Criar tabelas do BigLake no Cloud Storage

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

3. Expanda a opção more_vert Ações e clique em Criar tabela.

4. Na seção Origem, especifique os seguintes campos:

   1. Em Criar tabela de, selecione Google Cloud Storage.

   2. Em Selecionar arquivo do bucket do GCS ou usar um padrão de URI, procure para selecionar um bucket e um arquivo a ser usado ou digite o caminho no formato gs://bucket_name/[folder_name/]file_name.

      Não é possível especificar vários URIs no console do Google Cloud, mas é possível selecionar vários arquivos especificando um caractere curinga de asterisco (*). Por exemplo, gs://mybucket/file_name*. Para mais informações, consulte Compatibilidade de caracteres curinga com URIs do Cloud Storage.

      O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando.

   3. Em Formato do arquivo, selecione o formato que corresponde ao seu arquivo.

5. Na seção Destino, especifique os seguintes detalhes:

   1. Em Projeto, selecione o projeto em que a tabela será criada.

   2. Em Conjunto de dados, selecione o conjunto de dados em que a tabela será criada.

   3. Em Tabela, insira o nome da tabela que você está criando.

   4. Em Tipo de tabela, selecione Tabela externa.

   5. Selecione Criar uma tabela do BigLake usando uma conexão do Cloud Resource.

   6. Em ID da conexão, selecione a conexão que você criou anteriormente.

6. Se você tiver um arquivo de origem, na seção Esquema, ative a detecção automática de esquema ou especifique manualmente um esquema. Se você não tiver um arquivo de origem, especifique um esquema manualmente.

   • Para ativar a detecção automática de esquema, selecione a opção Detectar automaticamente.

   • Para especificar um esquema manualmente, deixe a opção Detectar automaticamente desmarcada. Ative Editar como texto e insira o esquema da tabela como uma matriz JSON.

7. Para ignorar linhas com valores de coluna extras que não correspondem ao esquema, expanda a seção Opções avançadas e selecione Valores desconhecidos.

8. Selecione 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.

SQL

