Consultar dados do Cloud Storage em tabelas do BigLake

Neste documento, descrevemos como consultar dados armazenados em uma tabela BigLake do Cloud Storage.

Antes de começar

Verifique se você tem uma tabela do Cloud Storage BigLake.

Papéis obrigatórios

Para consultar tabelas do BigLake do Cloud Storage, verifique se você tem os seguintes papéis:

Leitor de dados do BigQuery (roles/bigquery.dataViewer)
Usuário do BigQuery (roles/bigquery.user)

Dependendo das suas permissões, é possível conceder esses papéis a você mesmo ou pedir ao administrador para concedê-los. Para mais informações sobre como conceder papéis, consulte Como visualizar os papéis atribuíveis em recursos.

Para ver as permissões exatas que são necessárias para consultar as tabelas do BigLake do Cloud Storage, expanda a seção Permissões necessárias:

Permissões necessárias

bigquery.jobs.create
bigquery.readsessions.create: obrigatório apenas se você estiver lendo dados com a API BigQuery Storage Read
bigquery.tables.get
bigquery.tables.getData

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Consultar tabelas do BigLake

Depois de criar uma tabela do BigLake no Cloud Storage, consulte a sintaxe do GoogleSQL, como se ela fosse uma tabela padrão do BigQuery. Por exemplo, SELECT field1, field2 FROM mydataset.my_cloud_storage_table;.

Consultar tabelas do BigLake usando ferramentas externas de processamento de dados

É possível usar os conectores do BigQuery com outras ferramentas de processamento de dados para acessar as tabelas do BigLake no Cloud Storage. Para mais informações, consulte Conectores.

Apache Spark

O exemplo a seguir usa o Dataproc, mas também funciona com qualquer implantação do Spark que usa o conector Spark-BigQuery.

Neste exemplo, você fornece o conector Spark-BigQuery como uma ação de inicialização ao criar um cluster. Essa ação permite que você use um notebook Zeppelin e exercite a jornada do usuário de analista de dados.

As versões do conector Spark-BigQuery estão listadas no repositório do GitHub GoogleCloudDataproc/spark-bigquery-connector.

Crie um cluster de nó único usando a ação de inicialização do conector Spark-BigQuery:

gcloud dataproc clusters create biglake-demo-cluster \
    --optional-components=ZEPPELIN \
    --region=REGION \
    --enable-component-gateway \
    --single-node \
    --initialization-actions gs://goog-dataproc-initialization-actions-REGION/connectors/connectors.sh \
    --metadata spark-bigquery-connector-url= gs://spark-lib/bigquery/spark-bigquery-with-dependencies_SCALA_VERSION-CONNECTOR_VERSION.jar

Apache Hive

No exemplo a seguir, usamos o Dataproc, mas ele também funciona com qualquer implantação do Hive que usa o conector Hive-BigQuery.

Neste exemplo, você fornece o conector Hive-BigQuery como uma ação de inicialização ao criar um cluster.

As versões do conector Hive-BigQuery estão listadas no repositório do GitHub GoogleCloudDataproc/hive-bigquery-connector.

Crie um cluster de nó único usando a ação de inicialização do conector Hive-BigQuery:

gcloud dataproc clusters create biglake-hive-demo-cluster \
    --region=REGION \
    --single-node \
    --initialization-actions gs://goog-dataproc-initialization-actions-REGION/connectors/connectors.sh \
    --metadata hive-bigquery-connector-url=gs://goog-dataproc-artifacts-REGION/hive-bigquery/hive-bigquery-connector-CONNECTOR_VERSION.jar

Para mais informações sobre o conector Hive-BigQuery, consulte Usar o conector Hive-BigQuery.

Dataflow

Para ler as tabelas do BigLake no Dataflow, use o conector do Dataflow no modo DIRECT_READ para usar a API BigQuery Storage. A leitura de uma string de consulta também é compatível. Consulte BigQuery I/O na documentação do Apache Beam.

Consultar tabelas temporárias do BigLake

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).

