Importar metadados do Databricks Unity Catalog

Elimine os silos de dados e evite alternar entre ferramentas usando um conector do Knowledge Catalog (antigo Dataplex Universal Catalog) para importar metadados do Databricks Unity Catalog diretamente para o Google Cloud.

Esse conector é compatível com instâncias do Databricks Unity Catalog hospedadas no Google Cloud, no Microsoft Azure ou no Amazon Web Services (AWS).

A tabela a seguir lista os metadados que o conector do Databricks Unity Catalog captura:

Categoria Metadados capturados
Técnico
  • Metastore
  • Catálogo
  • Esquema
  • Tabela (Delta gerenciado, externa, streaming, on-line, recurso, catálogo REST do Apache Iceberg (IRC))
  • Visualização (padrão, materializada)
  • Volumes
  • Funções e procedimentos
Operacional
  • Métricas de uso (visualizações em 30 e 90 dias; leituras, gravações, usuários frequentes e tabelas mescladas com frequência em 30 dias)
  • Chaves primárias e externas
Negócios
  • Tags (objeto, classificação de dados)
  • Qualidade de dados (resultados de detecção de anomalias do monitoramento de qualidade de dados, desvio de dados e métricas personalizadas do monitoramento do Lakehouse)
  • Criação de perfil de dados (do Lakehouse Monitoring)
  • Mesclagens e relações
  • Proprietário da tabela e da visualização, horário de criação e horário da última alteração
Semântica
  • Visualização de métricas (dimensões, medidas, mapeamento de relacionamentos, certificações)
  • Proprietário da visualização de métricas
  • Uso da visualização de métricas (visualizações em 30 e 90 dias; leituras, gravações, usuários frequentes e tabelas unidas com frequência em 30 dias)
  • Nomes de exibição (das visualizações de métricas)
  • Sinônimos (das visualizações de métricas)
  • Comentários em Markdown

Limitações

O conector do Databricks Unity Catalog tem as seguintes limitações:

  • Não há suporte para linhagem.
  • As tags semânticas e os glossários empresariais não são compatíveis com a integração (API Genie).
  • O conector importa os metadados das tabelas do Iceberg, mas não vincula automaticamente as entradas importadas às entradas correspondentes do Iceberg REST Catalog (IRC) do Lakehouse Databricks Unity Catalog Google Cloud .

Antes de começar

Antes de importar metadados do Databricks Unity Catalog, conclua as seguintes tarefas:

  1. Conceda os papéis e as permissões necessários.
  2. Ative a API Dataplex e a API do serviço de transferência de dados do BigQuery.
  3. Atenda aos pré-requisitos do Databricks Unity Catalog.
  4. Atenda aos pré-requisitos de rede.

Permissões e papéis do IAM

Para criar e gerenciar um job do conector do Knowledge Catalog, você precisa de papéis do Identity and Access Management (IAM) que concedem permissões para o Knowledge Catalog e o serviço de transferência de dados do BigQuery.

Para receber as permissões necessárias para configurar um conector do Databricks Unity Catalog, peça ao administrador para conceder a você os seguintes papéis do IAM:

Você também precisa conceder ao agente de serviço do serviço de transferência de dados do BigQuery (service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com) os dois papéis a seguir:

  • Importador de grupo de entrada do Dataplex (roles/dataplex.entryGroupImporter), no grupo de entrada de destino ou no projeto que o contém. Esse papel permite que o agente de serviço importe metadados para o grupo de entrada (dataplex.entryGroups.import).

  • Proprietário de entradas e links de entradas do Dataplex (roles/dataplex.entryOwner), no projeto que contém o grupo de entrada de destino. Esse papel permite que o agente de serviço importe metadados de uso, negócios e qualidade de dados, além de links de entrada. Ele inclui as seguintes permissões:

    • dataplex.entryGroups.useDataProfileAspect
    • dataplex.entryGroups.useDataQualityScorecardAspect
    • dataplex.entryGroups.useManagedConnectorTypes
    • dataplex.entryGroups.useReferenceEntryLink
    • dataplex.entryGroups.useSchemaAspect
    • dataplex.entryGroups.useSchemaJoinAspect
    • dataplex.entryGroups.useSchemaJoinEntryLink
    • dataplex.entryGroups.useUsageAspect
    • dataplex.entryLinks.reference

    Conceda esse papel no projeto, não apenas no grupo de entrada, porque a importação verifica a permissão dataplex.entryLinks.reference no projeto. Se o agente de serviço não tiver essa permissão no projeto, a execução da transferência vai falhar com um erro como Permission 'dataplex.entryLinks.reference' denied, e nenhum metadado será importado.

