Como consultar dados do Cloud Storage

Com o BigQuery, é possível realizar a consulta de dados do Cloud Storage nos seguintes formatos:

  • Valores separados por vírgula (CSV, na sigla em inglês)
  • JSON (delimitado por nova linha)
  • Avro
  • ORC
  • Parquet
  • Exportações do Datastore
  • Exportações do Firestore

O BigQuery é compatível com a consulta de dados do Cloud Storage destas classes de armazenamento:

  • Padrão
  • Nearline
  • Coldline
  • Arquivo

Para consultar uma fonte de dados externa do Cloud Storage, forneça o caminho do URI do Cloud Storage para seus dados e crie uma tabela que faça referência a essa fonte. A tabela usada para fazer referência à fonte de dados do Cloud Storage pode ser permanente ou temporária.

Considere a localização do seu conjunto de dados e do intervalo do Cloud Storage ao consultar dados armazenados nele.

Como recuperar o URI do Cloud Storage

Para criar uma tabela externa usando uma fonte de dados do Cloud Storage, você precisa fornecer o URI dele.

O URI do Cloud Storage contém o nome do intervalo e o objeto (nome do arquivo). Por exemplo, se o intervalo do Cloud Storage se chamar mybucket e o arquivo de dados for denominado myfile.csv, o URI do intervalo será gs://mybucket/myfile.csv. Caso os dados estejam separados em vários arquivos, use um caractere curinga no URI. Para mais informações, consulte URIs de solicitação do Cloud Storage.

O BigQuery não é compatível com URIs de origem que incluam várias barras consecutivas após a barra dupla inicial. Os nomes de objeto do Cloud Storage podem conter vários caracteres de barra ("/") consecutivos. No entanto, o BigQuery os converte em uma única barra. Por exemplo, ainda que válido no Cloud Storage, este URI de origem não funciona no BigQuery: gs://bucket/my//object//name.

Para recuperar o URI do Cloud Storage:

  1. Abra o Console do Cloud Storage.

    Console do Cloud Storage

  2. Procure a localização do objeto (arquivo) que contém os dados de origem.

  3. Na parte superior do Console do Cloud Storage, anote o caminho para o objeto. Para escrever o URI, substitua gs://bucket/file pelo caminho apropriado, como por exemplo, gs://mybucket/myfile.json. bucket é o nome do intervalo do Cloud Storage e file é o nome do objeto (arquivo) que contém os dados.

Tabelas externas permanentes x temporárias

É possível consultar uma fonte de dados externa no BigQuery usando uma tabela permanente ou uma temporária. Uma tabela permanente é criada em um conjunto de dados e vinculada à sua fonte de dados externa. Como a tabela é permanente, é possível usar controles de acesso para compartilhá-la com outras pessoas que também têm acesso à fonte de dados externa subjacente e pode consultá-la a qualquer momento.

Ao consultar uma fonte de dados externa usando uma tabela temporária, você envia um comando que inclui uma consulta e cria uma tabela não permanente vinculada a essa fonte. A tabela temporária não é criada em um dos conjuntos de dados do BigQuery. Como ela não fica armazenada de modo permanente em um conjunto de dados, não é possível compartilhá-la com outras pessoas. A consulta em uma fonte de dados externa usando uma tabela temporária é útil no caso de consultas ad hoc únicas em dados externos ou para extrair, transformar e carregar (ETL) processos.

Como consultar dados do Cloud Storage usando tabelas externas permanentes

Permissões e escopos necessários

Ao consultar dados externos no Cloud Storage usando uma tabela permanente, você precisa de permissões para executar um job de consulta para envolvidos no projeto ou indivíduos em níveis superiores, criar uma tabela que aponte para os dados externos e acessar as informações da tabela. Quando os dados externos são armazenados no Cloud Storage, também é necessário ter permissões para acessá-los no intervalo do Cloud Storage.

Permissões do BigQuery

Para criar e consultar uma tabela externa no BigQuery, é preciso ter, no mínimo, as seguintes permissões.

  • bigquery.tables.create
  • bigquery.tables.getData
  • bigquery.jobs.create

