Gerenciar metadados de código aberto com o BigLake Metastore

O BigLake Metastore é um serviço de metadados físicos unificado para produtos de análise de dados no Google Cloud. O BigLake Metastore oferece uma única fonte de verdade para os metadados e permite gerenciar e acessar dados de várias fontes. O BigLake Metastore pode ser acessado no BigQuery e em vários mecanismos de processamento de dados abertos no Dataproc, o que o torna uma ferramenta útil para engenheiros e analistas de dados.

Para gerenciar metadados comerciais, consulte Dataplex.

Como o BigLake Metastore funciona

O BigLake Metastore é um serviço sem servidor que não exige provisionamento de recursos para uso. É possível usá-lo como uma alternativa sem servidor para o Hive Metastore nos clusters do Dataproc. O BigLake Metastore funciona da mesma maneira que o Hive Metastore por meio das APIs compatíveis com o Hive, e você pode consultar imediatamente tabelas de formato aberto no BigQuery sem precisar de outras etapas. O BigLake Metastore é compatível apenas com tabelas do Apache Iceberg.

O BigLake Metastore oferece APIs, bibliotecas de cliente e integração de mecanismo de dados (como Apache Spark) para gerenciar catálogos, bancos de dados e tabelas.

Limitações

O BigLake Metastore está sujeito às seguintes limitações:

• O BigLake Metastore não é compatível com tabelas do Apache Hive.
• Os papéis e as permissões do Identity and Access Management (IAM) só podem ser concedidos a projetos. Não é possível conceder permissões do IAM aos recursos.
• O Cloud Monitoring não é compatível.
• Os catálogos e bancos de dados do BigLake Metastore têm as seguintes limitações de nomenclatura:
  • Os nomes podem ter até 1.024 caracteres.
  • Os nomes podem conter apenas letras UTF-8 (maiúsculas e minúsculas), números e sublinhados.
  • Os nomes precisam ser exclusivos para cada combinação de projeto e região.
• As tabelas do BigLake Metastore seguem as mesmas convenções de nomenclatura das tabelas do BigQuery. Para mais informações, consulte Nomenclatura da tabela.

Antes de começar

É necessário ativar o faturamento e a API BigLake antes de usar o BigLake Metastore.

1. Peça ao administrador para conceder a você o papel do IAM de Administrador do uso de serviço (roles/serviceusage.serviceUsageAdmin) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
2. Ative o faturamento para o projeto do Google Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

3. Ative a API BigLake.

   Ativar a API

Funções exigidas

• Para ter controle total sobre os recursos do BigLake Metastore, você precisa do papel de Administrador do BigLake (roles/biglake.admin). Se você estiver usando uma conta de serviço do conector do BigQuery Spark, uma conta de serviço do Dataproc sem servidor ou uma conta de serviço da VM do Dataproc, conceda o papel de administrador do BigLake à conta.
• Para ter acesso somente leitura aos recursos do BigLake Metastore, você precisa do papel Visualizador do BigLake (roles/biglake.viewer). Por exemplo, ao consultar uma tabela do BigLake Metastore no BigQuery, o usuário ou a conta de serviço de conexão do BigQuery precisa ter o papel de visualizador do BigLake.
• Para criar tabelas do BigQuery com conexões, você precisa do papel Usuário de conexão do BigQuery (roles/bigquery.connectionUser). Para mais informações sobre compartilhamento de conexões, consulte Compartilhar conexões com usuários.

Dependendo do caso de uso, a identidade que chama o BigLake Metastore pode ser usuários ou contas de serviço:

• Usuário: ao chamar diretamente a API BigLake Rest ou ao consultar uma tabela do BigQuery Iceberg sem uma conexão do BigQuery. O BigQuery usa as credenciais do usuário nessa circunstância.
• Conexão de recursos do Cloud com o BigQuery: ao consultar uma tabela do BigQuery Iceberg com uma conexão do BigQuery. O BigQuery usa a credencial da conta de serviço de conexão para acessar o BigLake Metastore.
• Conector do Spark com o BigQuery: ao usar o Spark com o BigLake Metastore em um procedimento armazenado do Spark com o BigQuery. O Spark usa a credencial da conta de serviço do conector do Spark para acessar o BigLake Metastore e criar tabelas do BigQuery.
• Conta de serviço do Dataproc sem servidor: ao usar o Spark com o BigLake no Dataproc sem servidor. O Spark usa a credencial da conta de serviço.
• Conta de serviço da VM do Dataproc: ao usar o Dataproc (e não o Dataproc sem servidor). O Apache Spark usa a credencial da conta de serviço da VM.

