Importar metadados do Snowflake Horizon

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

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

A tabela a seguir lista os metadados que o conector do Snowflake Horizon captura:

Categoria Metadados capturados
Técnico
  • Metastore (conta do Snowflake)
  • Catálogo (banco de dados)
  • Esquema
  • Tabela (incluindo tabelas temporárias, externas, dinâmicas, interativas, híbridas e do Apache Iceberg) e colunas
  • Visualização (padrão, materializada e segura)
  • Estágios (internos e externos), importados como conjuntos de arquivos
  • Funções definidas pelo usuário (UDFs) e procedimentos armazenados
Operacional
  • Métricas de uso (visualizações, leituras e gravações em 30 e 90 dias; usuários frequentes e tabelas unidas com frequência em 30 dias)
  • Chaves primárias e chaves externas
Negócios
  • Tags (tags de objeto, coluna e membro de visualização semântica)
  • Qualidade de dados (expectativas de função de métrica de dados, detecção de anomalias e resultados de monitoramento automático de qualidade de dados)
  • Criação de perfil de dados (medições de função de métrica de dados e resultados de classificação de dados)
  • Mesclagens e relações (inferidas do histórico de consultas, declaradas em visualizações semânticas e dependências de visualização para tabela)
  • Proprietário (papel de proprietário), horário de criação e horário da última alteração
Semântica
  • Visualização semântica (tabelas lógicas, dimensões, fatos, métricas, relacionamentos, sinônimos, valores de amostra e instruções personalizadas)
  • Proprietário da visualização semântica
  • Uso da visualização semântica (visualizações e leituras em 30 e 90 dias; usuários frequentes e tabelas mescladas com frequência em 30 dias)

Limitações

O conector do Snowflake Horizon tem as seguintes limitações:

  • Não há suporte para linhagem.
  • O conector importa os metadados das tabelas do Iceberg, mas não os vincula automaticamente às tabelas físicas subjacentes no Iceberg REST Catalog (IRC).
  • Tags, resultados de qualidade de dados e criação de perfil, resultados de classificação, mesclagens de histórico de consultas e insights de uso que leem ACCESS_HISTORY (usuários frequentes e tabelas mescladas com frequência) exigem o Snowflake Enterprise Edition ou superior.

Antes de começar

Antes de importar metadados do Snowflake Horizon, 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 Snowflake Horizon.
  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 Snowflake Horizon, 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 Snowflake Horizon

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

O conector faz login no Snowflake como um usuário do Snowflake com autenticação de par de chaves e lê metadados do esquema SNOWFLAKE.ACCOUNT_USAGE. A autenticação por senha não é aceita. Um administrador do Snowflake, como um usuário com o papel ACCOUNTADMIN, precisa concluir as seguintes etapas:

  1. Crie um papel para o conector e conceda a ele acesso ao ACCOUNT_USAGE e a um warehouse que executa as consultas de metadados:

    CREATE ROLE IF NOT EXISTS DATAPLEX_CATALOG_READER;
GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE
  TO ROLE DATAPLEX_CATALOG_READER;
GRANT USAGE ON WAREHOUSE WAREHOUSE_NAME
  TO ROLE DATAPLEX_CATALOG_READER;

    Substitua WAREHOUSE_NAME pelo nome do warehouse do Snowflake que executa as consultas de metadados.

  2. Crie um usuário de serviço para o conector ou use um usuário atual e conceda a ele o papel:

    CREATE USER IF NOT EXISTS USERNAME
  TYPE = SERVICE
  DEFAULT_ROLE = DATAPLEX_CATALOG_READER
  DEFAULT_WAREHOUSE = WAREHOUSE_NAME;
GRANT ROLE DATAPLEX_CATALOG_READER TO USER USERNAME;

    Substitua USERNAME pelo nome do usuário do Snowflake para o conector.

  3. Gere um par Chave RSA com a chave privada no formato PKCS#8:

    openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

    Para criptografar a chave privada, substitua -nocrypt por -v2 aes-256-cbc e forneça a senha longa ao configurar o conector. Mantenha o arquivo de chave privada (rsa_key.p8) seguro, porque você o fornecerá ao configurar o conector.

  4. Atribua a chave pública ao usuário do Snowflake:

    ALTER USER USERNAME SET RSA_PUBLIC_KEY='PUBLIC_KEY';

    Substitua PUBLIC_KEY pelo conteúdo de rsa_key.pub, exceto as linhas -----BEGIN PUBLIC KEY----- e -----END PUBLIC KEY-----.

  5. Opcional: para importar outros metadados, conceda ao papel do conector os seguintes privilégios:

    • Perfis de dados e resultados de qualidade de dados: conceda o papel de aplicativo SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER:

      GRANT APPLICATION ROLE SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER
  TO ROLE DATAPLEX_CATALOG_READER;

      Os resultados de qualidade de dados são importados apenas para as verificações que o papel pode visualizar, o que requer USAGE no banco de dados e no esquema, SELECT na tabela e USAGE em funções de métricas de dados personalizadas.

    • Chaves primárias e chaves estrangeiras: conceda USAGE no banco de dados e no esquema, e SELECT ou REFERENCES nas tabelas.

    • Valores de amostra e instruções personalizadas de visualizações semânticas: conceda REFERENCES nas visualizações semânticas.

