Interface do administrador do Dataproc Metastore

Nesta página, explicamos como usar a interface de administrador do Dataproc Metastore.

A interface do administrador oferece uma ferramenta centralizada para inspecionar e gerenciar os metadados armazenados no serviço do metastore do Dataproc, sem precisar se conectar a um cluster do Dataproc ou a uma instância do Hive. Em vez disso, gerencie seus metadados com as APIs CLI gcloud ou Dataproc Metastore.

Por exemplo, usando a interface do administrador, é possível executar uma consulta SQL diretamente nos metadados do back-end para buscar um nome de tabela específico. Esse processo envolve seguir menos etapas do que o fluxo de trabalho típico, como criar um cluster do Dataproc, conectar-se ao cluster usando SSH, iniciar uma instância do Hive e, por fim, executar uma consulta (por exemplo, SELECT * FROM table_name).

Como resultado, a interface do administrador pode ajudar a economizar tempo e diminuir a quantidade de recursos do Google Cloud necessários para recuperar seus dados.

Antes de começar

• Ative o Dataproc Metastore no seu projeto.
• Crie um serviço Metastore do Dataproc.
• Importe metadados para o Dataproc Metastore.

Funções exigidas

Para receber as permissões necessárias para usar a interface de administrador do Dataproc Metastore, peça que o administrador conceda a você os seguintes papéis do IAM no projeto, com base no princípio de privilégio mínimo:

• Para consultar os metadados do Dataproc Metastore: Administrador de consultas de metadados (roles/metastore.metadataQueryAdmin) na conta de usuário ou de serviço
• Para alterar o local de recursos dos metadados, incluindo bancos de dados, tabelas e partições, ou mover uma tabela para outro banco de dados:
  • Mutação de administrador de metadados (roles/metastore.metadataMutateAdmin) na conta de usuário ou de serviço
  • Editor do metastore do Dataproc (roles/metastore.editor) na conta de usuário ou de serviço

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para usar a interface de administrador do Dataproc Metastore. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para usar a interface de administrador do Dataproc Metastore:

• Para consultar os metadados do Dataproc Metastore: metastore.services.queryMetadata
• Para alterar ou mover tabelas do Dataproc Metastore: metastore.services.mutateMetadata

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para mais informações sobre papéis e permissões específicos do Dataproc Metastore, consulte Visão geral do IAM do Dataproc Metastore.

Operações de administrador com suporte

Só é possível executar operações de interface de administrador usando a CLI gcloud ou as APIs do Metastore do Dataproc. As operações da interface de administrador não são compatíveis com o Console do Google Cloud.

A interface do administrador oferece suporte às seguintes operações.

• Operações somente leitura.

  • Consultar metadados.
  Aviso: execute apenas consultas somente leitura de forma interativa. Não automatize nem execute consultas somente leitura não interativas em processos críticos para a produção. A execução de consultas não interativas pode causar problemas se o esquema do banco de dados subjacente mudar sem aviso prévio.

• Operações de leitura e gravação.

  • Altere o local do recurso dos metadados, incluindo bancos de dados, tabelas e partições.
  • Alterar propriedades da tabela, como pares de chave-valor personalizados.
  • Mover uma tabela para outro banco de dados.

Consultar metadados

Essa operação permite que você procure informações de metadados no seu banco de dados usando consultas SQL. Depois que você executa uma consulta, os resultados são transferidos para o bucket de artefatos do Google Cloud.

Antes de executar essa operação, observe as seguintes considerações:

• As operações com suporte incluem apenas consultas read-only MySQL ou Spanner. Se a consulta tentar modificar os dados, a operação vai falhar.
• O arquivo de saída contém no máximo 1.000 linhas. Não é possível mudar essa configuração.

• Os arquivos de saída não são excluídos automaticamente. Em vez disso, exclua-os manualmente do bucket do Google Cloud. Se você não fizer isso, poderá incorrer em custos de armazenamento extras.

CLI da gcloud

1. Para consultar metadados, execute o seguinte comando gcloud metastore services query-metadata:

   gcloud metastore services query-metadata SERVICE \
     --location=LOCATION \
     --query=QUERY

   Substitua:

   • SERVICE: o nome do serviço do metastore do Dataproc.
   • LOCATION: a região do Google Cloud em que o serviço do Dataproc Metastore está localizado.
   • QUERY: a consulta SQL para segmentar seus metadados.
     • Se você estiver usando um banco de dados MySQL, use uma consulta MySQL regular.
     • Se você estiver usando um banco de dados do Spanner, use uma consulta do GoogleSQL.

2. Acesse o arquivo de saída no bucket de artefatos do Google Cloud.

REST

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário. Para fazer login, execute gcloud init ou gcloud auth login, ou use o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa executando gcloud auth list.

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -X POST -d '{"query": "QUERY"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:queryMetadata

Substitua:

• QUERY: a consulta SQL que você está usando para segmentar os metadados.
  • Se você estiver usando um banco de dados MySQL, use uma consulta MySQL regular.
  • Se você estiver usando um banco de dados do Spanner, use uma consulta do GoogleSQL.