Dependendo das suas permissões, é possível conceder esses papéis a você mesmo ou pedir ao administrador para concedê-los. Para mais informações sobre como conceder papéis, consulte Como visualizar os papéis atribuíveis em recursos.

Para conferir as permissões exatas necessárias para acessar os recursos do BigLake Metastore, expanda a seção Permissões necessárias:

Permissões necessárias

• biglake.tables.get para envolvidos no projeto, para todos os acessos somente leitura. A consulta em uma tabela Iceberg do BigQuery é somente leitura.
• biglake.{catalogs|databases|tables}.* para envolvidos no projeto, para todas as permissões de leitura e gravação. Normalmente, o Apache Spark precisa da capacidade de ler e gravar dados, incluindo a capacidade de criar, gerenciar e visualizar catálogos, bancos de dados e tabelas.
• bigquery.connections.delegate no nível de conexão de recursos do Cloud com o BigQuery ou superior, para criar uma tabela Iceberg do BigQuery usando uma conexão.

Conectar-se ao BigLake Metastore

As seções a seguir explicam como se conectar ao BigLake Metastore. Essas seções instalam e usam o plug-in de catálogo do BigLake Apache Iceberg, indicado pelos arquivos JAR nos métodos a seguir. O plug-in do catálogo se conecta ao BigLake Metastore a partir de mecanismos de código aberto, como o Apache Spark.

Conectar-se com uma VM do Dataproc

Para se conectar ao BigLake Metastore com uma VM do Dataproc, faça o seguinte:

1. Usar SSH para se conectar ao Dataproc.

2. Na CLI do Spark SQL, use a seguinte instrução para instalar e configurar o catálogo personalizado do Apache Iceberg para trabalhar com o BigLake Metastore:

   spark-sql \
     --packages ICEBERG_SPARK_PACKAGE \
     --jars BIGLAKE_ICEBERG_CATALOG_JAR \
     --conf spark.sql.catalog.SPARK_CATALOG=org.apache.iceberg.spark.SparkCatalog \
     --conf spark.sql.catalog.SPARK_CATALOG.catalog-impl=org.apache.iceberg.gcp.biglake.BigLakeCatalog \
     --conf spark.sql.catalog.SPARK_CATALOG.gcp_project=PROJECT_ID \
     --conf spark.sql.catalog.SPARK_CATALOG.gcp_location=LOCATION \
     --conf spark.sql.catalog.SPARK_CATALOG.blms_catalog=BLMS_CATALOG \
     --conf spark.sql.catalog.SPARK_CATALOG.warehouse=GCS_DATA_WAREHOUSE_FOLDER \
     --conf spark.sql.catalog.SPARK_HMS_CATALOG=org.apache.iceberg.spark.SparkCatalog \
     --conf spark.sql.catalog.SPARK_HMS_CATALOG.type=hive \
     --conf spark.sql.catalog.SPARK_HMS_CATALOG.uri=thrift://HMS_URI:9083
     

Substitua:

• ICEBERG_SPARK_PACKAGE: a versão do Apache Iceberg com o Spark a ser usado. Recomendamos usar a versão do Spark que corresponda à versão do Spark na instância do Dataproc ou do Dataproc sem servidor. Para conferir uma lista de versões disponíveis do Apache Iceberg, consulte Downloads do Apache Iceberg. Por exemplo, a flag do Apache Spark 3.3 é:
  --packages org.apache.iceberg:iceberg-spark-runtime-3.3_2.13:1.2.1
• BIGLAKE_ICEBERG_CATALOG_JAR: o URI do Cloud Storage do plug-in do catálogo personalizado do Iceberg a ser instalado. Dependendo do ambiente, selecione uma das seguintes opções:
  • Iceberg 1.2.0: gs://spark-lib/biglake/biglake-catalog-iceberg1.2.0-0.1.1-with-dependencies.jar
  • Iceberg 0.14.0: gs://spark-lib/biglake/biglake-catalog-iceberg0.14.0-0.1.1-with-dependencies.jar