Os seguintes papéis predefinidos do Cloud IAM incluem permissões bigquery.tables.create e bigquery.tables.getData:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Os seguintes papéis predefinidos do Cloud IAM incluem permissões bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário crie tabelas externas no conjunto de dados, mas ainda são necessárias permissões bigquery.jobs.create para consultar as informações.

Para mais informações sobre os papéis e permissões do Cloud IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões do Cloud Storage

Para consultar dados externos em um intervalo do Cloud Storage, é preciso ter as permissões storage.objects.get. Se você estiver usando um caractere curinga de URI, também precisará ter permissões storage.objects.list.

O papel predefinido storage.objectViewer do Cloud IAM concede as permissões storage.objects.get e storage.objects.list.

Escopos para instâncias do Compute Engine

Ao criar uma instância do Compute Engine, é possível especificar uma lista de escopos para ela. Os escopos controlam o acesso da instância aos produtos do GCP, incluindo o Cloud Storage. Os aplicativos executados na VM usam a conta de serviço anexada à instância para chamar APIs do Google Cloud.

Se você tiver configurado uma instância do Compute Engine para ser executada como a conta de serviço padrão do Compute Engine e essa conta acessar uma tabela externa vinculada a uma fonte de dados do Cloud Storage, a instância solicitará acesso somente leitura ao Cloud Storage. A conta de serviço padrão do Compute Engine recebe automaticamente o escopo https://www.googleapis.com/auth/devstorage.read_only. Se você criar sua própria conta de serviço, aplique o escopo de somente leitura do Cloud Storage à instância.

Para mais informações sobre como aplicar escopos a uma instância do Compute Engine, consulte Como alterar a conta de serviço e os escopos de acesso de uma instância. Acesse Contas de serviço para saber mais sobre esse tipo de conta do Compute Engine.

Como criar e consultar uma tabela externa permanente

É possível criar uma tabela permanente vinculada à sua fonte de dados externa da seguinte forma:

  • Usando o Console do Cloud ou a IU da Web clássica do BigQuery.
  • Usando o comando mk da ferramenta de linha de comando
  • Criando um ExternalDataConfiguration ao usar o método de API tables.insert
  • Use bibliotecas de cliente

Para consultar uma fonte de dados externa usando uma tabela permanente, crie a tabela em um conjunto de dados do BigQuery vinculado a essa fonte. Os dados não ficam armazenados na tabela do BigQuery. Como a tabela é permanente, é possível usar controles de acesso para compartilhá-la com outras pessoas que também têm acesso à fonte de dados externa subjacente.

Existem três maneiras de especificar informações de esquema ao criar uma tabela externa permanente no BigQuery:

  • Se você estiver usando o método da API tables.insert para criar uma tabela externa permanente, criará um recurso de tabela que inclui uma definição de esquema e uma ExternalDataConfiguration. Defina o parâmetro autodetect como true para ativar a detecção automática de esquema para fontes de dados compatíveis.
  • Se você está usando a CLI para criar uma tabela externa permanente, é possível usar um arquivo de definição de tabela, criar e usar seu próprio arquivo de esquema ou inserir o esquema in-line (na linha de comando). Ao criar um arquivo de definição de tabela, é possível ativar a detecção automática de esquema para fontes de dados compatíveis.
  • Se você está usando o console ou a IU clássica da Web do BigQuery para criar uma tabela externa permanente, insira o esquema da tabela manualmente ou use a detecção automática de esquemas para fontes de dados compatíveis.

Para criar uma tabela externa:

