Criar uma tabela

O catálogo do ambiente de execução do Lakehouse permite criar tabelas do Apache Iceberg no Cloud Storage que podem ser consultadas e modificadas no BigQuery, no Apache Spark, no Trino e na API REST do Iceberg. Quando você cria uma tabela sem especificar um caminho de armazenamento explícito, o catálogo do ambiente de execução do Lakehouse coloca automaticamente os metadados e os diretórios de dados no local padrão do Cloud Storage do endpoint do catálogo, anexando os identificadores de namespace e tabela.

Para registrar uma tabela do Apache Iceberg sem criar novos diretórios de armazenamento, consulte Registrar uma tabela.

Antes de começar

  1. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  2. Ative a API BigLake, se ainda não tiver feito isso.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  3. Configure o catálogo do ambiente de execução do Lakehouse com o endpoint do catálogo REST do Apache Iceberg. Para ativar o gerenciamento automático de tabelas, verifique se o catálogo usa o modo de venda de credenciais.

Funções exigidas

Para receber as permissões necessárias para criar uma tabela, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto e no bucket de armazenamento:

  • Criar uma tabela:
    • Administrador do BigLake (roles/biglake.admin): seu projeto
    • Administrador do Storage (roles/storage.admin): o bucket do Cloud Storage de destino

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Se o endpoint do catálogo usar o modo de venda de credenciais e os buckets do Cloud Storage forem protegidos por um perímetro de serviço do VPC Service Controls, você também precisará configurar uma regra de entrada para a conta de serviço do endpoint do catálogo antes de criar tabelas. Para mais informações, consulte Usar o VPC Service Controls com a venda de credenciais.

Recursos e suporte de tabelas

Ao usar tabelas no catálogo do ambiente de execução do Lakehouse, é útil entender os diferentes tipos de tabela e os recursos de ativação deles. Para saber mais sobre como usar as tabelas do Apache Iceberg, consulte Visão geral das tabelas do Apache Iceberg.

Tabelas do Iceberg compatíveis

Somente as tabelas Apache Iceberg V2 (GA) e V3 (pré-lançamento) são compatíveis. As tabelas do Iceberg V1 não são compatíveis. Para fazer upgrade das tabelas V1 atuais, consulte Fazer upgrade das tabelas do Iceberg V1 para V2.

Usar opções de tabela (pré-lançamento)

É possível ativar o uso de recursos gerenciados pelo BigQuery, como a linguagem de manipulação de dados (DML) do BigQuery e o gerenciamento automático de tabelas, configurando propriedades de tabela específicas. Esses recursos são ativados de maneiras diferentes, dependendo de onde a tabela é criada:

  • Do BigQuery: a DML do BigQuery e o gerenciamento automático de tabelas são ativados por padrão.
  • De mecanismos de código aberto: para ativar, é preciso configurar explicitamente as propriedades da tabela. Para mais informações, consulte Configurar opções de tabela.

Criar uma tabela

Criar uma tabela do Apache Iceberg. Para ativar o gerenciamento automático de tabelas (gcp.biglake.table-management.enabled), o catálogo precisa usar o modo de venda de credenciais.

Console

  1. No console do Google Cloud , acesse a página Lakehouse.

    Acessar o Lakehouse

  2. Selecione um catálogo ou crie um, se não tiver.

  3. Selecione um namespace ou crie um, se não tiver.

  4. Na página Detalhes do namespace, clique em Criar tabela. O painel Criar tabela será aberto.

  5. Em Formato da tabela, verifique se Iceberg está selecionado.

  6. Em Nome da tabela, insira um nome exclusivo.

  7. Opcional: para substituir o local padrão da tabela, no campo Local, insira um caminho do Cloud Storage no local do namespace.

  8. Na seção Esquema, defina o esquema da tabela:

    • Para adicionar colunas individualmente, clique em Adicionar campo. No campo Nome do campo, insira um nome de coluna e, na lista Tipo, selecione um tipo de dados.
    • Para inserir um esquema como texto, clique no botão Editar como texto para a posição ativada e insira JSON ou pares name:type separados por vírgulas.
  9. Opcional: na seção Propriedades, configure as propriedades da tabela. Nesta seção, listamos propriedades predefinidas, como gcp.biglake.bigquery-dml.enabled e gcp.biglake.table-management.enabled.

    Por exemplo, é possível mudar esses valores para true para ativar a DML do BigQuery ou a manutenção automática de tabelas. A manutenção automática de tabelas executa tarefas em segundo plano, como compactação e expiração de snapshots. Para mais informações, consulte Configurar opções de tabela.

  10. Clique em Criar.

A tabela aparece na página Detalhes do namespace.

Spark

spark.sql("CREATE TABLE NAMESPACE_NAME.TABLE_NAME (id int, data string) USING ICEBERG;")

Substitua os seguintes valores:

  • NAMESPACE_NAME: o nome do namespace.
  • TABLE_NAME: um nome para a tabela.

Para ativar a interoperabilidade de leitura/gravação e o gerenciamento de tabelas (pré-lançamento), adicione as propriedades à cláusula TBLPROPERTIES:

TBLPROPERTIES (
  'gcp.biglake.bigquery-dml.enabled' = true,
  'gcp.biglake.table-management.enabled' = true
)

Trino

CREATE TABLE SCHEMA_NAME.TABLE_NAME (id int, data varchar);

Substitua os seguintes valores:

  • SCHEMA_NAME: o nome do seu esquema.
  • TABLE_NAME: um nome para a tabela.

Para ativar a interoperabilidade de leitura/gravação e o gerenciamento de tabelas (pré-lançamento), adicione estas propriedades à cláusula WITH:

WITH (
  "gcp.biglake.bigquery-dml.enabled" = 'true',
  "gcp.biglake.table-management.enabled" = 'true'
)

gcloud

Para criar uma tabela usando a Google Cloud CLI, execute o comando gcloud biglake iceberg tables create:

gcloud biglake iceberg tables create \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME" \
    --create-from-file="TABLE_DEFINITION_FILE"

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud.
  • CATALOG_ID: o ID do catálogo.
  • NAMESPACE_NAME: o nome do namespace do catálogo.
  • TABLE_DEFINITION_FILE: o caminho para um arquivo JSON que contém a definição da tabela do Iceberg.

BigQuery

Para criar uma tabela do Apache Iceberg no catálogo do ambiente de execução do Lakehouse no BigQuery, use a seguinte instrução CREATE TABLE do GoogleSQL. Quando você cria uma tabela no BigQuery, a DML do BigQuery e o gerenciamento de tabelas são ativados por padrão. Para usar o gerenciamento automático de tabelas, o catálogo precisa usar o modo de venda de credenciais.

CREATE TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME` (id int, data string);

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • CATALOG_ID: o ID do catálogo do ambiente de execução do Lakehouse.
  • NAMESPACE: o nome do namespace do Iceberg.
  • TABLE_NAME: um nome para a tabela do Apache Iceberg.

REST

Para criar uma tabela do Apache Iceberg usando a API REST, faça uma solicitação POST ao endpoint CreateIcebergTable:

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/tables

O corpo da solicitação precisa conter um payload JSON CreateTableRequest do Iceberg válido que defina o esquema da tabela, a especificação da partição e as propriedades iniciais.

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • CATALOG_ID: o ID do catálogo.
  • NAMESPACE_NAME: o nome do namespace do catálogo.

A seguir