Nesta página, explicamos como usar a interface de administrador do metastore do Dataproc.
A interface do administrador oferece uma ferramenta centralizada para inspecionar e gerenciar os metadados armazenados no serviço 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 a Google Cloud CLI ou as APIs do Dataproc Metastore.
Por exemplo, usando a interface do administrador, é possível executar uma consulta SQL diretamente nos metadados de back-end para buscar um nome de tabela específico. Esse processo envolve menos etapas do que o fluxo de trabalho típico, como criar um cluster do Dataproc, se conectar a ele usando SSH, iniciar uma instância do Hive e executar uma consulta (por exemplo, SELECT * FROM table_name
).
Como resultado, a interface do administrador pode ajudar você 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 metastore do Dataproc.
Funções exigidas
Para receber as permissões necessárias para usar a interface de administrador do Dataproc Metastore, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto, com base no princípio de privilégio mínimo:
-
Para consultar metadados do metastore do Dataproc:
Administrador de consultas de metadados (
roles/metastore.metadataQueryAdmin
) na conta de usuário ou de serviço -
Para alterar o local do recurso dos seus metadados, incluindo bancos de dados, tabelas e partições, ou mover uma tabela para outro banco de dados:
-
Administrador de mutação de metadados (
roles/metastore.metadataMutateAdmin
) na conta de usuário ou de serviço -
Editor do Dataproc Metastore (
roles/metastore.editor
) na conta de usuário ou de serviço
-
Administrador de mutação de metadados (
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 do 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 do administrador do metastore do Dataproc:
-
Para consultar metadados do metastore do Dataproc:
metastore.services.queryMetadata
-
Para alterar ou mover tabelas do metastore do Dataproc:
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 metastore do Dataproc, consulte Visão Identity and Access Management do metastore do Dataproc.Operações de administrador compatíveis
Só é possível executar operações da interface de administrador usando a CLI gcloud ou as APIs do Dataproc Metastore. As operações da interface do administrador não são compatíveis com o console Google Cloud .
A interface de administrador é compatível com as seguintes operações.
Operações somente leitura.
- Consultar metadados.
Operações de leitura e gravação.
- Altere o local do recurso dos metadados, incluindo bancos de dados, tabelas e partições.
- Altere as propriedades da tabela, como pares de chave-valor personalizados.
- Mover uma tabela para outro banco de dados.
Se a interface do administrador não for compatível com uma operação diferente, você poderá consultar a metastore do Hive diretamente.
Por exemplo, para listar todas as tabelas em uma instância do metastore do Dataproc, consulte diretamente o esquema do metastore do Hive. Nesse caso, execute
select * from TBLS
para listar todas as tabelas armazenadas no seu serviço.
Consultar metadados
Essa operação permite pesquisar informações de metadados no banco de dados usando consultas SQL. Depois de executar uma consulta, os resultados são despejados no seu bucket artifacts Google Cloud .
Antes de executar essa operação, observe as seguintes considerações:
- As operações compatíveis incluem apenas consultas do MySQL ou do Spanner
read-only
. 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 manualmente os arquivos do seu bucket do Google Cloud . Se você não fizer isso, poderá incorrer em custos extras de armazenamento.
CLI da gcloud
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 seu serviço metastore do Dataproc.LOCATION
: a Google Cloud região em que o serviço do metastore do Dataproc está localizado.QUERY
: a consulta SQL para segmentar seus metadados.- Se você estiver usando um banco de dados MySQL, use uma consulta normal do MySQL.
- Se você estiver usando um banco de dados do Spanner, use uma consulta do GoogleSQL.
Confira o arquivo de saída no bucket Google Cloud de artefatos.
REST
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 seus metadados.- Se você estiver usando um banco de dados MySQL, use uma consulta normal do MySQL.
- Se você estiver usando um banco de dados do Spanner, use uma consulta do GoogleSQL.
PROJECT_ID
: o ID do projeto Google Cloud em que o serviço do Dataproc Metastore reside.SERVICE
: o nome do seu serviço do metastore do Dataproc.LOCATION
: a região em que o metastore do Dataproc está localizado.
O exemplo a seguir mostra um comando de amostra que executa uma consulta select *
de 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 metastore do Dataproc cria automaticamente uma pasta Google Cloud no bucket de artefatos Google Cloud .
O nome dela é query-results
. Após cada execução de consulta bem-sucedida (chamada de API),
uma nova pasta é criada dentro da pasta query-results
, que recebe um nome com um
UUID gerado aleatoriamente.
Cada nova pasta contém um arquivo result manifest
com os resultados da consulta. A localização dessa pasta é retornada 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 arquivoresult manifest
. - Se a consulta resultar em uma falha, o campo
details
vai mostrar a mensagem de erro.
Alterar o local do recurso dos seus metadados
Essa operação permite alterar o local do recurso de um banco de dados, uma tabela ou uma partição.
Quando você executa esse comando, ele atualiza apenas o diretório principal ou o recurso de metadados respectivo. Esse comando não transfere dados para o novo local.
CLI da gcloud
Para alterar o local do recurso dos 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 seu serviço do metastore do Dataproc.LOCATION
: a Google Cloud região em que o serviço do metastore do Dataproc 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 deRESOURCE_NAME
. Esse valor é o caminho para onde você está movendo o local do recurso de metadados. Esse caminho precisa começar comgs://
. Por exemplo,gs://bucket/object
.
Verifique se a mudança de local do recurso foi bem-sucedida.
REST
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 Google Cloud em que o serviço do Dataproc Metastore reside.SERVICE
: o nome do seu serviço metastore do Dataproc.LOCATION
: a região em que o metastore do Dataproc reside.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 deRESOURCE_NAME
. Esse valor é o caminho para onde você está movendo o local do recurso de metadados. Esse caminho precisa começar comgs://
. Por exemplo,gs://bucket/object
.
O exemplo a seguir mostra um comando de amostra 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
Para alterar as propriedades de uma tabela, execute o seguinte comando
gcloud metastore services alter-table-properties
:gcloud metastore services alter-table-properties SERVICE \ --location=LOCATION \ --table-name=TABLE_NAME \ --update-mask=UPDATE_MASK \ --properties=PROPERTIES
Substitua:
SERVICE
: o nome do seu serviço metastore do Dataproc.LOCATION
: a Google Cloud região em que o serviço do metastore do Dataproc 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 sua 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 emUPDATE_MASK
.
REST
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 seu serviço metastore do Dataproc.LOCATION
: a Google Cloud região em que o serviço do metastore do Dataproc 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 sua 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 emUPDATE_MASK
.
O exemplo a seguir mostra um comando de amostra que altera as propriedades de uma tabela chamada test-table
. Neste exemplo, o par de chave-valor 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 (tabela 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
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 seu serviço metastore do Dataproc.LOCATION
: a Google Cloud região em que o serviço Metastore do Dataproc 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.
Verifique se a mudança na tabela foi bem-sucedida.
REST
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 Google Cloud em que o serviço do metastore do Dataproc está localizado.SERVICE
: o nome do seu serviço do metastore do Dataproc.LOCATION
: a região em que o metastore do Dataproc 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 amostra 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