Criar um catálogo

A criação de um endpoint de catálogo (como um endpoint de catálogo REST do Apache Iceberg ou do Apache Hive) estabelece um endpoint de gerenciamento no catálogo do ambiente de execução do Lakehouse.

Esse endpoint aponta para um bucket do Cloud Storage subjacente, fornecendo uma camada de metadados que permite que mecanismos de consulta e cargas de trabalho de código aberto interajam diretamente com suas tabelas.

Ao criar o endpoint do catálogo para o Lakehouse sem bordas, você pode escolher entre credenciais de usuário final ou modo de venda de credenciais para delegação de acesso ao armazenamento.

Antes de começar

1. Leia Sobre o catálogo do ambiente de execução do Lakehouse para entender como o catálogo do ambiente de execução do Lakehouse funciona e as limitações do serviço.
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.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Funções exigidas

Para receber as permissões necessárias para criar um catálogo e registrar tabelas, peça ao administrador os seguintes papéis do IAM:

• Crie um catálogo:
  • Administrador do BigLake (roles/biglake.admin) no projeto
  • Administrador do Storage (roles/storage.admin) no projeto
• Criar (registrar) tabelas: Administrador do BigLake (roles/biglake.admin) no seu projeto. Para registrar tabelas, é necessário ter a permissão específica de registro de tabela (biglake.tables.register), que está incluída no papel de administrador do BigLake.
• Use a conta de serviço do catálogo provisionada automaticamente no modo de venda de credenciais: Usuário de objetos do Storage (roles/storage.objectUser) nos buckets de destino do Cloud Storage. Depois de criar o catálogo, conceda explicitamente o papel de usuário de objetos do Storage (roles/storage.objectUser) nos seus buckets de armazenamento à conta de serviço provisionada automaticamente.

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.

Observação: a criação da conta de serviço do catálogo provisionada automaticamente é eventualmente consistente. Isso significa que leva algum tempo para que a conta de serviço se propague pelo sistema. Se você tentar conceder papéis à conta de serviço imediatamente após a criação, a solicitação poderá falhar. Para saber quanto tempo leva, em média, para as mudanças de acesso serem propagadas, consulte Propagação de mudança de acesso.

Criar um catálogo

Crie um catálogo.

Criar um catálogo

Siga estas etapas para criar um catálogo com base no modo de credencial e no tipo de bucket de sua preferência. Para mais informações sobre os diferentes tipos de catálogo, consulte Sobre o endpoint do catálogo REST do Apache Iceberg.

