从 Snowflake Horizon 导入元数据

使用 Knowledge Catalog（原 Dataplex Universal Catalog）连接器将元数据从 Snowflake Horizon 直接导入 Google Cloud，从而打破数据孤岛，避免在工具之间切换。

此连接器支持托管在Google Cloud、Microsoft Azure 或 Amazon Web Services (AWS) 上的 Snowflake Horizon 实例。

下表列出了 Snowflake Horizon 连接器捕获的元数据：

类别	已捕获元数据
技术	Metastore（Snowflake 账号） 目录（数据库） 架构 表（包括临时表、外部表、动态表、交互式表、混合表和 Apache Iceberg 表）和列 视图（标准视图、物化视图和安全视图） 暂存区（内部和外部），作为文件集导入 用户定义的函数 (UDF) 和存储过程
可运行	使用情况指标（30 天和 90 天内的查看、读取和写入次数；30 天内的频繁用户和频繁联接的表） 主键和外键
商务版	标记（对象、列和语义视图成员标记） 数据质量（数据指标函数预期、异常值检测和自动数据质量监控结果） 数据分析（数据指标函数测量和数据分类结果） 联接和关系（从查询历史记录中推断、在语义视图中声明，以及视图到表的依赖关系） 所有者（所有者角色）、创建时间和上次更改时间
语义	语义视图（逻辑表、维度、事实、指标、关系、同义词、示例值和自定义说明） 语义视图所有者 语义视图使用情况（30 天和 90 天内的视图和读取次数；30 天内的频繁用户和频繁联接的表）

限制

Snowflake Horizon 连接器具有以下限制：

• 不支持沿袭。
• 连接器会导入 Iceberg 表的元数据，但不会自动将这些元数据关联到 Iceberg REST Catalog (IRC) 中的底层物理表。
• 读取 ACCESS_HISTORY 的标记、数据质量和分析结果、分类结果、查询历史记录联接以及使用情况数据分析（频繁用户和频繁联接的表）需要 Snowflake 企业版或更高版本。

准备工作

在从 Snowflake Horizon 导入元数据之前，请完成以下任务：

1. 授予所需的角色和权限。
2. 启用 Dataplex API 和 BigQuery Data Transfer Service API。
3. 满足 Snowflake Horizon 前提条件。
4. 满足网络前提条件。

IAM 角色和权限

如需创建和管理 Knowledge Catalog 连接器作业，您需要拥有授予 Knowledge Catalog 和 BigQuery Data Transfer Service 权限的 Identity and Access Management (IAM) 角色。

如需获得配置 Snowflake Horizon 连接器所需的权限，请让您的管理员为您授予以下 IAM 角色：

• 如需创建和管理条目组，您需要拥有项目的 Dataplex Catalog Admin (roles/dataplex.catalogAdmin)、Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) 角色。
• 如需查看 Snowflake Horizon 元数据，您需要拥有项目的 Dataplex Catalog Viewer (roles/dataplex.catalogViewer) 角色。
• 创建和管理 BigQuery Data Transfer Service 转移作业：项目的 BigQuery Admin (roles/bigquery.admin) 角色。
• 如需在 Cloud Logging 中查看日志，您需要拥有项目的 日志查看器 (roles/logging.viewer) 角色。

您还必须向 BigQuery Data Transfer Service 服务代理 (service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.) 授予以下两个角色：

• 目标条目组或包含该条目组的项目上的 Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter)。此角色允许服务代理将元数据导入条目组 (dataplex.entryGroups.import)。

• 针对包含目标条目组的项目的 Dataplex Entry and EntryLink Owner (roles/dataplex.entryOwner)。此角色可让服务代理导入使用情况、业务和数据质量元数据以及条目链接。它拥有以下权限：

  • 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

  请在项目（而不仅仅是条目群组）上授予此角色，因为导入操作会检查项目的 dataplex.entryLinks.reference 权限。如果服务代理在项目中没有此权限，则转移作业运行会失败并显示 Permission 'dataplex.entryLinks.reference' denied 等错误，并且不会导入任何元数据。