• PROJECT_ID: o ID do projeto do Google Cloud em que o serviço Dataproc Metastore reside.
• SERVICE: o nome do serviço do metastore do Dataproc.
• LOCATION: a região em que o Dataproc Metastore está localizado.

O exemplo a seguir mostra um comando de exemplo que executa uma consulta select * em um banco de dados chamado DBS.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" -X POST -d  '{"query": "select * from DBS;"}' \
  https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:queryMetadata

Interpretar a saída de uma operação de metadados de consulta

Quando você executa um comando de metadados de consulta pela primeira vez, o Dataproc Metastore cria automaticamente uma pasta do Google Cloud no bucket de artefatos do Google Cloud. Essa pasta é chamada de query-results. Depois de cada execução de consulta bem-sucedida (chamada de API), uma nova pasta é criada na pasta query-results, que é nomeada com um UUID gerado aleatoriamente.

Cada nova pasta contém um arquivo result manifest com os resultados da consulta. O local dessa pasta é retornado na resposta da chamada de API.

Por exemplo, na resposta, o campo resultManifestUri contém o local do arquivo.

"response": {
    "@type": "type.googleapis.com/google.cloud.metastore.QueryMetadataResponse",
    "resultManifestUri": "gs://gcs-bucket-6a3638b8-e319-46363-ad33-e632a5e/query-results/800156f5-2d13-4b80-bec3-2345a9e880f6/result-manifest"
  }

A saída do arquivo result manifest é semelhante a esta:

{
  "status": {
    "code": 0,
    "message": "Query results are successfully uploaded to cloud storage",
    "details": []
  },
  "filenames": ["result-001"]
}

Detalhes do arquivo de manifesto do resultado:

• O campo status mostra se a consulta foi bem-sucedida ou não.
• Se a execução da consulta for bem-sucedida, o campo filenames vai listar todos os arquivos criados. Esses arquivos estão na mesma pasta que o arquivo result manifest.
• Se a consulta resultar em uma falha, o campo details vai mostrar a mensagem de erro.

Observação: por padrão, os arquivos de saída não têm um TTL (time to live). É necessário excluí-los manualmente do bucket do Google Cloud ou criar uma regra de TTL personalizada na pasta query-results. Se você não fizer isso, poderá incorrer em custos de armazenamento extra.

Alterar o local do recurso dos metadados

Essa operação permite alterar o local do recurso de um banco de dados, tabela ou partição.

Quando você executa esse comando, ele só atualiza o diretório pai ou o respectivo recurso de metadados. Esse comando não transfere dados para o novo local.

CLI da gcloud

1. Para alterar o local do recurso de metadados, execute o seguinte comando gcloud metastore services alter-metadata-resource-location:

   gcloud metastore services alter-metadata-resource-location SERVICE \
     --location=LOCATION \
     --resource_name=RESOURCE_NAME \
     --location_uri=LOCATION_URI

   Substitua:

   • SERVICE: o nome do serviço do metastore do Dataproc.
   • LOCATION: a região do Google Cloud em que o serviço do Dataproc Metastore está localizado.
   • RESOURCE_NAME: o nome do banco de dados, da tabela ou da partição que você está alterando.
   • LOCATION_URI: o novo caminho do Cloud Storage para o conteúdo de RESOURCE_NAME. Esse valor é o caminho para onde você está movendo o local do recurso de metadados. Esse caminho precisa começar com gs://. Por exemplo, gs://bucket/object.

2. Verifique se a mudança de local do recurso foi bem-sucedida.

REST

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário. É possível fazer login executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que conta executando gcloud auth list.

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"resource_name": "RESOURCE_NAME", "location_uri":"LOCATION_URI"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterLocation

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud em que o serviço Dataproc Metastore reside.
• SERVICE: o nome do serviço do metastore do Dataproc.
• LOCATION: a região em que o Dataproc Metastore está localizado.
• RESOURCE_NAME: o nome do banco de dados, da tabela ou da partição que você está alterando.
• LOCATION_URI: o novo caminho do Cloud Storage para o conteúdo de RESOURCE_NAME. Esse valor é o caminho para onde você está movendo o local do recurso de metadados. Esse caminho precisa começar com gs://. Por exemplo, gs://bucket/object.

O exemplo a seguir mostra um comando que move uma tabela chamada test-table2 para um novo bucket do Cloud Storage.

 curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -X POST -d  '{"resource_name": "databases/testdb1/tables/test-table2",
   "location_uri":"gs://gcs-bucket-dpms1-9425bd83-b794-4f1c-9e79-2d833f758cc1/empty"}'
   https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:alterLocation

Alterar propriedades da tabela

Essa operação permite alterar as propriedades de uma tabela, como um par de chave-valor personalizado que você está usando para armazenar dados. Por exemplo, é possível mudar um par de chave-valor de properties.customerID_1 para properties.customerID_2.