Console

  1. Abra a IU da Web do BigQuery no Console do Cloud.
    Acessar o Console do Cloud
  2. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.
  3. Clique em Criar tabela no lado direito da janela. Criar tabela
  4. Na página Criar tabela, na seção Origem:

    • Em Criar tabela de, selecione "Cloud Storage".

    • No campo Selecionar arquivo do intervalo do Cloud Storage, procure esse intervalo/arquivo ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no Console do Cloud, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela sendo criada.

      Selecionar arquivo

    • Em Formato do arquivo, selecione o formato dos dados. As opções válidas para dados do Cloud Storage podem ser as seguintes:

      • Valores separados por vírgula (CSV, na sigla em inglês)
      • JSON (delimitado por nova linha)
      • Avro
      • Backup do Datastore (também usado para o Firestore)
  5. Na página Criar tabela, na seção Destino:

    • Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.

      Selecionar conjunto de dados

    • Verifique se o Tipo de tabela está definido como Tabela externa.

    • No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.

  6. Na seção Esquema, insira a definição do esquema.

    • Em arquivos JSON ou CSV, marque a opção Detectar automaticamente para ativar a detecção automática de esquemas. A detecção automática não está disponível para arquivos Avro e exportações do Datastore e do Firestore. As informações de esquema para esses tipos de arquivo são recuperadas automaticamente dos dados de origem autodescritivos.
    • Em arquivos CSV e JSON, é possível inserir informações do esquema manualmente seguindo um destes procedimentos:
      • Ative Editar como texto e insira o esquema da tabela como uma matriz JSON. Observação: para ver o esquema de uma tabela no formato JSON, insira este comando de CLI: bq show --format=prettyjson dataset.table.
      • Use Adicionar campo para inserir manualmente o esquema.
  7. Clique em Criar tabela.

Após a criação da tabela permanente, é possível executar uma consulta na tabela como se ela fosse nativa do BigQuery. Após a conclusão da consulta, será possível exportar os resultados como arquivos CSV ou JSON, salvá-los como uma tabela ou nas Planilhas Google.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, passe o cursor do mouse sobre um conjunto de dados, clique no ícone de seta para baixo imagem do ícone de seta para baixo e selecione Criar nova tabela.

  3. Na página Criar tabela, na seção Dados de origem:

    • Em Local, selecione Cloud Storage e, no campo de origem, insira o URI do Cloud Storage. Os caracteres curinga são compatíveis com URIs do Cloud Storage.
    • Em Formato do arquivo, selecione o formato dos dados. Estes são os formatos válidos para dados do Cloud Storage:
      • Valores separados por vírgula (CSV)
      • JSON (delimitado por nova linha)
      • Avro
      • Backup do Datastore (também usado para o Firestore)
  4. Na seção Tabela de destino da página Criar tabela, faça isto:

    • Em Nome da tabela, escolha o conjunto de dados apropriado e, no campo apropriado, insira o nome da tabela permanente a ser criada no BigQuery.
    • Verifique se o Tipo de tabela está definido como Tabela externa.
  5. Na seção Esquema, insira as informações:

    • Em arquivos JSON ou CSV, marque a opção Detectar automaticamente para ativar a detecção automática de esquema. A detecção automática não está disponível para arquivos Avro e exportações do Datastore e do Firestore. As informações de esquema para esses tipos de arquivo são recuperadas automaticamente dos dados de origem autodescritivos.

    • Outra opção é inserir informações de esquema CSV ou JSON manualmente:

      • Clique em Editar como texto e insira o esquema da tabela no formato JSON.
      • Use Adicionar campo para inserir manualmente o esquema.
  6. Selecione os itens aplicáveis na seção Opções e clique em Criar tabela.

Após a criação da tabela permanente, é possível executar uma consulta na tabela como se ela fosse nativa do BigQuery. Após a conclusão da consulta, será possível exportar os resultados como arquivos CSV ou JSON, salvá-los como uma tabela ou nas Planilhas Google.

CLI

Crie uma tabela na ferramenta de linha de comando do BigQuery usando o comando bq mk. Ao usar a CLI para criar uma tabela vinculada a uma fonte de dados externa, identifique o esquema dessa tabela usando:

  • um arquivo de definição de tabela (armazenado em sua máquina local);
  • uma definição de esquema in-line;
  • um arquivo de esquema JSON (armazenado em sua máquina local).

Para criar uma tabela permanente vinculada à fonte de dados do Cloud Storage usando um arquivo de definição de tabela, insira o seguinte comando:

bq mk \
--external_table_definition=definition_file \
dataset.table

Onde:

  • definition_file é o caminho para o arquivo de definição de tabela na sua máquina local;
  • dataset é o nome do conjunto de dados que contém a tabela;
  • table é o nome da tabela que você está criando.

