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

O Lakehouse sem fronteiras é compatível com o gerenciamento de recursos por meio do catálogo do 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, 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.

    Ativar as APIs

Funções exigidas

Para receber as permissões necessárias para gerenciar recursos do Apache Iceberg no catálogo do ambiente 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ê transmitir.

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

Substitua:

  • PROJECT_ID: o ID do projeto que contém o conjunto de dados de destino.
  • DATASET_ID: o ID do conjunto de dados de destino.
  • URI: o URI do Cloud Storage para 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 o 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 para 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.

{
  "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 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 visualizar todas as tabelas em um namespace ou use o método tables.get para visualizar 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 do ambiente 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 de 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 para o 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 verdadeiro 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 descartada.

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