您可以改为针对包含目标条目组的项目授予 Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) 角色，而无需同时授予这两个角色。此角色包含这两个角色的权限，还允许服务代理创建、删除和管理对项目中所有条目群组的访问权限。

如需详细了解如何授予角色，请参阅管理访问权限。

启用 API

启用 Dataplex API 和 BigQuery Data Transfer Service API。

启用 API

Snowflake Horizon 前提条件

如果您还想针对远程 Snowflake 目录运行 SQL 查询或 Spark 作业，请参阅为 Snowflake Horizon 目录设置跨云连接。

连接器以 Snowflake 用户的身份登录 Snowflake，并使用密钥对身份验证，然后从 SNOWFLAKE.ACCOUNT_USAGE 架构中读取元数据。不支持密码身份验证。Snowflake 管理员（例如具有 ACCOUNTADMIN 角色的用户）必须完成以下步骤：

1. 为连接器创建一个角色，并向其授予对 ACCOUNT_USAGE 以及运行元数据查询的仓库的访问权限：

   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;
   

   将 WAREHOUSE_NAME 替换为运行元数据查询的 Snowflake 仓库的名称。

2. 为连接器创建服务用户或使用现有用户，并为其授予以下角色：

   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;
   

   将 USERNAME 替换为连接器的 Snowflake 用户的名称。

3. 生成 RSA 密钥对，其中私钥采用 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
   

   如需加密私钥，请将 -nocrypt 替换为 -v2 aes-256-cbc，并在配置连接器时提供口令。请妥善保管私钥文件 (rsa_key.p8)，因为您在配置连接器时需要提供该文件。

4. 将公钥分配给 Snowflake 用户：

   ALTER USER USERNAME SET RSA_PUBLIC_KEY='PUBLIC_KEY';
   

   将 PUBLIC_KEY 替换为 rsa_key.pub 的内容，不包括 -----BEGIN PUBLIC KEY----- 和 -----END PUBLIC KEY----- 行。

5. 可选：如需导入其他元数据，请向连接器角色授予以下权限：

   • 数据分析和数据质量结果：授予 SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER 应用角色：

     GRANT APPLICATION ROLE SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER
       TO ROLE DATAPLEX_CATALOG_READER;
     

     系统只会导入该角色可以查看的检查的数据质量结果，这需要对数据库和架构具有 USAGE 权限，对表具有 SELECT 权限，以及对自定义数据指标函数具有 USAGE 权限。

   • 主键和外键：授予对数据库和架构的 USAGE 权限，以及对表的 SELECT 或 REFERENCES 权限。

   • 语义视图的示例值和自定义说明：授予对语义视图的 REFERENCES 权限。

如需查找在配置连接器时输入的账号标识符，请在 Snowflake 中运行以下查询：

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

注意： 连接器从 ACCOUNT_USAGE 视图中读取元数据，这些视图的延迟时间最长可达 3 小时，某些视图的延迟时间最长可达 24 小时。您创建或更改的对象可能要到后续运行才会显示。

网络前提条件

为了让 BigQuery Data Transfer Service 通过专用网络内的专用 IP 地址安全地连接到外部数据库或第三方云数据源，请通过 Private Service Connect 配置网络连接。

如果您使用公共 IP 地址连接到本地环境或云托管实例，则不需要网络连接。

注意： 不支持具有网络连接的私有网域。

配置 Snowflake Horizon 连接器

使用Google Cloud 控制台或 REST API 配置 Snowflake Horizon 连接器。

控制台

1. 在 Google Cloud 控制台中，前往 Knowledge Catalog 页面。

   前往 Knowledge Catalog

2. 在导航菜单的管理部分中，点击连接器，然后点击添加连接。

3. 在连接器列表中，选择 Snowflake Horizon 卡片。