Em vez de conceder esses dois papéis, é possível conceder o papel de Proprietário do grupo de entrada do Dataplex (roles/dataplex.entryGroupOwner) no projeto que contém o grupo de entrada de destino. Esse papel inclui as permissões de ambos os papéis e também permite que o agente de serviço crie, exclua e gerencie o acesso a todos os grupos de entrada no projeto.

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Ativar APIs

Ative a API Dataplex e a API serviço de transferência de dados do BigQuery.

Ativar as APIs

Pré-requisitos do Databricks Unity Catalog

A entidade de serviço usada para o conector do Databricks Unity Catalog precisa ter as seguintes permissões no Databricks Unity Catalog:

  • Permissão Can use no data warehouse do Databricks SQL usado pelo conector.
  • Privilégio BROWSE nos catálogos de destino ou USE CATALOG, USE SCHEMA e SELECT nos catálogos, esquemas e tabelas ou visualizações de destino.
  • USE CATALOG no catálogo system, além de USE SCHEMA e SELECT nos seguintes esquemas do sistema:
    • system.information_schema: necessário para ler catálogos, esquemas, tabelas, colunas, volumes, rotinas, restrições e tags.
    • system.access e system.query: opcionais, necessários para importar métricas de uso, insights de uso e mesclagens de histórico de consultas.
    • system.data_quality_monitoring: opcional, obrigatório para importar resultados de detecção de anomalias.
  • Opcional: USE CATALOG, USE SCHEMA e SELECT nas tabelas de saída do Lakehouse Monitoring (TABLE_NAME_profile_metrics e TABLE_NAME_drift_metrics) para importar métricas de criação de perfil de dados e desvio.

Se você também quiser executar consultas SQL ou jobs do Spark no catálogo remoto do Databricks, consulte Configurar uma conexão entre nuvens para o catálogo do Databricks Unity.

Pré-requisitos de rede

Para permitir que o serviço de transferência de dados do BigQuery se conecte com segurança a bancos de dados externos ou fontes de dados em nuvem de terceiros com um endereço IP privado dentro de uma rede privada, configure um anexo de rede pelo Private Service Connect.

Se você se conectar a um ambiente local ou a uma instância hospedada na nuvem usando um endereço IP público, não será necessário um anexo de rede.

Configurar um conector do Databricks Unity Catalog

Configure um conector do Databricks Unity Catalog usando o console do Google Cloud ou a API REST.