Por exemplo, o comando a seguir cria uma tabela permanente chamada mytable usando um arquivo de definição de tabela chamado mytable_def.

bq mk --external_table_definition=/tmp/mytable_def mydataset.mytable

Para criar uma tabela permanente vinculada à sua fonte de dados externa usando uma definição de esquema in-line, digite o seguinte comando.

bq mk \
--external_table_definition=schema@source_format=Cloud Storage URI \
dataset.table

Onde:

  • schema é a definição do esquema no formato field:data_type,field:data_type;
  • source_format é CSV, NEWLINE_DELIMITED_JSON, AVRO ou DATASTORE_BACKUP (DATASTORE_BACKUP também é usado para o Filestore);
  • Cloud Storage URI é o URI do Cloud Storage;
  • dataset é o nome do conjunto de dados que contém a tabela;
  • table é o nome da tabela que você está criando.

Por exemplo, o comando a seguir cria uma tabela permanente chamada sales vinculada a um arquivo CSV armazenado no Cloud Storage com a seguinte definição de esquema: Region:STRING,Quarter:STRING,Total_sales:INTEGER.

bq mk \
--external_table_definition=Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv \
mydataset.sales

Para criar uma tabela permanente vinculada à sua fonte de dados externa usando um arquivo de esquema JSON, digite o seguinte comando:

bq mk \
--external_table_definition=schema@source_format=Cloud Storage URI \
dataset.table

Onde:

  • schema é o caminho para o arquivo de esquema JSON na máquina local.
  • source_format é CSV, NEWLINE_DELIMITED_JSON, AVRO ou DATASTORE_BACKUP (DATASTORE_BACKUP também é usado para o Firestore);
  • Cloud Storage URI é o URI do Cloud Storage;
  • dataset é o nome do conjunto de dados que contém a tabela;
  • table é o nome da tabela que você está criando.

Por exemplo, o comando a seguir cria uma tabela chamada sales vinculada a um arquivo CSV armazenado no Cloud Storage usando o arquivo de esquema /tmp/sales_schema.json.

bq mk \
--external_table_definition=/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv \
mydataset.sales

Após a criação da tabela permanente, é possível executar uma consulta na tabela como se ela fosse nativa do BigQuery. Após a conclusão da consulta, será possível exportar os resultados como arquivos CSV ou JSON, salvá-los como uma tabela ou nas Planilhas Google.

API

Crie uma ExternalDataConfiguration quando utilizar o método de API tables.insert. Especifique a property schema ou defina a property autodetect como true para ativar a detecção automática de esquema para fontes de dados compatíveis.

Python

Antes de testar esta amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Python (em inglês).

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

# Configure the external data source
dataset_ref = client.dataset(dataset_id)
table_id = "us_states"
schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
table = bigquery.Table(dataset_ref.table(table_id), schema=schema)
external_config = bigquery.ExternalConfig("CSV")
external_config.source_uris = [
    "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
]
external_config.options.skip_leading_rows = 1  # optionally skip header row
table.external_data_configuration = external_config

# Create a permanent table linked to the GCS file
table = client.create_table(table)  # API request

# Example query to find states starting with 'W'
sql = 'SELECT * FROM `{}.{}` WHERE name LIKE "W%"'.format(dataset_id, table_id)

query_job = client.query(sql)  # API request

w_states = list(query_job)  # Waits for query to finish
print("There are {} states with names starting with W.".format(len(w_states)))

Consulta de dados do Cloud Storage usando tabelas temporárias

Para consultar uma fonte de dados externa sem criar uma tabela permanente, execute um comando para combinar:

  • um arquivo de definição de tabela com uma consulta;
  • uma definição de esquema in-line com uma consulta;
  • um arquivo de definição de esquema JSON com uma consulta.

O arquivo de definição de tabela ou esquema fornecido é usado para criar a tabela externa temporária, e a consulta será executada nela. Na CLI e na API do BigQuery, é permitido consultar uma fonte de dados externa usando uma tabela temporária.

