Criar uma tabela

A criação de uma tabela do Apache Iceberg registra os metadados da tabela em um namespace no catálogo de ambientes de execução do Lakehouse.

Se você não especificar um local de armazenamento explícito no namespace ou na tabela durante a criação, o sistema vai construir automaticamente os metadados e diretórios de dados da tabela no local padrão do catálogo (derivado do bucket base do Cloud Storage do catálogo) anexando os identificadores de namespace e tabela.

Antes de começar

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

  2. Ative a API BigLake.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de proprietário (roles/owner). Caso contrário, você pode receber essa permissão com o papel de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  3. Configure o catálogo de ambientes de execução do Lakehouse com o endpoint do catálogo REST do Apache Iceberg.

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:

  • Todos:
    • 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 com papéis personalizados ou outros papéis predefinidos.

Recursos e suporte da tabela

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

Tabelas do Iceberg com suporte

Somente as tabelas do 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 do BigQuery, como a linguagem de manipulação de dados (DML) do BigQuery e o gerenciamento automático de tabelas, configurando propriedades específicas da tabela. Esses recursos são ativados de maneiras diferentes, dependendo de onde a tabela é criada:

  • No 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, é necessário configurar explicitamente as propriedades da tabela. Consulte Configurar opções de tabela para mais informações.

Criar uma tabela

Crie uma tabela do Iceberg.

Console

  1. No Google Cloud console, acesse Lakehouse.

    Acessar o Lakehouse

  2. Selecione um catálogo atual ou crie um se você não tiver.

  3. Na barra de menus, clique em + Criar tabela.

  4. Em Formato da tabela, selecione Iceberg.

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

  6. Opcional: na seção Propriedades, configure as propriedades da tabela. As propriedades predefinidas, como gcp.biglake.bigquery-dml.enabled e gcp.biglake.table-management.enabled, são listadas.

    Por exemplo, é possível mudar esses valores para true para ativar a DML do BigQuery ou o gerenciamento automático de tabelas. Para mais informações, consulte Configurar opções de tabela.

  7. 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 seu 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 essas propriedades à cláusula WITH:

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

gcloud

Para criar uma tabela usando gcloud, execute o gcloud biglake iceberg tables create comando.

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 Google Cloud projeto.
  • 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 de ambientes 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 automático de tabelas são ativados por padrão.

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

Substitua:

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

REST

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

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 válido do Iceberg que define o esquema da tabela, a especificação de partição e as propriedades iniciais.

Substitua:

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

A seguir