Console

  1. No console Google Cloud , acesse a página do Knowledge Catalog.

    Acessar o Knowledge Catalog

  2. No menu de navegação, na seção Gerenciar, clique em Conectores e em Adicionar conexão.

  3. Na lista Conectores, selecione o card Databricks Unity Catalog.

  4. Na seção Detalhes da fonte de dados, forneça os detalhes de conexão da sua instância do Databricks Unity Catalog:

    • Em Anexo de rede, selecione um anexo de rede existente, se necessário, ou crie um.
    • Insira o host do espaço de trabalho, o caminho HTTP do SQL Warehouse, o ID do cliente e a chave secreta do cliente.

    • Em Objetos do Databricks para transferência, clique em Procurar para selecionar os metastores, catálogos, esquemas ou objetos individuais (tabelas, visualizações, volumes, funções e procedimentos) a serem importados para o Knowledge Catalog. Selecionar um metastore, catálogo ou esquema importa todos os objetos nele.

      Também é possível inserir objetos manualmente no formato TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]], em que TYPE é METASTORE, CATALOG, SCHEMA, TABLE, VIEW, VOLUME, FUNCTION ou PROCEDURE (por exemplo, SCHEMA:my_metastore/main/sales). Padrões de nome não são compatíveis.

  5. Na seção Configurações de destino:

    • Clique em Procurar e selecione um grupo de entradas do Knowledge Catalog para armazenar os metadados importados ou clique em Criar novo grupo de entradas.
    • Selecione se você quer definir as permissões no grupo de entrada agora ou mais tarde. Para permitir que os usuários vejam os metadados importados, defina permissões no grupo de entrada. Se você não concedeu o papel de Importador de grupo de entrada do Dataplex (roles/dataplex.entryGroupImporter) ou a permissão dataplex.entryGroups.import ao agente de serviço do serviço de transferência de dados do BigQuery no nível do projeto, conceda-o nesse grupo de entrada. Ainda é necessário conceder o papel de Proprietário de entradas e links de entradas do Dataplex (roles/dataplex.entryOwner) no projeto, porque a permissão dataplex.entryLinks.reference é verificada no nível do projeto. Para mais informações, consulte Papéis e permissões do IAM.

  6. No campo Nome de exibição da seção Nome de configuração da transferência, insira um nome para o job de importação de metadados.

  7. Na seção Opções de programação, configure a frequência do job de importação de metadados. Se você selecionar On demand, o job só será executado quando você o acionar manualmente.

  8. Opcional: na seção Opções de notificação, configure uma notificação por e-mail ou Pub/Sub para falhas de job.

  9. Opcional: na seção Opções avançadas, defina as configurações de criptografia. Se você selecionar uma chave de criptografia gerenciada pelo cliente (CMEK), ela vai criptografar todos os dados temporários preparados antes de iniciar os jobs de importação de metadados do Knowledge Catalog. A chave não criptografa os metadados no grupo de entrada de destino do Knowledge Catalog.

  10. Clique em Salvar.

REST

Use o método projects.locations.transferConfigs.create. No recurso TransferConfig, configure os seguintes campos:

  • Defina o campo dataSourceId como "databricks_unity"
  • No campo metadataDestination, preencha o campo dataplexConfiguration.entryGroup com o caminho do recurso do grupo de entrada de destino do Knowledge Catalog: projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID.
  • No campo params, defina os seguintes parâmetros:
    • connector.host (obrigatório): o nome do host do espaço de trabalho do Databricks (por exemplo, dbc-a1b2345c-d6e7.cloud.databricks.com).
    • connector.httpPath (obrigatório): o caminho HTTP do SQL warehouse do Databricks (por exemplo, /sql/1.0/warehouses/a1b2345c67890def).
    • connector.authentication.oauth.clientId (obrigatório): o ID do cliente OAuth do Databricks.
    • connector.authentication.oauth.clientSecret (obrigatório): a chave secreta do cliente OAuth do Databricks.
    • connector.networkAttachment (opcional): o anexo de rede no formato projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_ID.
    • assets (obrigatório): a lista de objetos do Databricks Unity Catalog a serem importados no formato TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]], como ["SCHEMA:my_metastore/main/sales"].
  • Opcional: para manter as credenciais do OAuth fora da configuração de transferência, armazene-as no Secret Manager:
    1. Defina connector.authentication.oauth.clientSecret (e connector.authentication.oauth.clientId, se quiser) como o nome do recurso da versão do secret no formato projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID e adicione esses nomes de parâmetro ao campo paramConfig.secretManagerManagedParams.
    2. Conceda o papel de Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) em cada secret ao agente de serviço do serviço de transferência de dados do BigQuery do projeto que contém a configuração de transferência (service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com). Os secrets podem estar em um projeto diferente. Se o agente de serviço não conseguir ler um secret, a execução vai falhar antes de começar com um erro como Failed to retrieve secret ... Permission 'secretmanager.versions.access' denied. O serviço de transferência de dados do BigQuery lê os secrets no início de cada execução. Portanto, se você definir VERSION_ID como latest, um secret alternado será usado a partir da próxima execução.