CLI da gcloud

1. Para alterar as propriedades de uma tabela, execute o comando gcloud metastore services alter-table-properties a seguir:

   gcloud metastore services alter-table-properties SERVICE \
     --location=LOCATION \
     --table-name=TABLE_NAME \
     --update-mask=UPDATE_MASK \
     --properties=PROPERTIES

   Substitua:

   • SERVICE: o nome do serviço do metastore do Dataproc.
   • LOCATION: a região do Google Cloud em que o serviço do Dataproc Metastore está localizado.
   • TABLE_NAME: o nome da tabela que contém as propriedades que você está alterando no seguinte formato, databases/{database_id}/tables/{table_id}.
   • UPDATE_MASK: os valores de propriedade atuais que você está atualizando. Use uma lista separada por vírgulas para descrever os pares de chave-valor, por exemplo, properties.1,properties.2,properties.3,....
   • PROPERTIES: as novas propriedades da tabela. Use uma lista separada por vírgulas para descrever os pares de chave-valor. Por exemplo, a=1,b=2,c=3,.... Os valores listados aqui substituem os valores em UPDATE_MASK.

REST

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário. Você pode fazer login executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. Execute o comando gcloud auth list para verificar a conta ativa.

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "update_mask":"UPDATE_MASK", "properties":PROPERTIES}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterTableProperties

Substitua:

• SERVICE: o nome do serviço do metastore do Dataproc.
• LOCATION: a região do Google Cloud em que o serviço do Dataproc Metastore está localizado.
• TABLE_NAME: o nome da tabela que contém as propriedades que você está alterando no seguinte formato, databases/{database_id}/tables/{table_id}.
• UPDATE_MASK: os valores de propriedade atuais que você está atualizando. Use uma lista separada por vírgulas para descrever os pares de chave-valor, por exemplo, properties.1,properties.2,properties.3,....
• PROPERTIES: as novas propriedades da tabela. Use uma lista separada por vírgulas para descrever os pares de chave-valor, por exemplo, a=1,b=2,c=3,.... Os valores listados aqui substituem os valores em UPDATE_MASK.

O exemplo a seguir mostra um comando de exemplo que altera as propriedades de uma tabela chamada test-table. Neste exemplo, o par de chave-valor existente, properties.customerID_1, é atualizado para o novo valor properties.customerID_2.

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -X POST -d  '{"table_name": "databases/default/tables/test-table", "update_mask":{"paths":"properties.customerID_1"}, "properties":{"customerID_1":"customerID_2"}}' https://metastore.googleapis.com/projects/dpms-p

Mover uma tabela para outro banco de dados

Essa operação permite mover uma tabela interna (gerenciada) para outro banco de dados. Nesse caso, o diretório pai do banco de dados e os dados dele são movidos.

Não é possível mover dados armazenados em tabelas externas.

CLI da gcloud

1. Para mover uma tabela para outro banco de dados, execute o seguinte comando gcloud metastore services move-table-to-database:

   gcloud metastore services move-table-to-database SERVICE \
     --location=LOCATION \
     --db_name=DB_NAME \
     --table_name=TABLE_NAME \
     --destination_db_name=DESTINATION_DB_NAME

   Substitua:

   • SERVICE: o nome do serviço do metastore do Dataproc.
   • LOCATION: a região do Google Cloud em que o serviço do Dataproc Metastore está localizado.
   • DB_NAME: o nome do banco de dados de origem que contém a tabela que você quer mover.
   • TABLE_NAME: o nome da tabela que você quer mover.
   • DESTINATION_DB_NAME: o nome do novo banco de dados para onde você quer mover a tabela.

2. Verifique se a mudança na tabela foi concluída.

REST

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário. Para fazer login, execute gcloud init ou gcloud auth login, ou use o Cloud Shell, que faz login automaticamente na CLI gcloud. Execute o comando gcloud auth list para verificar a conta ativa.

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "db_name": "DB_NAME", "destination_db_name": "DESTINATION_DB_NAME"}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:moveTableToDatabase

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud em que o serviço do Dataproc Metastore está localizado.
• SERVICE: o nome do serviço do metastore do Dataproc.
• LOCATION: a região em que o Dataproc Metastore está localizado.
• DB_NAME: o nome do banco de dados de origem que contém a tabela que você quer mover.
• TABLE_NAME: o nome da tabela que você quer mover.
• DESTINATION_DB_NAME: o nome do novo banco de dados para onde você quer mover a tabela.

O exemplo a seguir mostra um comando de exemplo que move um banco de dados chamado testdb1 para outro banco de dados chamado testdb2.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json"
 -X POST -d  '{"table_name": "testtb1", "db_name": "testdb1",
 "destination_db_name": "testdb2"}' https://metastore.googleapis.com/projects/dpms/locations/asia-northeast2/services/dpms1:moveTableToDatabase

A seguir

• Exportar metadados
• Atualizar uma metastore
• Fazer backup de um metastore