Observação: ao criar ou gerenciar um catálogo de vários buckets no Google Cloud, especifique caminhos do Cloud Storage (gs://) para os locais de armazenamento padrão e restrito. O formato de URI bl://projects/PROJECT_ID/catalogs/CATALOG_ID é usado exclusivamente durante a configuração do cliente para identificar o data warehouse do catálogo ao se conectar de mecanismos de consulta (como Spark ou Trino).

Console

Criar um catálogo de vários buckets (recomendado)

Com essa configuração, seu catálogo pode associar vários buckets e ser nomeado de forma independente de qualquer nome de bucket.

1. Abra a página Lakehouse no console Google Cloud .

   Acessar o Lakehouse

2. Clique em Criar catálogo.

3. Em Tipo de catálogo, selecione Catálogo REST do Iceberg.

4. Em Opções de bucket do catálogo do Lakehouse, selecione Catálogo de vários buckets.

5. Em Caminho padrão do Cloud Storage do catálogo, insira ou procure o caminho do Cloud Storage a ser usado com seu catálogo.

6. Em ID do catálogo, insira um nome personalizado para seu catálogo.

7. Em Local principal, selecione um local. O local precisa estar perto das regiões do bucket principal.

8. Clique em Continuar.

9. Na etapa Caminhos de dados, adicione outros caminhos do Cloud Storage, se necessário.

10. Clique em Continuar.

11. Em Método de autenticação, selecione Credenciais de usuário final ou Modo de venda de credenciais.

12. Clique em Criar.

    Seu catálogo é criado e a página Detalhes do catálogo é aberta.

13. Se você selecionou Modo de fornecimento de credenciais, siga estas etapas adicionais:

    1. Em Método de autenticação, clique em Definir permissões do bucket.
    2. Na caixa de diálogo, clique em Confirmar.

Criar um catálogo de bucket único (gs://)

Atenção:não recomendamos o uso da configuração de um único bucket para novos projetos. Essa configuração restringe seu catálogo a um único bucket e bloqueia o nome do catálogo para o nome do bucket.

1. Em Tipo de catálogo, selecione Catálogo REST do Iceberg ou Hive Metastore.
2. Em Opções de bucket do catálogo do Lakehouse, selecione Catálogo de bucket único.
3. Em Caminho padrão do Cloud Storage do catálogo, insira ou procure o caminho do Cloud Storage a ser usado com seu catálogo. Para um catálogo de bucket único (gs://), só é possível ter um catálogo por bucket, e o nome do catálogo precisa corresponder ao nome do bucket.
4. Clique em Continuar.
5. Em Método de autenticação, selecione Credenciais de usuário final ou Modo de venda de credenciais.
6. Clique em Criar.
7. Se você selecionou Modo de fornecimento de credenciais, siga estas etapas adicionais:
   1. Em Método de autenticação, clique em Definir permissões do bucket.
   2. Na caixa de diálogo, clique em Confirmar.

gcloud

Criar um catálogo de vários buckets (recomendado)

Com essa configuração, seu catálogo pode associar vários buckets e ser nomeado de forma independente de qualquer nome de bucket.

Para criar um catálogo de vários buckets (recomendado), execute o comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    --credential-mode CREDENTIAL_MODE \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    [--primary-location LOCATION]

Substitua:

• CATALOG_NAME: um nome para o catálogo. Para catálogos de vários buckets (recomendado), esse é o nome personalizado do catálogo.
• PROJECT_ID: o ID do projeto do Google Cloud.
• DEFAULT_LOCATION: especifique o local de armazenamento padrão do catálogo. É possível especificar um bucket (gs://my-bucket) ou um subcaminho (gs://my-bucket/path). Todos os namespaces e tabelas no catálogo precisam estar no caminho especificado. Por exemplo, se você especificar gs://my-bucket/path, não poderá criar namespaces ou tabelas em gs://my-bucket/another/path.

• CREDENTIAL_MODE: o método de autenticação. Use end-user para Credenciais do usuário final ou vended-credentials para Modo de venda de credenciais.

  Observação: se você usar o modo de venda de credenciais, conceda explicitamente o papel Usuário de objetos do Storage (roles/storage.objectUser) em todos os buckets de armazenamento associados à conta de serviço do catálogo de tempo de execução do Lakehouse provisionado automaticamente do seu catálogo.

• RESTRICTED_LOCATIONS: (opcional) lista separada por vírgulas de locais de armazenamento permitidos adicionais, no formato gs://my-bucket-1/...,gs://my-bucket-2/.... Se você especificar um caminho (como gs://my-bucket/path), todos os namespaces ou tabelas nesse bucket precisarão estar nesse caminho. Todos os locais de armazenamento em nuvem configurados no local padrão e nos locais restritos precisam estar no mesmo grupo de região geográfica ou jurisdição (como Estados Unidos, Europa, Canadá ou Ásia). Por exemplo, não é possível misturar um bucket nos EUA com um na Europa. Para conferir uma lista de locais aceitos, consulte Locais do Lakehouse.

  Aviso:evite configurar caminhos sobrepostos com outros catálogos para impedir a exposição não autorizada de credenciais. Para mais informações, consulte Armazenamento em vários buckets.

• LOCATION: (opcional) a região principal do catálogo para garantir a interoperabilidade com o BigQuery. Para buckets do Cloud Storage na região dos EUA (por exemplo, US ou us-central1) ou na região da UE (por exemplo, EU ou europe-west4), especifique US ou EU, respectivamente, para garantir que o catálogo esteja acessível e disponível para consultas nas multirregiões correspondentes do BigQuery. Para mais informações, consulte Regiões de bucket e catálogo.

Criar um catálogo de bucket único (gs://)

Atenção:não recomendamos o uso da configuração de um único bucket para novos projetos. Essa configuração restringe seu catálogo a um único bucket e bloqueia o nome do catálogo para o nome do bucket.

Para criar um catálogo de bucket único (gs://), execute o seguinte comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode CREDENTIAL_MODE

Substitua:

• CATALOG_NAME: um nome para o catálogo. Para catálogos de bucket único (gs://), isso corresponde ao ID do bucket do Cloud Storage usado com o catálogo REST.
• PROJECT_ID: o ID do projeto do Google Cloud.
• CREDENTIAL_MODE: o método de autenticação. Use end-user para Credenciais do usuário final ou vended-credentials para Modo de venda de credenciais.

REST

Criar um catálogo REST do Iceberg

Para criar um endpoint de gerenciamento de catálogo usando a API REST, faça uma solicitação POST para o endpoint CreateIcebergCatalog:

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?icebergCatalogId=CATALOG_ID

O corpo da solicitação precisa conter um payload JSON IcebergCatalog que defina a configuração do catálogo, como o bucket do Cloud Storage subjacente, o data warehouse e o modo de autenticação.

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• CATALOG_ID: o ID do catálogo do ambiente de execução do Lakehouse.