O exemplo a seguir mostra um corpo de solicitação TransferConfig:

{
  "displayName": "databricks-unity-metadata-import",
  "dataSourceId": "databricks_unity",
  "schedule": "every 24 hours",
  "params": {
    "connector.host": "dbc-a1b2345c-d6e7.cloud.databricks.com",
    "connector.httpPath": "/sql/1.0/warehouses/a1b2345c67890def",
    "connector.authentication.oauth.clientId": "CLIENT_ID",
    "connector.authentication.oauth.clientSecret": "CLIENT_SECRET",
    "assets": [
      "SCHEMA:my_metastore/main/sales"
    ]
  },
  "metadataDestination": {
    "dataplexConfiguration": {
      "entryGroup": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID"
    }
  }
}

O job é executado automaticamente com base na sua programação, ou você pode acioná-lo manualmente.

Monitorar um job do conector do Databricks Unity Catalog

Monitore um job do conector do Databricks Unity Catalog usando o console doGoogle Cloud ou a API REST.

Console

  1. No console do Google Cloud , na página Conectores, clique no Nome de exibição do job de transferência do Databricks Unity Catalog.
  2. Na guia Histórico de execução, clique em Ver detalhes para conferir os registros.
  3. Para ver as entradas criadas, clique na guia Detalhes e, em seguida, no link do grupo de entradas Destino de metadados.

REST

  • Para listar as execuções de uma configuração de transferência e conferir o estado delas, use o método projects.locations.transferConfigs.runs.list.

  • Cada execução importa os metadados coletados para o Knowledge Catalog com um job de importação de metadados com o ID dts-run-RUN_ID. Para ver o resultado da importação, como o número de entradas criadas, filtre os registros do job no Logging usando a seguinte consulta:

    logName="projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fmetadata_job"
AND resource.labels.metadata_job_id="dts-run-RUN_ID"

  • Para ver o resultado de uma importação sem usar o Logging, chame o método projects.locations.metadataJobs.get em projects/PROJECT_ID/locations/LOCATION/metadataJobs/dts-run-RUN_ID. O campo importResult mostra o número de entradas e links de entrada criados, atualizados, inalterados e excluídos.

Pesquisar e visualizar metadados do Databricks Unity Catalog

  1. No console Google Cloud , acesse a página Pesquisa do Knowledge Catalog.

    Acesse Pesquisar

  2. No painel Filtros, filtre os recursos do Databricks Unity Catalog usando as seções Projeto, Sistemas e Aliases de tipo. Para filtrar todos os metadados do Databricks Unity Catalog, na seção Sistemas, selecione Contexto importado e, na subseção Conectores gerenciados, selecione Databricks Unity.

  3. No campo de pesquisa, digite uma palavra-chave ou uma consulta de pesquisa com linguagem natural. Por exemplo, para ver todos os recursos do Databricks Unity Catalog usando a pesquisa por palavra-chave, digite system=DATABRICKS.

    Para saber mais sobre como pesquisar recursos, consulte Pesquisar recursos no Knowledge Catalog. Para saber mais sobre as expressões que podem ser usadas no campo de pesquisa, consulte Sintaxe de pesquisa do Knowledge Catalog.

Também é possível usar a API LookupContext para recuperar o contexto do LLM para recursos específicos do Databricks Unity Catalog. Para mais informações, consulte Recuperar contexto para recursos de dados.

A seguir