• SPARK_CATALOG: o identificador de catálogo do Spark. Ele está vinculada a um catálogo do BigLake Metastore.
• PROJECT_ID: o ID do projeto do Google Cloud do catálogo do BigLake Metastore ao qual o catálogo do Spark está vinculado.
• LOCATION: o local do Google Cloud do catálogo do BigLake Metastore ao qual o catálogo do Spark está vinculado.
• BLMS_CATALOG: o ID do catálogo do BigLake Metastore ao qual o catálogo do Spark está vinculado. O catálogo não precisa existir e pode ser criado no Spark.
• GCS_DATA_WAREHOUSE_FOLDER: a pasta do Cloud Storage em que o Spark cria todos os arquivos. Ela começa com gs://.
• HMS_DB: (opcional) o banco de dados HMS que contém a tabela da qual copiar.
• HMS_TABLE: (opcional) a tabela HMS da qual copiar.
• HMS_URI: (opcional) o endpoint HMS Thrift.

Conectar-se com um cluster do Dataproc

Como alternativa, é possível enviar um job do Dataproc para um cluster. O exemplo a seguir instala o catálogo personalizado do Iceberg apropriado.

Para se conectar a um cluster do Dataproc, envie um job com as seguintes especificações:

CONFS="spark.sql.catalog.SPARK_CATALOG=org.apache.iceberg.spark.SparkCatalog,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.catalog-impl=org.apache.iceberg.gcp.biglake.BigLakeCatalog,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.gcp_project=PROJECT_ID,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.gcp_location=LOCATION,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.blms_catalog=BLMS_CATALOG,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.warehouse=GCS_DATA_WAREHOUSE_FOLDER,"
CONFS+="spark.jars.packages=ICEBERG_SPARK_PACKAGE"

gcloud dataproc jobs submit spark-sql --cluster=DATAPROC_CLUSTER \
  --project=DATAPROC_PROJECT_ID \
  --region=DATAPROC_LOCATION \
  --jars=BIGLAKE_ICEBERG_CATALOG_JAR \
  --properties="${CONFS}" \
  --file=QUERY_FILE_PATH

Substitua:

• DATAPROC_CLUSTER: o cluster do Dataproc ao qual enviar o job.
• DATAPROC_PROJECT_ID: o ID do projeto do cluster do Dataproc. Esse ID pode ser diferente de PROJECT_ID.
• DATAPROC_LOCATION: o local do cluster do Dataproc. Esse local pode ser diferente de LOCATION.
• QUERY_FILE_PATH: o caminho para o arquivo que contém as consultas a serem executadas.

Conectar-se ao Dataproc sem servidor

Da mesma forma, é possível enviar uma carga de trabalho em lote para o Dataproc sem servidor. Para isso, siga as instruções de carga de trabalho em lote com as seguintes flags adicionais:

• --properties="${CONFS}"
• --jars=BIGLAKE_ICEBERG_CATALOG_JAR

Conectar-se com os procedimentos armazenados do BigQuery

É possível usar procedimentos armazenados do BigQuery para executar jobs do Dataproc sem servidor. O processo é semelhante à execução de jobs do Dataproc sem servidor diretamente no Dataproc.

Criar recursos do Metastore

As seções a seguir descrevem como criar recursos no metastore.

Criar catálogos

Os nomes dos catálogos têm restrições. Para mais informações, consulte Limitações. Para criar um catálogo, selecione uma das seguintes opções:

API

Use o método projects.locations.catalogs.create e especifique o nome de um catálogo.

Spark SQL

CREATE NAMESPACE SPARK_CATALOG;

Terraform

Isso cria um banco de dados do BigLake chamado "my_database" do tipo "HIVE" no catálogo especificado pela variável "google_biglake_catalog.default.id". Para mais informações, consulte a documentação do Terraform no BigLake.

resource "google_biglake_catalog" "default" {
name     = "my_catalog"
location = "US"
}

Criar bancos de dados

Os nomes dos bancos de dados têm restrições. Para mais informações, consulte Limitações. Para garantir que o recurso de banco de dados seja compatível com mecanismos de dados, recomendamos criar bancos de dados usando mecanismos de dados, em vez de criar manualmente o corpo do recurso. Para criar um banco de dados, selecione uma das seguintes opções:

API

Use o método projects.locations.catalogs.databases.create e especifique o nome de um banco de dados.

Spark SQL

CREATE NAMESPACE SPARK_CATALOG.BLMS_DB;

Substitua:

• BLMS_DB: o ID do banco de dados do BigLake Metastore a ser criado

Terraform

Isso cria um banco de dados do BigLake chamado "my_database" do tipo "HIVE" no catálogo especificado pela variável "google_biglake_catalog.default.id". Para mais informações, consulte a documentação do Terraform no BigLake.