4. 在数据源详细信息部分，提供 Snowflake 账号的连接详细信息：

   • 对于网络连接，请根据需要选择现有网络连接，或创建一个网络连接。
   • 在账号标识符字段中，输入不含 .snowflakecomputing.com 的 Snowflake 账号标识符（例如 myorg-myaccount）。您也可以输入账号定位器，例如 xy12345.us-east-2.aws。
   • 在用户名字段中，输入您为密钥对身份验证配置的 Snowflake 用户。
   • 对于私钥，输入用户的 PKCS#8 私钥，例如 rsa_key.p8 文件的内容。
   • 可选：对于私钥口令，如果私钥已加密，请输入其口令。
   • 可选：在仓库字段中，输入运行元数据查询的仓库。如果您未指定仓库，则连接器会使用用户的默认仓库。
   • 可选：对于角色，输入连接器使用的角色，例如 DATAPLEX_CATALOG_READER。如果您未指定角色，则连接器会使用用户的默认角色。

   • 对于要转移的 Snowflake 对象，点击浏览以选择要导入的数据库、架构或单个对象（表、视图、语义视图、暂存区、函数和过程）。选择数据库或架构会导入其中的所有对象。函数和过程会与其参数类型（例如 CALC(NUMBER, VARCHAR)）一起列出。

     您还可以采用 TYPE:ACCOUNT/DATABASE[/SCHEMA[/OBJECT]] 格式手动输入对象，其中 TYPE 为 CATALOG（或 DATABASE）、SCHEMA、TABLE、VIEW、SEMANTIC-MODEL、FILESET、FUNCTION 或 PROCEDURE（例如 SCHEMA:myorg-myaccount/SALES/PUBLIC）。以浏览中显示的 ORG_NAME-ACCOUNT_NAME 小写格式输入 ACCOUNT。数据库、架构和对象名称区分大小写。不支持名称格式。

5. 在目标设置部分中：

   • 点击浏览，然后选择一个现有的 Knowledge Catalog 条目组来存储导入的元数据，或点击创建新条目组。
   • 选择是立即还是稍后设置条目组的权限。 如需允许用户查看导入的元数据，请对条目组设置权限。如果您未在项目级层向 BigQuery Data Transfer Service 服务代理授予 Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter) 角色或 dataplex.entryGroups.import 权限，请在此条目组中授予该角色或权限。您仍必须为项目授予 Dataplex Entry and EntryLink Owner (roles/dataplex.entryOwner) 角色，因为 dataplex.entryLinks.reference 权限是在项目级层检查的。如需了解详情，请参阅 IAM 角色和权限。

6. 在转移配置名称部分的显示名称中，输入元数据导入作业的名称。

7. 在时间表选项部分，配置元数据导入作业的频率。如果您选择按需，则只有在您手动触发作业时，作业才会运行。

8. 可选：在通知选项部分中，为作业失败配置电子邮件或 Pub/Sub 通知。

9. 可选：在高级选项部分中，配置加密设置。如果您选择客户管理的加密密钥 (CMEK)，则该密钥会加密在启动 Knowledge Catalog 元数据导入作业之前暂存的所有临时数据。该密钥不会加密目标 Knowledge Catalog 条目组中的元数据。

10. 点击保存。

REST

使用 projects.locations.transferConfigs.create 方法。 在 TransferConfig 资源中，配置以下字段：

• 将 dataSourceId 字段设置为 "snowflake_horizon"。
• 在 metadataDestination 字段中，使用目标 Knowledge Catalog 条目组的资源路径填充 dataplexConfiguration.entryGroup 字段：projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID。
• 在 params 字段中，设置以下参数：
  • connector.accountIdentifier（必需）：不含 .snowflakecomputing.com 的 Snowflake 账号标识符（例如 myorg-myaccount）或账号定位器（例如 xy12345.us-east-2.aws）。
  • connector.authentication.username（必填）：Snowflake 用户。
  • connector.authentication.privateKey（必需）：采用 PKCS#8 PEM 格式的用户私钥。
  • connector.authentication.privateKeyPassphrase（可选）：私钥的口令（如果密钥已加密）。
  • connector.warehouse（可选）：运行元数据查询的仓库。如果您省略此参数，则连接器会使用用户的默认仓库。
  • connector.role（可选）：连接器使用的角色。如果您省略此参数，则连接器会使用用户的默认角色。
  • connector.networkAttachment（可选）：格式为 projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_ID 的网络连接。
  • assets（必需）：要导入的 Snowflake 对象的列表，格式为 TYPE:ACCOUNT/DATABASE[/SCHEMA[/OBJECT]]，例如 ["SCHEMA:myorg-myaccount/SALES/PUBLIC"]。