A tabela externa temporária não é criada em um dos conjuntos de dados do BigQuery. Como ela não fica armazenada permanentemente em um conjunto de dados, não é possível compartilhá-la com outros. A consulta a uma fonte de dados externa usando uma tabela temporária é útil quando você quer consultar dados externos apenas uma vez, com um propósito específico, ou executar processos de Extração, transformação e carregamento (ETL).

Permissões necessárias

Ao consultar dados externos no Cloud Storage usando uma tabela temporária, você precisa de permissões para executar um job de consulta no nível do projeto ou superior, acesso ao conjunto de dados contendo uma tabela que aponte para os dados externos. Ao consultar dados no Cloud Storage, você também precisa de permissões para acessar o bucket que contém seus dados.

Permissões do BigQuery

Para consultar uma tabela externa no BigQuery usando uma tabela temporária, é necessário ter, no mínimo, as seguintes permissões.

  • bigquery.tables.getData
  • bigquery.jobs.create

Os papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.tables.getData:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Os seguintes papéis predefinidos do Cloud IAM incluem permissões bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário crie e acesse tabelas externas no conjunto de dados, mas as permissões bigquery.jobs.create ainda são necessárias para consultar os dados.

Para mais informações sobre os papéis e permissões do Cloud IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões do Cloud Storage

Para consultar dados externos em um intervalo do Cloud Storage, é preciso ter as permissões storage.objects.get. Se você estiver usando um caractere curinga de URI, também precisará ter permissões storage.objects.list.

O papel predefinido storage.objectViewer do Cloud IAM concede as permissões storage.objects.get e storage.objects.list.

Como criar e consultar uma tabela temporária

É possível criar e consultar uma tabela temporária vinculada a uma fonte de dados externa usando a CLI, a API ou as bibliotecas de cliente.

CLI

Consulte uma tabela temporária vinculada a uma fonte de dados externa usando o comando bq query com a sinalização --external_table_definition. Ao usar a CLI para consultar uma tabela temporária vinculada a uma fonte de dados externa, identifique o esquema dessa tabela usando:

  • um arquivo de definição de tabela (armazenado em sua máquina local);
  • uma definição de esquema in-line;
  • um arquivo de esquema JSON (armazenado em sua máquina local).

(Opcional) Forneça a sinalização --location e defina o valor do local.

Para consultar uma tabela temporária vinculada à sua fonte de dados externa usando um arquivo de definição de tabela, digite o seguinte comando:

bq --location=location query \
--external_table_definition=table::definition_file \
'query'

Onde:

  • location é o nome do seu local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • table é o nome da tabela temporária que você está criando;
  • definition_file é o caminho para o arquivo de definição de tabela na sua máquina local;
  • query é a consulta que você está enviando para a tabela temporária.

Por exemplo, o comando a seguir cria e consulta uma tabela temporária chamada sales usando um arquivo de definição de tabela chamado sales_def.

bq query \
--external_table_definition=sales::sales_def \
'SELECT
  Region,
  Total_sales
FROM
  sales'

Para consultar uma tabela temporária vinculada à sua fonte de dados externa usando uma definição de esquema in-line, digite o seguinte comando.

bq --location=location query \
--external_table_definition=table::schema@source_format=Cloud Storage URI \
'query'

Onde:

  • location é o nome do seu local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • table é o nome da tabela temporária que você está criando;
  • schema é a definição do esquema inline no formato field:data_type,field:data_type;
  • source_format é CSV, NEWLINE_DELIMITED_JSON, AVRO ou DATASTORE_BACKUP (DATASTORE_BACKUP também é usado para o Firestore);
  • Cloud Storage URI é o URI do Cloud Storage;
  • query é a consulta que você está enviando para a tabela temporária.

Por exemplo, o comando a seguir cria e consulta uma tabela temporária chamada sales vinculada a um arquivo CSV armazenado no Cloud Storage com a seguinte definição de esquema: Region:STRING,Quarter:STRING,Total_sales:INTEGER.

bq query \
--external_table_definition=sales::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv \
'SELECT
  Region,
  Total_sales
FROM
  sales'

Para consultar uma tabela temporária vinculada à sua fonte de dados externa usando um arquivo de esquema JSON, digite o seguinte comando:

