Criar e gerenciar recursos no catálogo de ambiente de execução do Lakehouse

O Lakehouse para Apache Iceberg oferece suporte ao gerenciamento de recursos pelo catálogo de ambiente de execução do Lakehouse.

Esse catálogo compartilhado elimina a necessidade de manter vários catálogos para cargas de trabalho de código aberto em diferentes mecanismos de processamento de dados. As operações compatíveis incluem criar, visualizar, modificar e excluir recursos, como namespaces e tabelas.

Antes de começar

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

  2. Ative as APIs BigQuery, BigQuery Storage e Serviço Gerenciado para Apache Spark.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar as APIs

Funções exigidas

Para receber as permissões necessárias a fim de gerenciar recursos do Apache Iceberg no catálogo de tempo de execução do Lakehouse, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

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.

Criar recursos de catálogo

As seções a seguir descrevem como criar recursos no catálogo do ambiente de execução do Lakehouse.

Criar namespaces

Selecione uma das seguintes opções:

API

Use o método datasets.insert e especifique o campo ExternalCatalogDatasetOptions no recurso do conjunto de dados que você transmite.

{
  "datasetReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID"
  },
  "externalCatalogDatasetOptions": {
    "defaultStorageLocationUri": "URI",
    "parameters": {
      ...
    }
  },
  "location": "LOCATION"
}

Substitua:

  • PROJECT_ID: o ID do projeto que contém seu conjunto de dados de destino.
  • DATASET_ID: o ID do conjunto de dados de destino.
  • URI: o URI do Cloud Storage de todas as tabelas no conjunto de dados.
  • LOCATION: o local do BigQuery em que você quer criar o conjunto de dados.

SQL do Apache Spark 

CREATE NAMESPACE SPARK_CATALOG.NAMESPACE;

Substitua:

  • SPARK_CATALOG: o nome do catálogo do Apache Spark.
  • NAMESPACE: o nome do novo namespace.

Terraform 

provider "google" {
  project = "PROJECT_ID"
}

resource "google_bigquery_dataset" "default" {
  dataset_id = "DATASET_ID"
  location   = "LOCATION"

  external_catalog_dataset_options {
    default_storage_location_uri = "URI"
    parameters = {
      ...
    }
  }
}

Substitua:

  • PROJECT_ID: o ID do projeto que contém seu conjunto de dados de destino.
  • DATASET_ID: o ID do conjunto de dados de destino.
  • LOCATION: o local do BigQuery em que você quer criar o conjunto de dados.
  • URI: o URI do Cloud Storage de todas as tabelas no conjunto de dados.

Criar tabelas do Apache Iceberg

Selecione uma das seguintes opções:

API

Use o método tables.insert e especifique o campo ExternalCatalogTableOptions no recurso de tabela que você transmite para a API.

{
  "tableReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "externalCatalogTableOptions": {
    "parameters": {
      "table_type": "iceberg",
      "metadata_location": "METADATA_URI"
    },
    "connection_id": "CONNECTION_ID"
  }
}

Substitua:

  • PROJECT_ID: o ID do projeto que contém a tabela de destino.
  • DATASET_ID: o ID do conjunto de dados que contém a tabela de destino.
  • TABLE_ID: o ID da tabela de destino.
  • METADATA_URI: o URI do Cloud Storage para o arquivo de metadados mais recente do Apache Iceberg. Por exemplo, gs://mybucket/mytable/metadata/1234.metadata.json.
  • CONNECTION_ID: o ID da sua conexão com o Cloud Storage.

SQL do Apache Spark 

CREATE TABLE SPARK_CATALOG.NAMESPACE.TABLE
  (id bigint, data string) USING iceberg;

Substitua:

  • SPARK_CATALOG: o nome do catálogo do Apache Spark.
  • NAMESPACE: o nome do namespace.
  • TABLE: o nome da nova tabela.

Terraform 

resource "google_bigquery_table" "default" {
  deletion_protection = false
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "TABLE"

  external_catalog_table_options {
    storage_descriptor {
      location_uri  = "STORAGE_URI"
      input_format  = "org.apache.hadoop.mapred.FileInputFormat"
      output_format = "org.apache.hadoop.mapred.FileOutputFormat"
    }
    parameters = {
      "table_type"        = "iceberg"
      "metadata_location" = "METADATA_URI"
      "write.parquet.compression-codec" : "zstd"
      "EXTERNAL" : "TRUE"
    }
  }
}

Substitua:

  • TABLE: o nome da tabela de destino.
  • STORAGE_URI: o URI do Cloud Storage em que os dados da tabela são armazenados, começando com gs://.
  • METADATA_URI: o URI do Cloud Storage para o arquivo de metadados mais recente do Apache Iceberg. Por exemplo, gs://mybucket/mytable/metadata/1234.metadata.json.