Para consultar uma fonte de dados externa sem criar uma tabela permanente, forneça uma definição de tabela para a tabela temporária e use-a em um comando ou uma chamada para consultar a tabela temporária. É possível fornecer a definição da tabela de uma destas maneiras:

Um arquivo de definição da tabela
uma definição de esquema in-line;
Um arquivo de esquema JSON

O arquivo de definição de tabela ou esquema fornecido é usado para criar a tabela externa temporária, e a consulta será executada nela.

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.

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

bq

Use o comando bq query com a sinalização--external_table_definition.

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'

Substitua:

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 tabelas na 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@us.myconnection \
'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=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
'query'

Substitua:

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 de esquema in-line no formato field:data_type,field:data_type
SOURCE_FORMAT: o formato da fonte de dados externa, por exemplo, CSV.
BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os dados da tabela, no formato gs://bucket_name/[folder_name/]file_pattern.

É possível selecionar vários arquivos do bucket especificando um caractere curinga de asterisco (*) no file_pattern. Por exemplo, gs://mybucket/file00*.parquet. Para mais informações, consulte Compatibilidade de caracteres curinga com URIs do Cloud Storage.

É possível especificar vários buckets para a opção uris fornecendo múltiplos caminhos.

Os exemplos a seguir mostram valores uris válidos:
- gs://bucket/path1/myfile.csv
- gs://bucket/path1/*.parquet
- gs://bucket/path1/file1*, gs://bucket1/path1/*
Quando você especifica valores uris voltados para vários arquivos, todos eles precisam compartilhar um esquema compatível.

Para mais informações sobre o uso de URIs do Cloud Storage no BigQuery, consulte Caminho do recurso do Cloud Storage.
PROJECT_ID: o projeto que contém a conexão.
REGION: a região que contém a conexão, por exemplo, us.
CONNECTION_ID: o nome da conexão. Por exemplo, myconnection.
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@us.myconnection \
'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=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
'QUERY'

Substitua:

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 máquina local
SOURCE_FORMAT: o formato da fonte de dados externa, por exemplo, CSV.
BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os dados da tabela, no formato gs://bucket_name/[folder_name/]file_pattern.

É possível selecionar vários arquivos do bucket especificando um caractere curinga de asterisco (*) no file_pattern. Por exemplo, gs://mybucket/file00*.parquet. Para mais informações, consulte Compatibilidade de caracteres curinga com URIs do Cloud Storage.

É possível especificar vários buckets para a opção uris fornecendo múltiplos caminhos.

Os exemplos a seguir mostram valores uris válidos:
- gs://bucket/path1/myfile.csv
- gs://bucket/path1/*.parquet
- gs://bucket/path1/file1*, gs://bucket1/path1/*
Quando você especifica valores uris voltados para vários arquivos, todos eles precisam compartilhar um esquema compatível.

Para mais informações sobre o uso de URIs do Cloud Storage no BigQuery, consulte Caminho do recurso do Cloud Storage.
PROJECT_ID: o projeto que contém a conexão.
REGION: a região que contém a conexão, por exemplo, us.
CONNECTION_ID: o nome da conexão. Por exemplo, myconnection.
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@us.myconnection \
  'SELECT
      Region,
      Total_sales
    FROM
      sales'

API

Para executar uma consulta usando a API, siga estas etapas:

Criar um objeto Job.
Preencha a seção configuration do objeto Job com um objeto JobConfiguration.
Preencha a seção query do objeto JobConfiguration com um objeto JobConfigurationQuery.
Preencha a seção tableDefinitions do objeto JobConfigurationQuery com um objeto ExternalDataConfiguration. Especifique a conexão a ser usada para se conectar ao Cloud Storage no campo connectionId.
Chame o método jobs.insert para executar a consulta de forma assíncrona ou o método jobs.query para executar a consulta de forma síncrona, transmitindo no objeto Job.

A seguir

Saiba mais sobre como usar o SQL no BigQuery.
Saiba mais sobre as tabelas BigLake.
Saiba mais sobre as cotas do BigQuery.