resource "google_biglake_database" "default" {
name    = "my_database"
catalog = google_biglake_catalog.default.id
type    = "HIVE"
hive_options {
  location_uri = "gs://${google_storage_bucket.default.name}/${google_storage_bucket_object.metadata_directory.name}"
  parameters = {
    "owner" = "Alex"
  }
}
}

crie tabelas

Os nomes das tabelas têm restrições. Para mais informações, consulte Nomenclatura da tabela. Para criar uma tabela, escolha uma das seguintes opções:

API

Use o método projects.locations.catalogs.databases.tables.create e especifique o nome de uma tabela.

Spark SQL

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

Substitua:

• BLMS_TABLE: o ID da tabela do BigLake Metastore a ser criado

Terraform

Isso cria uma tabela do BigLake Metastore com o nome "my_table" e o tipo "HIVE" no banco de dados especificado pela variável "google_biglake_database.default.id". Consulte a documentação do provedor do Terraform para mais informações: tabela do BigLake.

resource "google_biglake_table" "default" {
name     = "my-table"
database = google_biglake_database.default.id
type     = "HIVE"
hive_options {
  table_type = "MANAGED_TABLE"
  storage_descriptor {
    location_uri  = "gs://${google_storage_bucket.default.name}/${google_storage_bucket_object.data_directory.name}"
    input_format  = "org.apache.hadoop.mapred.SequenceFileInputFormat"
    output_format = "org.apache.hadoop.hive.ql.io.HiveSequenceFileOutputFormat"
  }
  parameters = {
    "spark.sql.create.version"          = "3.1.3"
    "spark.sql.sources.schema.numParts" = "1"
    "transient_lastDdlTime"             = "1680894197"
    "spark.sql.partitionProvider"       = "catalog"
    "owner"                             = "Alex"
    "spark.sql.sources.schema.part.0" = jsonencode({
      "type" : "struct",
      "fields" : [
        { "name" : "id", "type" : "integer",
          "nullable" : true,
          "metadata" : {}
        },
        {
          "name" : "name",
          "type" : "string",
          "nullable" : true,
          "metadata" : {}
        },
        {
          "name" : "age",
          "type" : "integer",
          "nullable" : true,
          "metadata" : {}
        }
      ]
    })
    "spark.sql.sources.provider" = "iceberg"
    "provider"                   = "iceberg"
  }
}
}

Exemplo do E2E Terraform

Este exemplo do GitHub (em inglês) fornece um exemplo E2E executável que cria um catálogo, banco de dados e tabela do Metastore "BigLake". Para mais informações sobre como usar esse exemplo, consulte Comandos básicos do Terraform.

Copiar uma tabela Iceberg do Hive Metastore para o BigLake Metastore

Para criar uma tabela do Iceberg e copiar uma tabela do Hive Metastore para o BigLake Metastore, use a seguinte instrução SQL do Spark:

CREATE TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE
  (id bigint, data string) USING iceberg
  TBLPROPERTIES(hms_table='HMS_DB.HMS_TABLE');

Vincular tabelas do BigLake a tabelas do BigLake Metastore

O BigLake Metastore é o metastore recomendado para consultar tabelas externas do BigLake para o Iceberg. Ao criar uma tabela Iceberg no Spark, você tem a opção de criar uma tabela vinculada BigLake Iceberg ao mesmo tempo.

Vincular tabelas automaticamente

Para criar uma tabela Iceberg no Spark e criar automaticamente uma tabela BigLake Iceberg ao mesmo tempo, use a seguinte instrução SQL do Spark:

  CREATE TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE
    (id bigint, data string) USING iceberg
    TBLPROPERTIES(bq_table='BQ_TABLE_PATH',
    bq_connection='BQ_RESOURCE_CONNECTION');

Substitua:

• BQ_TABLE_PATH: o caminho da tabela Iceberg do BigLake a ser criada. Siga a sintaxe do caminho da tabela do BigQuery. Ela usa o mesmo projeto que o catálogo do BigLake Metastore se o projeto não estiver especificado.

• BQ_RESOURCE_CONNECTION (opcional): o formato é project.location.connection-id. Se especificado, as consultas do BigQuery usam as credenciais de conexão de recurso do Cloud para acessar o BigLake Metastore. Se não for especificado, o BigQuery criará uma tabela externa normal em vez de uma tabela do BigLake.

  Observação: o conjunto de dados do BigQuery em que você quer criar as tabelas já precisa existir. Esta instrução não cria um conjunto de dados. O local dos conjuntos de dados e tabelas do BigQuery precisa ser o mesmo que o catálogo do BigLake Metastore.