• 可选：如需将私钥保留在转移作业配置之外，请将其存储在 Secret Manager 中：
  1. 将 connector.authentication.privateKey（以及 connector.authentication.privateKeyPassphrase，如果您使用的话）设置为 Secret 版本资源名称，格式为 projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID，并将这些参数名称添加到 paramConfig.secretManagerManagedParams 字段。
  2. 向包含转移作业配置 (service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.) 的项目的 BigQuery Data Transfer Service 服务代理授予每个 Secret 的 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。Secret 可以位于其他项目中。如果服务代理无法读取 Secret，则运行会在启动前失败，并显示 Failed to retrieve secret ... Permission 'secretmanager.versions.access' denied 等错误。BigQuery Data Transfer Service 会在每次运行开始时读取 Secret，因此，如果您将 VERSION_ID 设置为 latest，则从下次运行开始，系统会使用轮替后的密钥。

以下示例展示了 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"
    }
  }
}

该作业会根据您的时间表自动运行，您也可以手动触发。

监控 Snowflake Horizon 连接器作业

使用Google Cloud 控制台或 REST API 监控 Snowflake Horizon 连接器作业。

控制台

1. 在 Google Cloud 控制台的连接器页面上，点击 Snowflake Horizon 转移作业的显示名称。
2. 在运行记录标签页上，点击查看详情以查看日志。
3. 如需查看创建的条目，请点击详细信息标签页，然后点击元数据目标条目组链接。

REST

• 如需列出转移作业配置的运行并查看其状态，请使用 projects.locations.transferConfigs.runs.list 方法。

• 每次运行都会通过 ID 为 dts-run-RUN_ID 的元数据导入作业将收集到的元数据导入 Knowledge Catalog。如需查看导入结果（例如创建的条目数），请使用以下查询在 Logging 中过滤作业的日志：

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

• 如需在不使用 Logging 的情况下查看导入结果，请对 projects/PROJECT_ID/locations/LOCATION/metadataJobs/dts-run-RUN_ID 调用 projects.locations.metadataJobs.get 方法。importResult 字段显示已创建、已更新、未更改和已删除的条目和条目链接的数量。

注意： 即使转移作业运行的元数据导入作业以 SUCCEEDED_WITH_ERRORS 结束，转移作业运行也可能会显示 SUCCEEDED 状态，例如，当某个条目因其某个方面过大而被拒绝时。检查元数据导入作业的状态和日志，确认所有条目均已导入。

搜索和查看 Snowflake Horizon 元数据

1. 在 Google Cloud 控制台中，前往 Knowledge Catalog 搜索页面。

   转到搜索

2. 在过滤条件面板中，使用项目、系统和类型别名部分过滤 Snowflake Horizon 资产。如需过滤所有 Snowflake Horizon 元数据，请在系统部分中选择导入的上下文，然后在代管式连接器子部分中选择 Snowflake Horizon。

3. 在搜索字段中，输入关键字或自然语言搜索查询。例如，如需通过关键字搜索查看所有 Snowflake Horizon 资产，请输入 system=SNOWFLAKE。

   如需详细了解如何搜索资源，请参阅在 Knowledge Catalog 中搜索资源。如需详细了解可在搜索字段中使用的表达式，请参阅 Knowledge Catalog 的搜索语法。

您还可以使用 LookupContext API 检索特定 Snowflake Horizon 资源的 LLM 上下文。如需了解详情，请参阅检索数据资产的上下文。

后续步骤

• 了解如何管理连接器作业。