Criar e consultar uma tabela do Iceberg no Lakehouse usando a Google Cloud CLI
Com o Lakehouse sem fronteiras, é possível compartilhar tabelas do Apache Iceberg entre o Google Cloud e mecanismos de código aberto, como Apache Spark, Trino e Apache Flink. O catálogo do ambiente de execução do Lakehouse rastreia metadados, incluindo esquemas, snapshots e locais do Cloud Storage, pelo endpoint do catálogo REST do Apache Iceberg.
Neste guia de início rápido, você vai usar a Google Cloud CLI para configurar um catálogo de vários buckets e executar um job do PySpark no Serviço Gerenciado para Apache Spark. Depois que o job cria uma tabela do Iceberg, você a consulta diretamente no BigQuery usando a sintaxe de quatro partes P.C.N.T (Project.Catalog.Namespace.Table) sem mover ou registrar dados.
Antes de começar
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.
-
Instale a CLI do Google Cloud.
-
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init -
Crie ou selecione um projeto do Google Cloud .
Papéis necessários para selecionar ou criar um projeto
- Selecionar um projeto: para selecionar um projeto, não é necessário ter um papel do IAM específico. É possível selecionar qualquer projeto em que você tenha um papel.
-
Criar um projeto: para criar um projeto, é preciso ter o papel de criador de projetos
(
roles/resourcemanager.projectCreator), que contém a permissãoresourcemanager.projects.create. Saiba como conceder papéis.
-
Crie um projeto do Google Cloud :
gcloud projects create PROJECT_ID
Substitua
PROJECT_IDpor um nome para o projeto do Google Cloud que você está criando. -
Selecione o projeto do Google Cloud que você criou:
gcloud config set project PROJECT_ID
Substitua
PROJECT_IDpelo nome do projeto do Google Cloud .
-
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Ative as APIs BigLake, Serviço Gerenciado para Apache Spark, Cloud Storage, BigQuery e Compute Engine, se ainda não estiverem ativadas:
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.gcloud services enable biglake.googleapis.com
dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com -
Atribua papéis à sua conta de usuário. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM:
roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUsergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Substitua:
PROJECT_ID: o ID do projeto.USER_IDENTIFIER: o identificador da sua conta de usuário . Por exemplo,myemail@example.com.ROLE: o papel do IAM que você concede à sua conta de usuário.
-
Instale a CLI do Google Cloud.
-
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init -
Crie ou selecione um projeto do Google Cloud .
Papéis necessários para selecionar ou criar um projeto
- Selecionar um projeto: para selecionar um projeto, não é necessário ter um papel do IAM específico. É possível selecionar qualquer projeto em que você tenha um papel.
-
Criar um projeto: para criar um projeto, é preciso ter o papel de criador de projetos
(
roles/resourcemanager.projectCreator), que contém a permissãoresourcemanager.projects.create. Saiba como conceder papéis.
-
Crie um projeto do Google Cloud :
gcloud projects create PROJECT_ID
Substitua
PROJECT_IDpor um nome para o projeto do Google Cloud que você está criando. -
Selecione o projeto do Google Cloud que você criou:
gcloud config set project PROJECT_ID
Substitua
PROJECT_IDpelo nome do projeto do Google Cloud .
-
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Ative as APIs BigLake, Serviço Gerenciado para Apache Spark, Cloud Storage, BigQuery e Compute Engine, se ainda não estiverem ativadas:
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.gcloud services enable biglake.googleapis.com
dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com -
Atribua papéis à sua conta de usuário. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM:
roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUsergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Substitua:
PROJECT_ID: o ID do projeto.USER_IDENTIFIER: o identificador da sua conta de usuário . Por exemplo,myemail@example.com.ROLE: o papel do IAM que você concede à sua conta de usuário.
Configurar o ambiente e criar um bucket
Abra o Cloud Shell e crie um bucket do Cloud Storage para armazenar um script do PySpark e dados de tabela do Iceberg:
No console do Google Cloud , clique em Ativar o Cloud Shell.
Clique em Autorizar se solicitado.
Defina variáveis de ambiente para o projeto, a região, o bucket e o nome do catálogo para que você possa reutilizá-los neste guia de início rápido:
export PROJECT_ID=$(gcloud config get-value project) export REGION="us-central1" export BUCKET_NAME="${PROJECT_ID}-lakehouse-quickstart" export LAKEHOUSE_CATALOG_ID="quickstart_catalog"Crie um bucket do Cloud Storage na região selecionada:
gcloud storage buckets create gs://${BUCKET_NAME} \ --project=${PROJECT_ID} \ --location=${REGION}
Conceder permissões à conta de serviço do Spark
Por padrão, o Serviço Gerenciado para Apache Spark executa jobs em lote usando a conta de serviço padrão do Compute Engine do seu projeto. Conceda a essa conta de serviço os seguintes papéis do IAM para que ela possa ler o script do PySpark no Cloud Storage e interagir com o catálogo do ambiente de execução do Lakehouse e o BigQuery:
| Papel | Recurso | Finalidade |
|---|---|---|
| Worker do Dataproc ( roles/dataproc.worker) |
Projeto | Executar cargas de trabalho em lote do Serviço Gerenciado para Apache Spark. |
| Consumidor do Service Usage ( roles/serviceusage.serviceUsageConsumer) |
Projeto | Usar APIs e cotas do projeto. |
| Editor do BigLake ( roles/biglake.editor) |
Projeto | Criar recursos de catálogo e solicitar credenciais de armazenamento vendidas. |
| Editor de dados do BigQuery ( roles/bigquery.dataEditor) |
Projeto | Gerenciar metadados do BigQuery para suas tabelas. |
| Leitor de objetos do Storage ( roles/storage.objectViewer) |
Bucket | Leia o script do PySpark no bucket do Cloud Storage. |
A conta de serviço do Spark só precisa do papel Leitor de objetos do Storage (roles/storage.objectViewer) para ler o script do PySpark. Ele não precisa de acesso de gravação direto ao bucket porque o catálogo do ambiente de execução do Lakehouse vende credenciais de gravação temporárias com escopo de tabela quando o job é executado.
No Cloud Shell, execute o script a seguir para conceder esses papéis:
PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} \
--format='value(projectNumber)')
SPARK_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
for ROLE in \
"roles/dataproc.worker" \
"roles/serviceusage.serviceUsageConsumer" \
"roles/biglake.editor" \
"roles/bigquery.dataEditor"; do
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
--member="serviceAccount:${SPARK_SA}" \
--role="${ROLE}"
done
gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
--member="serviceAccount:${SPARK_SA}" \
--role="roles/storage.objectViewer"Criar um catálogo no catálogo do ambiente de execução do Lakehouse
Crie um catálogo no catálogo do ambiente de execução do Lakehouse para suas tabelas do Apache Iceberg.
No Cloud Shell, crie um catálogo de vários buckets. Um catálogo de vários buckets permite que você nomeie seu catálogo de forma independente de qualquer nome de bucket e associe vários buckets do Cloud Storage a um único catálogo. Ative o modo de fornecimento de credenciais para que o catálogo do ambiente de execução do Lakehouse possa emitir com segurança credenciais de armazenamento temporárias para o Spark em seu nome.
gcloud biglake iceberg catalogs create ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} \ --catalog-type=biglake \ --default-location=gs://${BUCKET_NAME} \ --credential-mode=vended-credentials
Dê ao catálogo acesso ao seu bucket:
Com a venda de credenciais, a conta de serviço de provisionamento automático do catálogo precisa do papel de Usuário de objetos do Storage (
roles/storage.objectUser) no bucket para gerar tokens de acesso temporários para os mecanismos do cliente.# Retrieve the auto-provisioned catalog service account email CATALOG_SA=$(gcloud biglake iceberg catalogs describe ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} \ --format='value(biglake-service-account)') # Grant the Storage Object User role to the catalog service account on your bucket gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \ --member="serviceAccount:${CATALOG_SA}" \ --role="roles/storage.objectUser"
Criar uma tabela Iceberg com um job do PySpark
Com o catálogo e as permissões prontos, execute um job do PySpark no Serviço Gerenciado para Apache Spark para criar uma tabela do Iceberg e inserir alguns dados de amostra.
Criar e fazer upload de um script do PySpark
No Cloud Shell, crie um arquivo chamado
quickstart.py:cat << 'EOF' > quickstart.py from pyspark.sql import SparkSession spark = SparkSession.builder.appName("quickstart").getOrCreate() # Create a namespace spark.sql("CREATE NAMESPACE IF NOT EXISTS `quickstart_catalog`.quickstart_namespace") # Create the table spark.sql(""" CREATE OR REPLACE TABLE `quickstart_catalog`.quickstart_namespace.quickstart_table ( id INT, name STRING ) USING iceberg """) # Insert data into the table spark.sql(""" INSERT INTO `quickstart_catalog`.quickstart_namespace.quickstart_table VALUES (1, 'one'), (2, 'two'), (3, 'three') """) EOFEsse script inicia uma sessão do Spark, cria um namespace chamado
quickstart_namespacee uma tabela do Iceberg chamadaquickstart_tablee insere três linhas de dados de amostra. Como as instruções SQL não especificam um caminho de bucket (LOCATION), o catálogo do ambiente de execução do Lakehouse armazena automaticamente os arquivos de namespace e tabela no bucket--default-locationdo catálogo (gs://${BUCKET_NAME}).Copie
quickstart.pypara o bucket do Cloud Storage para que o Serviço Gerenciado para Apache Spark possa acessá-lo:gcloud storage cp quickstart.py gs://${BUCKET_NAME}/quickstart.py
Executar o script PySpark
Envie o script do PySpark como um job em lote do Serviço Gerenciado para Apache Spark, que executa o código com bibliotecas do Iceberg pré-instaladas sem a necessidade de provisionar um cluster.
A flag --properties configura o Spark para se conectar ao seu catálogo no
catálogo do ambiente de execução do Lakehouse usando o endpoint do catálogo REST do Apache
Iceberg:
No Cloud Shell, envie o job em lote:
gcloud dataproc batches submit pyspark gs://${BUCKET_NAME}/quickstart.py \ --project=${PROJECT_ID} \ --region=${REGION} \ --version=2.2 \ --properties="spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog,\ spark.sql.catalog.quickstart_catalog.type=rest,\ spark.sql.catalog.quickstart_catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\ spark.sql.catalog.quickstart_catalog.warehouse=bl://projects/${PROJECT_ID}/catalogs/${LAKEHOUSE_CATALOG_ID},\ spark.sql.catalog.quickstart_catalog.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\ spark.sql.catalog.quickstart_catalog.header.x-goog-user-project=${PROJECT_ID},\ spark.sql.catalog.quickstart_catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\ spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\ spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials,\ spark.sql.catalog.quickstart_catalog.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"
Além das configurações padrão do Iceberg (
SparkCatalog,type=resteIcebergSparkSessionExtensions), essas propriedades configuram a conexão do catálogo do ambiente de execução do Lakehouse:uriewarehouse(bl://...): conecte o Spark ao endpoint do catálogo REST do Apache Iceberg do catálogo do ambiente de execução do Lakehouse e encaminhe as solicitações para o catálogo de vários buckets.rest.auth.typeeheader.x-goog-user-project: autentique solicitações REST usando as credenciais da conta de serviço do Spark e fature a cota da API para seu projeto.header.X-Iceberg-Access-Delegation,io-implegcs.oauth2.refresh-credentials-endpoint: solicite credenciais temporárias do Cloud Storage ao catálogo e configure o clienteGCSFileIOdo Iceberg para gravar arquivos de dados usando esses tokens.
Para mais informações sobre essas configurações, consulte Configurar o aplicativo cliente e a documentação de configuração do Apache Iceberg Spark.
Quando o job é concluído, a saída é semelhante a esta:
Batch [cb9d84e9489d408baca4f9e7ab4c64ff] finished. metadata: '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata batch: projects/PROJECT_ID/locations/us-central1/batches/cb9d84e9489d408baca4f9e7ab4c64ff batchUuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 createTime: '2026-01-24T00:10:50.224097Z' description: Batch labels: goog-dataproc-batch-id: cb9d84e9489d408baca4f9e7ab4c64ff goog-dataproc-batch-uuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 goog-dataproc-drz-resource-uuid: batch-54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 goog-dataproc-location: us-central1 operationType: BATCH name: projects/PROJECT_ID/regions/us-central1/operations/32287926-5f61-3572-b54a-fbad8940d6ef
Consultar a tabela no BigQuery
Agora que o Spark gravou sua tabela do Iceberg, é possível consultá-la imediatamente no BigQuery usando a sintaxe P.C.N.T (Project.Catalog.Namespace.Table) de quatro partes:
No Cloud Shell, execute o seguinte comando
bq query:bq query --project_id=${PROJECT_ID} --location=${REGION} --use_legacy_sql=false \ "SELECT * FROM \`${PROJECT_ID}.${LAKEHOUSE_CATALOG_ID}.quickstart_namespace.quickstart_table\`"A saída mostra as três linhas que você inseriu com o job do PySpark:
+----+-------+ | id | name | +----+-------+ | 1 | one | | 2 | two | | 3 | three | +----+-------+
Como o catálogo do ambiente de execução do Lakehouse rastreia os metadados do Iceberg e processa o acesso ao armazenamento, o BigQuery lê os arquivos subjacentes no Cloud Storage assim que o Spark confirma o snapshot.
Nesse mesmo ponto, também é possível ler ou gravar em quickstart_table usando
qualquer outro mecanismo compatível com o Iceberg, como Trino,
Flink ou um cluster do Spark autogerenciado. Como
a venda de credenciais está ativada no catálogo, um mecanismo externo só precisa
do papel de Leitor do BigLake (roles/biglake.viewer) no projeto para ler
a tabela ou do papel de Editor do BigLake (roles/biglake.editor) para também
gravar dados e confirmar novos snapshots. Para saber como conectar outros mecanismos, consulte
Configurar o endpoint do catálogo REST do Apache Iceberg.
Limpar
Para evitar cobranças desnecessárias na sua conta do Google Cloud , exclua os recursos criados neste guia de início rápido. A exclusão da tabela, do namespace e do catálogo remove o registro de metadados do catálogo do ambiente de execução do Lakehouse, enquanto a exclusão do bucket remove os dados do Parquet e os arquivos de metadados do Iceberg armazenados no Cloud Storage:
No Cloud Shell, exclua a tabela do catálogo:
gcloud biglake iceberg tables delete quickstart_table \ --project=${PROJECT_ID} \ --catalog=${LAKEHOUSE_CATALOG_ID} \ --namespace=quickstart_namespace \ --quietExclua o namespace do catálogo:
gcloud biglake iceberg namespaces delete quickstart_namespace \ --project=${PROJECT_ID} \ --catalog=${LAKEHOUSE_CATALOG_ID} \ --quietExclua o catálogo:
gcloud biglake iceberg catalogs delete ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} --quietExclua o bucket do Cloud Storage e todo o conteúdo dele:
gcloud storage rm -r gs://${BUCKET_NAME}
A seguir
- Consulte o guia de início rápido Criar e consultar uma tabela do Iceberg usando o console do Google Cloud para criar namespaces e tabelas do Iceberg na UI e modificar dados usando a linguagem de manipulação de dados (DML) do BigQuery.
- Faça o codelab Configurar o acesso a dados entre nuvens para consultar dados na Amazon Web Services (AWS), no AlloyDB para PostgreSQL e no Cloud Storage sem ETL.
- Aprenda mais sobre catálogos de vários buckets e o endpoint do catálogo REST do Apache Iceberg.
- Saiba como gerenciar catálogos no catálogo do ambiente de execução do Lakehouse.
- Aprenda mais sobre as tabelas do Apache Iceberg gerenciadas pelo Lakehouse.