Ver recursos do catálogo

As seções a seguir descrevem como visualizar recursos no catálogo do ambiente de execução do Lakehouse.

Ver namespaces

Selecione uma das seguintes opções:

API

Use o método datasets.list para conferir todos os namespaces ou o método datasets.get para conferir informações sobre um namespace definido.

SQL do Apache Spark

Para conferir todos os namespaces em um catálogo, use a seguinte instrução:

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

Substitua SPARK_CATALOG pelo nome do catálogo do Apache Spark.

Para conferir informações sobre um namespace definido, use a seguinte instrução:

DESCRIBE { DATABASE | NAMESPACE } [EXTENDED]
SPARK_CATALOG.NAMESPACE;

Substitua:

  • SPARK_CATALOG: o nome do catálogo do Apache Spark.
  • NAMESPACE: o nome do namespace.

Visualizar tabelas

Selecione uma das seguintes opções:

API

Use o método tables.list para conferir todas as tabelas em um namespace ou o método tables.get para conferir informações sobre uma tabela definida.

SQL do Apache Spark

Para conferir todas as tabelas em um namespace, use a seguinte instrução:

SHOW TABLES IN SPARK_CATALOG.NAMESPACE;

Substitua:

  • SPARK_CATALOG: o nome do catálogo do Apache Spark.
  • NAMESPACE: o nome do namespace.

Para conferir informações sobre uma tabela definida, use a seguinte instrução:

DESCRIBE TABLE [EXTENDED]
SPARK_CATALOG.NAMESPACE.TABLE;

Substitua:

  • SPARK_CATALOG: o nome do catálogo do Apache Spark.
  • NAMESPACE: o nome do namespace.
  • TABLE: o nome da tabela.

Modificar recursos do catálogo

As seções a seguir descrevem como modificar recursos no catálogo de tempo de execução do Lakehouse.

Atualizar namespaces

Selecione uma das seguintes opções:

API

Use o método datasets.patch e atualize o campo ExternalCatalogDatasetOptions no recurso do conjunto de dados. O método datasets.update não é recomendado porque substitui todo o recurso do conjunto de dados.

SQL do Apache Spark

Use a instrução ALTER DATABASE.

Atualizar tabelas do Apache Iceberg

Selecione uma das seguintes opções:

API

Use o método tables.patch e atualize o campo ExternalCatalogTableOptions no recurso de tabela. O método tables.update não é recomendado porque substitui todo o recurso da tabela.

Para atualizar o esquema ou o arquivo de metadados, use o método tables.patch e defina a propriedade autodetect_schema como "true":

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID?autodetect_schema=true

Substitua:

  • PROJECT_ID: o ID do projeto que contém a tabela que você quer atualizar.
  • DATASET_ID: o ID do conjunto de dados que contém a tabela que você quer atualizar.
  • TABLE_ID: o ID da tabela que você quer atualizar.

No corpo da solicitação, especifique o valor atualizado de cada campo. Por exemplo, para atualizar o local dos metadados da tabela do Apache Iceberg, especifique o valor atualizado no campo metadata_location:

{
  "externalCatalogTableOptions": {
    "parameters": {"metadata_location": "METADATA_URI"}
  },
  "schema": null
}'

Substitua METADATA_URI pelo URI do Cloud Storage do arquivo de metadados mais recente do Apache Iceberg. Por exemplo, gs://mybucket/mytable/metadata/1234.metadata.json.

SQL do Apache Spark

Use a instrução ALTER TABLE.

Excluir recursos do catálogo

As seções a seguir descrevem como excluir recursos no catálogo do ambiente de execução do Lakehouse.

Excluir namespaces

Selecione uma das seguintes opções:

API

Use o método datasets.delete. Defina o parâmetro deleteContents como "true" para excluir as tabelas no seu namespace.

SQL do Apache Spark 

DROP NAMESPACE SPARK_CATALOG.NAMESPACE;

Substitua:

  • SPARK_CATALOG: o nome do catálogo do Apache Spark.
  • NAMESPACE: o nome do namespace.

Excluir tabelas

Selecione uma das seguintes opções:

API

Use o método tables.delete e especifique o nome da tabela. Esse método não exclui os arquivos associados no Cloud Storage.

SQL do Apache Spark

Para descartar apenas a tabela, use a seguinte instrução:

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE;

Substitua:

  • SPARK_CATALOG: o nome do catálogo do Apache Spark.
  • NAMESPACE: o nome do namespace.
  • TABLE: o nome da tabela a ser excluída.

Para descartar a tabela e excluir os arquivos associados no Cloud Storage, use a seguinte instrução:

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE PURGE;

Substitua:

  • SPARK_CATALOG: o nome do catálogo do Apache Spark.
  • NAMESPACE: o nome do namespace.
  • TABLE: o nome da tabela a ser excluída.

A seguir