bq --location=location query \
--external_table_definition=schema_file@source_format=Cloud Storage URI \
'query'

Onde:

  • location é o nome do seu local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • schema_file é o caminho para o arquivo de esquema JSON na sua máquina local;
  • source_format é CSV, NEWLINE_DELIMITED_JSON, AVRO ou DATASTORE_BACKUP (DATASTORE_BACKUP também é usado para o Firestore);
  • Cloud Storage URI é o URI do Cloud Storage;
  • query é a consulta que você está enviando para a tabela temporária.

Por exemplo, o comando a seguir cria e consulta uma tabela temporária chamada sales vinculada a um arquivo CSV armazenado no Cloud Storage usando o arquivo de esquema /tmp/sales_schema.json.

bq query
--external_table_definition=sales::/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv
'SELECT Region, Total_sales FROM sales'

API

Python

Antes de testar esta amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Python (em inglês).

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# Configure the external data source and query job.
external_config = bigquery.ExternalConfig("CSV")
external_config.source_uris = [
    "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
]
external_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
external_config.options.skip_leading_rows = 1
table_id = "us_states"
job_config = bigquery.QueryJobConfig(table_definitions={table_id: external_config})

# Example query to find states starting with 'W'.
sql = 'SELECT * FROM `{}` WHERE name LIKE "W%"'.format(table_id)

query_job = client.query(sql, job_config=job_config)  # Make an API request.

w_states = list(query_job)  # Wait for the job to complete.
print("There are {} states with names starting with W.".format(len(w_states)))

Como consultar dados particionados externamente

Consulte as instruções para consultar dados do Cloud Storage particionados externamente.

Compatibilidade com caracteres curinga para URIs do Cloud Storage

Se os dados do Cloud Storage estiverem separados em vários arquivos que compartilham um nome de base comum, é possível usar um caractere curinga no URI do arquivo de definição de tabela. Você também pode usar um caractere curinga ao criar uma tabela externa sem usar um arquivo de definição de tabela.

Para adicionar um caractere curinga ao URI do Cloud Storage, adicione um asterisco (*) ao nome de base. Por exemplo, se você tiver dois arquivos chamados fed-sample000001.csv e fed-sample000002.csv, o URI do intervalo será gs://mybucket/fed-sample*. Esse URI de caractere curinga pode ser usado no console, na IU da Web clássica, na CLI, na API ou nas bibliotecas de cliente.

Só é possível usar um caractere curinga para objetos (nomes de arquivos) no intervalo. O caractere curinga pode ser exibido dentro ou no final do nome do objeto. Não é possível anexar um caractere curinga ao nome do intervalo.

Nas exportações do Google Datastore, só é possível especificar um URI, que precisa terminar com .backup_info ou .export_metadata.

O caractere curinga * não é permitido ao:

  • criar tabelas externas vinculadas a exportações do Datastore ou do Firestore;
  • carregar dados de exportação do Datastore ou do Firestore a partir do Cloud Storage.

A pseudocoluna _FILE_NAME

Tabelas baseadas em fontes de dados externas fornecem uma pseudocoluna denominada _FILE_NAME. Ela contém o caminho totalmente qualificado para o arquivo ao qual a linha pertence. Essa coluna está disponível apenas para tabelas que fazem referência a dados externos armazenados no Cloud Storage e no Google Drive.

O nome de coluna _FILE_NAME é reservado. Por isso, não crie nenhuma coluna com esse nome nas tabelas. Para selecionar o valor de _FILE_NAME, use um alias. A consulta de exemplo abaixo mostra a seleção de _FILE_NAME ao atribuir o alias fn na pseudocoluna.

bq query \
--project_id=project_id \
--use_legacy_sql=false \
'SELECT
   name,
   _FILE_NAME AS fn
 FROM
   `dataset.table_name`
 WHERE
   name contains "Alex"' 

Onde:

  • project_id é um ID de projeto válido. Essa sinalização não será necessária se você usar o Cloud Shell ou configurar um projeto padrão no SDK do Cloud.
  • dataset é o nome do conjunto de dados que armazena a tabela externa permanente;
  • table_name é o nome da tabela externa permanente.