Para encontrar o identificador da conta que você insere ao configurar o conector, execute a seguinte consulta no Snowflake:

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME();

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 Snowflake Horizon

Configure um conector do Snowflake Horizon usando o console doGoogle 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 Snowflake Horizon.

  4. Na seção Detalhes da fonte de dados, forneça os detalhes de conexão da sua conta do Snowflake:

    • Em Anexo de rede, selecione um anexo de rede existente, se necessário, ou crie um.
    • Em Identificador da conta, insira o identificador da sua conta do Snowflake sem .snowflakecomputing.com (por exemplo, myorg-myaccount). Também é possível inserir um localizador de conta, como xy12345.us-east-2.aws.
    • Em Nome de usuário, insira o usuário do Snowflake que você configurou para a autenticação de par de chaves.
    • Em Chave privada, insira a chave privada PKCS#8 do usuário, como o conteúdo do arquivo rsa_key.p8.
    • Opcional: em Senha longa da chave privada, se a chave privada estiver criptografada, insira a senha longa dela.
    • Opcional: em Warehouse, insira o warehouse que executa as consultas de metadados. Se você não especificar um warehouse, o conector usará o warehouse padrão do usuário.
    • Opcional: em Papel, insira o papel que o conector usa, como DATAPLEX_CATALOG_READER. Se você não especificar um papel, o conector vai usar o papel padrão do usuário.

    • Em Objetos do Snowflake para transferência, clique em Procurar para selecionar os bancos de dados, esquemas ou objetos individuais (tabelas, visualizações, visualizações semânticas, estágios, funções e procedimentos) a serem importados. Selecionar um banco de dados ou esquema importa todos os objetos nele. As funções e os procedimentos são listados com os tipos de argumento, como CALC(NUMBER, VARCHAR).

      Também é possível inserir objetos manualmente no formato TYPE:ACCOUNT/DATABASE[/SCHEMA[/OBJECT]], em que TYPE é CATALOG (ou DATABASE), SCHEMA, TABLE, VIEW, SEMANTIC-MODEL, FILESET, FUNCTION ou PROCEDURE (por exemplo, SCHEMA:myorg-myaccount/SALES/PUBLIC). Insira ACCOUNT no formato ORG_NAME-ACCOUNT_NAME em letras minúsculas, conforme mostrado em Procurar. Os nomes de bancos de dados, esquemas e objetos diferenciam maiúsculas de minúsculas. Não há suporte para padrões de nome.

  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 "snowflake_horizon"
  • 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.accountIdentifier (obrigatório): o identificador da sua conta do Snowflake sem .snowflakecomputing.com (por exemplo, myorg-myaccount) ou um localizador de conta (como xy12345.us-east-2.aws).
    • connector.authentication.username (obrigatório): o usuário do Snowflake.
    • connector.authentication.privateKey (obrigatório): a chave privada do usuário no formato PKCS#8 PEM.
    • connector.authentication.privateKeyPassphrase (opcional): a senha longa da chave privada, se ela estiver criptografada.
    • connector.warehouse (opcional): o warehouse que executa as consultas de metadados. Se você omitir esse parâmetro, o conector vai usar o warehouse padrão do usuário.
    • connector.role (opcional): o papel que o conector usa. Se você omitir esse parâmetro, o conector vai usar o papel padrão do usuário.
    • 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 Snowflake a serem importados no formato TYPE:ACCOUNT/DATABASE[/SCHEMA[/OBJECT]], como ["SCHEMA:myorg-myaccount/SALES/PUBLIC"].
  • Opcional: para manter a chave privada fora da configuração de transferência, armazene-a no Secret Manager:
    1. Defina connector.authentication.privateKey (e connector.authentication.privateKeyPassphrase, se você usar um) 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, uma chave alternada será usada a partir da próxima execução.

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

{
  "displayName": "snowflake-metadata-import",
  "dataSourceId": "snowflake_horizon",
  "schedule": "every 24 hours",
  "params": {
    "connector.accountIdentifier": "myorg-myaccount",
    "connector.authentication.username": "USERNAME",
    "connector.authentication.privateKey": "PRIVATE_KEY",
    "connector.warehouse": "WAREHOUSE_NAME",
    "connector.role": "DATAPLEX_CATALOG_READER",
    "assets": [
      "SCHEMA:myorg-myaccount/SALES/PUBLIC"
    ]
  },
  "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 Snowflake Horizon

Monitore um job do conector do Snowflake Horizon 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 Snowflake Horizon.
  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 Snowflake Horizon

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

    Acesse Pesquisar

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

  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 Snowflake Horizon usando a pesquisa por palavra-chave, digite system=SNOWFLAKE.

    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 Snowflake Horizon. Para mais informações, consulte Recuperar contexto para recursos de dados.

A seguir