Use a instrução DDL CREATE EXTERNAL TABLE. É possível especificar o esquema explicitamente ou usar a detecção automática de esquema para inferir o esquema a partir dos dados externos.

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
     WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
     OPTIONS (
       format ="TABLE_FORMAT",
       uris = ['BUCKET_PATH'[,...]],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE'
       );
   

   Substitua:

   • PROJECT_ID: o nome do projeto em que você quer criar a tabela, por exemplo, myproject
   • DATASET: o nome do conjunto de dados do BigQuery em que você quer criar a tabela (por exemplo, mydataset)
   • EXTERNAL_TABLE_NAME: o nome da tabela que você quer criar, por exemplo, mytable
   • REGION: a região que contém a conexão, por exemplo, us
   • CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

     Quando você visualiza os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

   • TABLE_FORMAT: o formato da tabela que você quer criar, por exemplo, PARQUET

     Para mais informações sobre os formatos compatíveis, consulte Limitações.

   • BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os dados da tabela externa, no formato ['gs://bucket_name/[folder_name/]file_name'].

     É possível selecionar vários arquivos do bucket especificando um caractere curinga de asterisco (*) no caminho. Por exemplo, ['gs://mybucket/file_name*']. 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/*.csv']
     • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

     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.

   • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

     Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

   • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

     Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

     Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

3. Clique em play_circle Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Opção 1: arquivo de definição da tabela

Use o comando bq mkdef para criar um arquivo de definição de tabela e, em seguida, transmita o caminho do arquivo para o comando bq mk da seguinte maneira:

bq mkdef \
    --connection_id=CONNECTION_ID \
    --source_format=SOURCE_FORMAT \
  BUCKET_PATH > DEFINITION_FILE

bq mk --table \
    --external_table_definition=DEFINITION_FILE \
    --max_staleness=STALENESS_INTERVAL \
    PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \
    SCHEMA

Substitua:

• CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

  Quando você visualiza os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

• SOURCE_FORMAT: o formato da fonte de dados externa. Por exemplo, PARQUET.

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

• DEFINITION_FILE: o caminho para o arquivo de definição de tabelas na máquina local.

• STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

  Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

  Para ativar o armazenamento em cache de metadados, especifique um valor de intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do tipo de dados INTERVAL. Por exemplo, especifique 0-0 0 4:0:0 para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

• DATASET: o nome do conjunto de dados do BigQuery em que você quer criar uma tabela, por exemplo, mydataset

• EXTERNAL_TABLE_NAME: o nome da tabela que você quer criar, por exemplo, mytable

• SCHEMA: o esquema da tabela do BigLake

Exemplo:

bq mkdef
    --connection_id=myconnection
    --metadata_cache_mode=CACHE_MODE
    --source_format=CSV 'gs://mybucket/*.csv' > mytable_def

bq mk
    --table
    --external_table_definition=mytable_def='gs://mybucket/*.csv'
    --max_staleness=0-0 0 4:0:0
    myproject:mydataset.mybiglaketable
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

Para usar a detecção automática de esquema, defina a sinalização --autodetect=true no comando mkdef e omita o esquema:

bq mkdef \
    --connection_id=myconnection \
    --metadata_cache_mode=CACHE_MODE \
    --source_format=CSV --autodetect=true \
    gs://mybucket/*.csv > mytable_def

bq mk \
    --table \
    --external_table_definition=mytable_def=gs://mybucket/*.csv \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable

Opção 2: definição da tabela inline

Em vez de criar um arquivo de definição de tabela, é possível transmitir a definição de tabela direto para o comando bq mk. Use o decorador @connection para especificar a conexão a ser usada no final do flag --external_table_definition.

bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

Substitua:

• 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 nome do projeto em que você quer criar a tabela, por exemplo, myproject

• REGION: a região que contém a conexão, us

• CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

  Quando você visualiza os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

• DATASET_NAME: o nome do conjunto de dados em que você quer criar a tabela do BigLake

• TABLE_NAME: o nome da tabela do BigLake

• SCHEMA: o esquema da tabela do BigLake

Exemplo:

bq mk --table \
    --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable \
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Chame o método de API tables.insert e crie um ExternalDataConfiguration no recurso Table que você transmite.

Especifique a propriedade schema ou defina a propriedade autodetect como true para ativar a detecção automática de esquema para fontes de dados compatíveis.

Especifique a propriedade connectionId para identificar a conexão que será usada para se conectar ao Cloud Storage.

Terraform

Neste exemplo, uma tabela do BigLake é criada em dados não particionados.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This queries the provider for project information.
data "google_project" "project" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.project.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding.
# This lets IAM permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with
# default expiration times for partitions and tables, a
# description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery Table with automatic metadata caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema = jsonencode([
    { "name" : "country", "type" : "STRING" },
    { "name" : "product", "type" : "STRING" },
    { "name" : "price", "type" : "INT64" }
  ])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/data/*"]
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [time_sleep.default]
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

   Faça as correções necessárias na configuração.

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

3. Clique em more_vert Acessar ações e depois em Criar tabela. O painel Criar tabela será aberto.

4. Na seção Origem, especifique os seguintes campos:

   1. Em Criar tabela de, selecione Google Cloud Storage.

   2. Forneça o caminho para a pasta usando caracteres curinga. Por exemplo, my_bucket/my_files*. A pasta precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.

   3. Na lista Formato de arquivo, selecione o tipo de arquivo.

   4. Marque a caixa de seleção Particionamento de dados de origem e especifique os seguintes detalhes:

      1. Em Selecionar prefixo do URI de origem, insira o prefixo de URI. Por exemplo, gs://my_bucket/my_files.
      2. Opcional: para exigir um filtro de partição em todas as consultas desta tabela, marque a caixa de seleção Exigir filtro de partição. A exigência de um filtro de partição pode reduzir custos e melhorar o desempenho. Para mais informações, consulte Como exigir filtros de predicado em chaves de partição em consultas.

      3. Na seção Modo de inferência de partição, selecione uma das seguintes opções:

         • Inferir automaticamente os tipos: defina o modo de detecção do esquema de partição como AUTO.
         • Todas as colunas são strings: defina o modo de detecção de esquema de partição como STRINGS.
         • Forneça meu próprio: defina o modo de detecção de esquema de partição como CUSTOM e insira manualmente as informações do esquema para as chaves de partição. Para mais informações, consulte Fornecer um esquema de chave de partição personalizado.

5. Na seção Destino, especifique os seguintes detalhes:

   1. Em Projeto, selecione o projeto em que você quer criar a tabela.
   2. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
   3. Em Tabela, insira o nome da tabela que você quer criar.
   4. Em Tipo de tabela, selecione Tabela externa.
   5. Marque a caixa de seleção Criar uma tabela do BigLake usando uma conexão do Recurso do Cloud.
   6. Em ID da conexão, selecione a conexão que você criou anteriormente.

6. Se você tiver um arquivo de origem, na seção Esquema, ative a detecção automática de esquema ou especifique manualmente um esquema. Se você não tiver um arquivo de origem, especifique um esquema manualmente.

   • Para ativar a detecção automática de esquema, selecione a opção Detectar automaticamente.

   • Para especificar um esquema manualmente, deixe a opção Detectar automaticamente desmarcada. Ative Editar como texto e insira o esquema da tabela como uma matriz JSON.

7. Para ignorar linhas com valores de coluna extras que não correspondem ao esquema, expanda a seção Opções avançadas e selecione Valores desconhecidos.

8. Selecione Criar tabela.

SQL

Use a instrução DDL CREATE EXTERNAL TABLE:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
   WITH PARTITION COLUMNS
   (
     PARTITION_COLUMN PARTITION_COLUMN_TYPE,
   )
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (
     hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
     uris=['FILE_PATH'],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE',
     format ="TABLE_FORMAT"
   );
   

   Substitua:

   • PROJECT_ID: o nome do projeto em que você quer criar a tabela, por exemplo, myproject
   • DATASET: o nome do conjunto de dados do BigQuery em que você quer criar a tabela (por exemplo, mydataset)
   • EXTERNAL_TABLE_NAME: o nome da tabela que você quer criar, por exemplo, mytable
   • PARTITION_COLUMN: o nome da coluna de particionamento.
   • PARTITION_COLUMN_TYPE: o tipo da coluna de particionamento
   • REGION: a região que contém a conexão, por exemplo, us.
   • CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

     Quando você visualiza os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

   • HIVE_PARTITION_URI_PREFIX: prefixo do URI de particionamento do Hive (por exemplo, gs://mybucket/)
   • FILE_PATH: caminho para a fonte de dados da tabela externa que você quer criar, por exemplo, gs://mybucket/*.parquet
   • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

     Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

   • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

     Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

     Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

   • TABLE_FORMAT: o formato da tabela que você quer criar, por exemplo, PARQUET

3. Clique em play_circle Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

Exemplos

O exemplo a seguir cria uma tabela do BigLake com base em dados particionados em que:

• O esquema é detectado automaticamente.
• O intervalo de inatividade do cache de metadados para a tabela é de 1 dia.
• O cache de metadados é atualizado automaticamente.

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

O exemplo a seguir cria uma tabela do BigLake com base em dados particionados em que:

• O esquema é especificado.
• O intervalo de inatividade do cache de metadados para a tabela é de 8 horas.
• O cache de metadados precisa ser atualizado manualmente.

CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName STRING,
  ProductType STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 8 HOUR,
  metadata_cache_mode = 'MANUAL'
);

bq

Primeiro, use o comando bq mkdef para criar um arquivo de definição de tabela:

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 GCS_URIS > DEFINITION_FILE

Substitua:

• SOURCE_FORMAT: o formato da fonte de dados externa. Por exemplo, CSV.
• REGION: a região que contém a conexão, por exemplo, us.

• CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

  Quando você visualiza os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

• PARTITIONING_MODE: o modo de particionamento do Hive. Use um dos seguintes valores:

  • AUTO: detecta automaticamente os nomes e tipos de chaves.
  • STRINGS: converte automaticamente os nomes das chaves em strings.
  • CUSTOM: codifique o esquema da chave no prefixo do URI de origem.

• GCS_URI_SHARED_PREFIX: o prefixo de URI de origem.

• BOOLEAN: especifica se um filtro de predicado é necessário no momento da consulta. Essa flag é opcional. O valor padrão é false.

• CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Você só precisa incluir essa sinalização se também planeja usar a sinalização --max_staleness no comando bq mk subsequente para ativar o armazenamento em cache de metadados. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

  Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

  Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

  Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

• GCS_URIS: o caminho para a pasta do Cloud Storage, usando o formato de caractere curinga

• DEFINITION_FILE: o caminho para o arquivo de definição de tabelas na máquina local.

Se PARTITIONING_MODE for CUSTOM, inclua o esquema da chave de partição no prefixo do URI de origem, usando este formato:

--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Depois de criar o arquivo de definição de tabela, use o comando bq mk para criar a tabela do BigLake:

bq mk --external_table_definition=DEFINITION_FILE \
--max_staleness=STALENESS_INTERVAL \
DATASET_NAME.TABLE_NAME \
SCHEMA

Substitua:

• DEFINITION_FILE: o caminho para o arquivo de definição da tabela.

• STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Se você incluir essa sinalização, também precisará especificar um valor para a sinalização --metadata_cache_mode no comando bq mkdef anterior. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

  Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

  Para ativar o armazenamento em cache de metadados, especifique um valor de intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do tipo de dados INTERVAL. Por exemplo, especifique 0-0 0 4:0:0 para um intervalo de inatividade de quatro horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

• DATASET_NAME: o nome do conjunto de dados onde está a tabela

• TABLE_NAME: o nome da tabela que você está criando;

• SCHEMA especifica um caminho para um arquivo de esquema JSON ou especifica o esquema no formato field:data_type,field:data_type,.... Para usar a detecção automática de esquema, omita esse argumento.

Exemplos

O exemplo a seguir usa o modo de particionamento AUTO do Hive e também define o cache de metadados para ter um intervalo de inatividade de 12 horas e para ser atualizado automaticamente:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  --max_staleness=0-0 0 12:0:0 \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

O exemplo a seguir usa o modo de particionamento do Hive STRING:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

O exemplo a seguir usa o modo de particionamento do Hive CUSTOM:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Para definir o particionamento do Hive usando a API do BigQuery, inclua o objeto hivePartitioningOptions no objeto ExternalDataConfiguration ao criar o arquivo de definição de tabela. Para criar uma tabela do BigLake, especifique também um valor para o campo connectionId.

Se você definir o campo hivePartitioningOptions.mode como CUSTOM, será necessário codificar o esquema da chave de partição no campo hivePartitioningOptions.sourceUriPrefix da seguinte maneira: gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Para aplicar o uso de um filtro de predicado no momento da consulta, defina o campo hivePartitioningOptions.requirePartitionFilter como true.

Terraform

Neste exemplo, uma tabela do BigLake é criada em dados particionados.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

# This creates a bucket in the US region named "my-bucket" with a pseudorandom
# suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

resource "google_storage_bucket_object" "default" {
  # This creates a fake message to create partition locations on the table.
  # Otherwise, the table deployment fails.
  name    = "publish/dt=2000-01-01/hr=00/min=00/fake_message.json"
  content = "{\"column1\": \"XXX\"}"
  bucket  = google_storage_bucket.default.name
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding. This lets IAM
# permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with default expiration times for
# partitions and tables, a description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery table with partitioning and automatic metadata
# caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema     = jsonencode([{ "name" : "column1", "type" : "STRING", "mode" : "NULLABLE" }])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/publish/*"]
    # This configures Hive partitioning for the BigQuery table,
    # partitioning the data by date and time.
    hive_partitioning_options {
      mode                     = "CUSTOM"
      source_uri_prefix        = "gs://${google_storage_bucket.default.name}/publish/{dt:STRING}/{hr:STRING}/{min:STRING}"
      require_partition_filter = false
    }
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [
    time_sleep.default,
    google_storage_bucket_object.default
  ]
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

   Faça as correções necessárias na configuração.

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

SQL

Use a instrução DDL CREATE OR REPLACE EXTERNAL TABLE para atualizar uma tabela:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   CREATE OR REPLACE EXTERNAL TABLE
     `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
     WITH CONNECTION `REGION.CONNECTION_ID`
     OPTIONS(
       format ="TABLE_FORMAT",
       uris = ['BUCKET_PATH'],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE'
       );
   

   Substitua:

   • PROJECT_ID: o nome do projeto que contém a tabela
   • DATASET: o nome do conjunto de dados onde está a tabela
   • EXTERNAL_TABLE_NAME: o nome da tabela
   • REGION: a região que contém a conexão
   • CONNECTION_ID: o nome da conexão a ser usada
   • TABLE_FORMAT: o formato usado pela tabela

     Não é possível mudar isso durante a atualização da tabela.

   • BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os dados da tabela externa, no formato ['gs://bucket_name/[folder_name/]file_name'].

     É possível selecionar vários arquivos do bucket especificando um caractere curinga de asterisco (*) no caminho. Por exemplo, ['gs://mybucket/file_name*']. 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/*.csv']
     • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

     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.

   • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela e quando eles precisam ser atualizados para que a operação possa usá-los.

     Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

     Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

   • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual.

     Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

     Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

     Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

3. Clique em play_circle Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use os comandos bq mkdef e bq update para atualizar uma tabela:

1. Gere uma definição de tabela externa que descreva os aspectos da tabela a serem alterados:

   bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
   --source_format=TABLE_FORMAT \
   --metadata_cache_mode=CACHE_MODE \
   "BUCKET_PATH" > /tmp/DEFINITION_FILE
   

   Substitua:

   • PROJECT_ID: o nome do projeto que contém a conexão.
   • REGION: a região que contém a conexão.
   • CONNECTION_ID: o nome da conexão a ser usada.
   • TABLE_FORMAT: o formato usado pela tabela. Não é possível mudar isso durante a atualização da tabela.

   • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

     Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

     Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

   • BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os dados da tabela externa, no formato gs://bucket_name/[folder_name/]file_name.

     É possível limitar os arquivos selecionados no bucket especificando um caractere curinga de asterisco (*) no caminho. Por exemplo, gs://mybucket/file_name*. 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/*.csv
     • gs://bucket/path1/*,gs://bucket/path2/file00*

     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.

   • DEFINITION_FILE: o nome do arquivo de definição de tabela que você está criando.

2. Atualize a tabela usando a nova definição de tabela externa:

   bq update --max_staleness=STALENESS_INTERVAL \
   --external_table_definition=/tmp/DEFINITION_FILE \
   PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME
   

   Substitua:

   • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela e quando eles precisam ser atualizados para que a operação possa usá-los. Para saber mais sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

     Para ativar o armazenamento em cache de metadados, especifique um valor de intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do tipo de dados INTERVAL. Por exemplo, especifique 0-0 0 4:0:0 para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

   • DEFINITION_FILE: o nome do arquivo de definição da tabela que você criou ou atualizou.

   • PROJECT_ID: o nome do projeto que contém a tabela.

   • DATASET: o nome do conjunto de dados onde está a tabela

   • EXTERNAL_TABLE_NAME: o nome da tabela

Exemplo

O exemplo a seguir atualiza mytable para usar metadados em cache, desde que tenha sido atualizado nas últimas 4,5 horas, e também para atualizar metadados armazenados em cache automaticamente:

bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable

Em que enable_metadata.json tem o seguinte conteúdo: { "metadataCacheMode": "AUTOMATIC" }