Vincular tabelas manualmente

Para criar manualmente links de tabelas BigLake Iceberg com URIs de tabela do BigLake Metastore (blms://…) especificadas, use a seguinte instrução SQL do BigQuery:

CREATE EXTERNAL TABLE 'BQ_TABLE_PATH'
  WITH CONNECTION `BQ_RESOURCE_CONNECTION`
  OPTIONS (
          format = 'ICEBERG',
          uris = ['blms://projects/PROJECT_ID/locations/LOCATION/catalogs/BLMS_CATALOG/databases/BLMS_DB/tables/BLMS_TABLE']
          )

Conferir recursos do Metastore

As seções a seguir descrevem como visualizar recursos no BigLake Metastore.

Conferir catálogos

Para conferir todos os bancos de dados em um catálogo, use o método projects.locations.catalogs.list e especifique o nome de um catálogo.

Para conferir informações sobre um catálogo, use o método projects.locations.catalogs.get e especifique o nome de um catálogo.

Conferir bancos de dados

Para visualizar um banco de dados, faça o seguinte:

API

Para conferir todas as tabelas em um banco de dados, use o método projects.locations.catalogs.databases.list e especifique o nome de um banco de dados.

Para conferir informações sobre um banco de dados, use o método projects.locations.catalogs.databases.get e especifique o nome de um banco de dados.

Spark SQL

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

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

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

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

Ver tabelas

Para visualizar todas as tabelas em um banco de dados ou uma tabela definida, faça o seguinte:

API

Para conferir todas as tabelas em um banco de dados, use o método projects.locations.catalogs.databases.tables.list e especifique o nome de um banco de dados.

Para conferir informações sobre uma tabela, use o método projects.locations.catalogs.databases.tables.get e especifique o nome de uma tabela.

Spark SQL

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

SHOW TABLES IN SPARK_CATALOG.BLMS_DB;

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

DESCRIBE TABLE [EXTENDED] SPARK_CATALOG.BLMS_DB.BLMS_TABLE;

Modificar recursos do metastore

As seções a seguir descrevem como modificar recursos no metastore.

Atualizar tabelas

Para evitar conflitos quando vários jobs tentam atualizar a mesma tabela ao mesmo tempo, o BigLake Metastore usa o bloqueio otimista. Para usar o bloqueio otimista, primeiro você precisa conseguir a versão atual da tabela (chamada de etag) usando o método GetTable. Em seguida, faça alterações na tabela e use o método UpdateTable, transmitindo a etag buscada anteriormente. Se outro job atualizar a tabela depois que você buscar a etag, o método UpdateTable falhará. Essa medida garante que apenas um job possa atualizar a tabela por vez, evitando conflitos.

Para criar uma tabela, escolha uma das seguintes opções:

API

Use o método projects.locations.catalogs.databases.tables.patch e especifique o nome de uma tabela.

Spark SQL

Para opções de atualização de tabela em SQL, consulte ALTER TABLE.

Renomear tabelas

Para renomear uma tabela, selecione uma das seguintes opções:

API

Use o método projects.locations.catalogs.databases.tables.rename e especifique o nome de uma tabela e um valor newName.

Spark SQL

ALTER TABLE BLMS_TABLE RENAME TO NEW_BLMS_TABLE;

Substitua:

• NEW_BLMS_TABLE: o novo nome de BLMS_TABLE. Precisa estar no mesmo conjunto de dados que BLMS_TABLE.

Excluir recursos do Metastore

As seções a seguir descrevem como excluir recursos no BigLake Metastore.

Excluir catálogos

Para excluir um catálogo, selecione uma das seguintes opções:

API

Use o método projects.locations.catalogs.delete e especifique o nome de um catálogo. Esse método não exclui os arquivos associados no Google Cloud.

Spark SQL

DROP NAMESPACE SPARK_CATALOG;

Excluir bancos de dados

Para excluir um banco de dados, selecione uma das seguintes opções:

API

Use o método projects.locations.catalogs.databases.delete e especifique o nome de um banco de dados. Esse método não exclui os arquivos associados no Google Cloud.

Spark SQL

DROP NAMESPACE SPARK_CATALOG.BLMS_DB;

Excluir tabelas

Para excluir uma tabela, selecione uma das seguintes opções:

API

Use o método projects.locations.catalogs.databases.tables.delete e especifique o nome de uma tabela. Esse método não exclui os arquivos associados no Google Cloud.

Spark SQL

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

DROP TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE;

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

DROP TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE PURGE;