Snowflake Open Catalog 入门¶

在笔记本电脑上安装 Conda、Spark 和 Jupyter¶

在本教程中，您可以使用 Conda 轻松创建开发环境和下载必要的软件包。只有当你按照用例 2 使用 Apache Spark™ 读取 Snowflake 管理的 Apache Spark™ 表时，才需要这样做。这不是在 Snowflake 上创建或使用 Iceberg 表所必需的。

1. 要安装 Conda，请按照以下特定于您 OS 的说明进行安装：

   • Mac (https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html)

   • Windows (https://docs.conda.io/projects/conda/en/latest/user-guide/install/windows.html)

   • Linux (https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html)

2. 使用以下内容创建名为 environment.yml 的文件：

   name: iceberg-lab
   channels:
     - conda-forge
   dependencies:
     - findspark=2.0.1
     - jupyter=1.0.0
     - pyspark=3.5.0
     - openjdk=11.0.13
   

   Copy

3. 要创建所需的环境，请在 shell 中运行以下命令：

   conda env create -f environment.yml
   

   Copy

创建 Open Catalog 账户¶

Open Catalog 账户只能由 ORGADMIN 创建。

1. 在 Snowsight 的导航窗格中，选择 Admin > Accounts。

2. 在 + Account 下拉菜单中，选择 Create Snowflake Open Catalog Account。

3. 完成 Create Snowflake Open Catalog Account 对话框：

   • 云：您想要存储 Apache Iceberg™ 表的云提供商。

   • 区域：您要存储 Iceberg 表的地区。

   • 版本：您的 Open Catalog 账户的版本。

4. 选择 Next。

5. 在 Create New Account 对话框中，填写 Account Name、User Name、Password 和 Email 字段。

6. 选择 Create Account。您的新 Open Catalog 账户已创建，并出现确认框。

7. 在确认框中，选择 Account Locator URL，在您的网络浏览器中打开账户定位器 URL。

8. 将账户定位器 URL 加入书签。登录 Open Catalog 时，必须指定账户定位器 URL。

登录到 Open Catalog Web 界面¶

1. 创建账户后，点击您通过电子邮件收到的账户 URL，OR前往 https://app.snowflake.cn。

2. 点击 Sign into a different account，然后使用之前创建的 Open Catalog 账户登录。

创建授予对 S3 位置的访问权限的 IAM 策略¶

如果您还没有，请首先创建一项授予访问您的 S3 位置的权限的 IAM 策略。有关创建此策略的说明，请参阅 创建授予您的 S3 位置访问权限的 IAM 策略。

创建 IAM 角色¶

如果您还没有，请为 Open Catalog 创建一个 AWS IAM 角色来授予您的 S3 存储桶权限。有关说明，请参阅 创建 IAM 角色。当说明提示您选择策略时，选择授予访问您的 S3 位置的 IAM 策略。

在 Open Catalog 中创建内部目录¶

您可以在 Open Catalog 账户中使用内部目录来创建表、进行查询，并使用 Apache Spark™ 或其他查询引擎对表运行 DML。

1. 登录您的新 Open Catalog 账户。

2. 要创建新目录，请在左侧窗格中选择 Catalogs。

3. 选择右上角的 +Catalogs。

4. 在 Create Catalog 对话框中，输入以下详细信息：

   • Name：为目录命名 demo_catalog。

   • Default base location: 存储表格数据的位置。

   • Additional locations (optional): 以逗号分隔的多个存储位置列表。它主要用于需要从该目录中的不同位置导入表。您可以把它留空。

   • S3 role ARN: 对存储位置具有读写权限的 AWS 角色。输入您为 Open Catalog 创建的 IAM 角色的 ARN。

   • External ID：（可选）： 在目录用户和存储账户之间创建信任关系时要提供的密钥。 如果您跳过此操作，它将自动生成。在本教程中使用像 abc123 这样的简单字符串。

5. 选择 Create。您的目录已创建并将以下值添加到您的目录中：

   • 您的 Open Catalog 账户的 IAM 用户 arn。

   • 如果您没有自己输入 External ID，则会为您的目录自动生成一个 External ID。

   在下一节中创建信任关系时，您将需要这些值。

创建信任关系¶

创建目录后，您需要设置信任关系，以便上述配置中指定的 S3 角色可以在存储位置读取和写入数据。请注意，要完成此任务，您需要为您的目录提供 S3 IAM 用户 arn 和 External ID。

1. 创建目录后，在列表中选择您的目录以显示您的目录的 S3 IAM 用户 arn 和 External ID。

2. 要创建信任关系，请按照 第 5 步：授予访问桶对象的 IAM 用户权限 中的说明操作。

   在这些说明中显示的 JSON 对象中：

   • 对于 <open_catalog_user_arn>，使用 Open Catalog UI 中 IAM 用户 arn 下的值。

   • 对于 <open_catalog_external_id>，使用 Open Catalog UI 中 External ID 下的值。

   

为 Apache Spark&trade 配置新服务连接；¶

为 Apache Spark 创建一个新连接 (client_id/client_secret pair)，以便对您刚创建的目录运行查询。

1. 在 Open Catalog 的左侧窗格中，选择 Connections 选项卡，然后选择右上角的 + Connections。

2. 在 Configure Service Connection 对话框中，创建新的主体角色或从可用角色中选择一个。

3. 选择 Create。

4. 在 Configure Service Connection 对话框中，要将客户端 ID 和客户端密钥复制到文本编辑器，请在 As <CLIENT ID>:<SECRET> 字段中选择 Copy。

   重要

   以后您将无法从 Open Catalog 服务检索这些文本字符串，因此必须立即复制它们。配置 Spark 时可以使用这些文本字符串。

为连接设置目录权限¶

现在，您可以为服务连接授予权限，以便它可以访问目录。如果没有访问权限，服务连接将无法对目录运行任何查询。

1. 在导航窗格中，选择 Catalogs，然后在列表中选择您的目录。

2. 要创建新角色，请选择 Roles 选项卡。

3. 选择 + Catalog role。

4. 在 Create Catalog Role 对话框中，为 Name 输入 spark_catalog_role。

5. 对于 Privileges，选择 **CATALOG_MANAGE_CONTENT **，然后选择 Create。

   这为角色提供了创建、读取和写入表的权限。

6. 选择 Grant to Principal Role。

7. 在 Grant Catalog Role 对话框中，对于 Principal role to receive grant，请选择 my_spark_admin_role。

8. 对于 Catalog role to grant，选择 spark_catalog_role，然后选择 Grant。

此过程的结果是，角色 spark_catalog_role 被授予了 my_spark_admin_role，这为您在前面的过程中创建的 Spark 连接提供了管理员权限。

设置 Spark¶

在终端上运行以下命令以激活您在安装程序中创建的虚拟环境，然后打开 Jupyter Notebook：

conda activate iceberg-lab
jupyter notebook

配置 Spark¶

• 要注册服务连接，请在 Jupyter 笔记本中运行以下命令。

  import os
  os.environ['SPARK_HOME'] = '/Users/<username>/opt/anaconda3/envs/iceberg-lab/lib/python3.12/site-packages/pyspark'
  
  import pyspark
  from pyspark.sql import SparkSession
  
  spark = SparkSession.builder.appName('iceberg_lab') \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'opencatalog') \
  .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
  .config('spark.sql.catalog.opencatalog.type', 'rest') \
  .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.cn/polaris/api/catalog') \
  .config('spark.sql.catalog.opencatalog.credential','<client_id>:<client_secret>') \
  .config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
  .config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:<principal_role_name>') \
  .getOrCreate()
  
  #Show namespaces
  spark.sql("show namespaces").show()
  
  #Create namespace
  spark.sql("create namespace spark_demo")
  
  #Use namespace
  spark.sql("use namespace spark_demo")
  
  #Show tables; this will show no tables since it is a new namespace
  spark.sql("show tables").show()
  
  #create a test table
  spark.sql("create table test_table (col1 int) using iceberg");
  
  #insert a record in the table
  spark.sql("insert into test_table values (1)");
  
  #query the table
  spark.sql("select * from test_table").show();
  

  Copy

  有关更多信息，请参阅 在 Spark 中注册服务连接。

.config('spark.sql.catalog.opencatalog.client.region','<target_s3_region>') \

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
.config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.config('spark.sql.defaultCatalog', 'opencatalog') \
.config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
.config('spark.sql.catalog.opencatalog.type', 'rest') \
.config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
.config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.cn/polaris/api/catalog') \
.config('spark.sql.catalog.opencatalog.credential','<client_id>:<secret>') \
.config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
.config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:<principal_role_name>') \
.config('spark.sql.catalog.opencatalog.client.region','<target_s3_region>') \
.getOrCreate()

使用 Snowflake 查询表¶

你可以在 Snowflake 中创建目录集成对象，然后在 Snowflake 中创建一个 Apache Iceberg™ 表，用于表示 Open Catalog 中的表。在以下示例中，您在 Snowflake 中创建了一个 Iceberg 表，该表表示 Spark 刚刚在 Open Catalog 的内部目录中创建的 Iceberg 表。

您可以使用相同的 Spark 连接凭据，也可以创建新的 Snowflake 连接。如果您创建新连接，则必须相应地设置角色和权限。

1. 创建目录集成对象：

   CREATE OR REPLACE CATALOG INTEGRATION demo_open_catalog_int 
     CATALOG_SOURCE = POLARIS 
     TABLE_FORMAT = ICEBERG 
     CATALOG_NAMESPACE = '<catalog_namespace>'
     REST_CONFIG = (
       CATALOG_URI = 'https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.com/polaris/api/catalog' 
       CATALOG_NAME = ‘<catalog_name>’
     )
       REST_AUTHENTICATION = (
       TYPE = OAUTH 
       OAUTH_CLIENT_ID = '<client_id>' 
       OAUTH_CLIENT_SECRET = '<secret>' 
       OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL') 
     ) 
     ENABLED = TRUE;
   
   # the <catalog_namespace> created in previous step is spark_demo.
   # the <catalog_name> created in previous step is demo_catalog.
   

   Copy

2. 使用上面创建的目录集成在 Snowflake 中创建表表示形式，然后查询该表：

   CREATE OR REPLACE ICEBERG TABLE test_table
     CATALOG = 'demo_open_catalog_int'
     EXTERNAL_VOLUME = '<external_volume>'
     CATALOG_TABLE_NAME = 'test_table';
   
   SELECT * FROM test_table;
   

   Copy

在 Open Catalog 中创建外部目录¶

Snowflake 的 Iceberg 表可以在您的 Open Catalog 账户的外部目录中同步。

1. 登录您的新 Open Catalog 账户。

2. 要创建新目录，请在左侧窗格中选择 Catalogs。

3. 选择右上角的 +Catalogs。

4. 在 Create Catalog 对话框中，输入以下详细信息：

   • Name：为目录命名 demo_catalog_ext。

   • 将 External 的开关设置为 On。

   • Default base location: 存储表格数据的位置。

     注意

     与在本教程的用例 1 中创建的内部目录相比，必须使用不同的存储位置。为确保正确执行为目录定义的访问权限，两个不同的目录的位置不能重叠。

   • Additional locations (optional): 以逗号分隔的多个存储位置列表。它主要用于需要从该目录中的不同位置导入表。您可以把它留空。

   • S3 role ARN: 对存储位置具有读写权限的 AWS 角色。

   • External ID：（可选）： 在目录用户和存储账户之间创建信任关系时要提供的密钥。 如果您跳过此操作，它将自动生成。在本教程中使用像 abc123 这样的简单字符串。

5. 选择 Create。以下值将添加到您的目录中：

   • 您的 Open Catalog 账户的 IAM 用户 arn。

   • 如果您没有自己输入 External ID，则会为您的目录自动生成一个 External ID。

为 Snowflake 配置新服务连接¶

1. 在 Open Catalog 的左侧窗格中，选择 Connections 选项卡，然后选择右上角的 + Connections。

2. 在 Configure Service Connection 对话框中，创建新的主体角色或从可用角色中选择一个。

3. 选择 Create。

4. 在 Configure Service Connection 对话框中，要将客户端 ID 和客户端密钥复制到文本编辑器，请在 As <CLIENT ID>:<SECRET> 字段中选择 Copy。

   重要

   以后您将无法从 Open Catalog 服务检索这些文本字符串，因此必须立即复制它们。配置 Spark 时可以使用这些文本字符串。

设置目录权限¶

要设置外部目录的权限，以便 Snowflake 连接具有对外部目录的正确权限，请执行以下步骤：

1. 在导航窗格中，选择 Catalogs，然后在列表中选择您的外部目录。

2. 要创建新角色，请选择 Roles 选项卡。

3. 选择 + Catalog role。

4. 在 Create Catalog Role 对话框中，为 Name 输入 spark_catalog_role。

5. 对于 Privileges，选择 **CATALOG_MANAGE_CONTENT **，然后选择 Create。

   这为角色提供了创建、读取和写入表的权限。

6. 选择 Grant to Principal Role。

7. 在 Grant Catalog Role 对话框中，对于 Principal role to receive grant，请选择 my_spark_admin_role。

8. 对于 Catalog role to grant，选择 spark_catalog_role，然后选择 Grant。

在 Snowflake 中创建目录集成对象¶

在 Snowflake 中，使用 CREATE CATALOG INTEGRATION（Snowflake Open Catalog）命令 创建目录集成对象。对于 CATALOG_NAME，请指定在 Open Catalog 账户中配置的外部目录名称 (demo_catalog_ext)。

Snowflake 会将表及其父命名空间同步到 Open Catalog 中的此外部目录。例如，如果您在 Snowflake 中注册了 open_catalog_demo.iceberg.test_table_managed Iceberg 表，并在目录集成中指定了 demo_catalog_ext，则 Snowflake 会使用以下完全限定名称将表与 Open Catalog 同步：demo_catalog_ext.open_catalog_demo.iceberg.test_table_managed。

CREATE OR REPLACE CATALOG INTEGRATION demo_open_catalog_ext 
  CATALOG_SOURCE=POLARIS 
  TABLE_FORMAT=ICEBERG 
  REST_CONFIG = (
    CATALOG_URI = 'https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.com/polaris/api/catalog' 
    CATALOG_NAME = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH 
    OAUTH_CLIENT_ID = '<client_id>' 
    OAUTH_CLIENT_SECRET = '<secret>' 
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL') 
  ) 
  ENABLED=TRUE;

# the <catalog_name> created in previous step is demo_catalog_ext.

设置目录同步¶

在将 Snowflake 管理的 Iceberg 表同步到 Open Catalog 之前，必须在 Open Catalog 中指定外部目录，以便 Snowflake 将表同步到该目录。

要设置目录同步，请使用带有 CATALOG_SYNC 参数的 ALTER DATABASE 命令。对于该参数的值，请指定 Open Catalog 的目录集成名称。例如：

ALTER DATABASE open_catalog_demo SET CATALOG_SYNC = 'demo_open_catalog_ext';

运行此代码后，Snowflake 会将 open_catalog_demo 数据库中所有 Snowflake 管理的 Iceberg 表同步到 <catalog_name> external catalog in Open Catalog that you specified in the demo_open_catalog_ext 目录集成。

创建 Snowflake 管理的 Iceberg 表¶

创建 Snowflake 管理的 Iceberg 表，并将其从 Snowflake 同步到 Open Catalog。有关更多信息，请参阅：

• [为 Amazon S3 配置外部卷] (https://docs.snowflake.com/en/user-guide/tables-iceberg-configure-external-volume-s3)

• CREATE ICEBERG TABLE（Snowflake 作为 Iceberg 目录）

重要

外部卷的 STORAGE_BASE_URL 必须与您在 Open Catalog 中创建的外部目录的 Default base location 相匹配。

use database open_catalog_demo;
use schema iceberg;

# Note that the storage location for this external volume will be different than the storage location for the external volume in use case 1

CREATE OR REPLACE EXTERNAL VOLUME snowflake_demo_ext
  STORAGE_LOCATIONS =
      (
        (
            NAME = '<storage_location_name>'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://<s3_location>'
            STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::<aws_acct>:role/<rolename>'
            STORAGE_AWS_EXTERNAL_ID = '<external_id>'
        )
      );

CREATE OR REPLACE ICEBERG TABLE test_table_managed (col1 int)
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'snowflake_demo_ext'
  BASE_LOCATION = 'test_table_managed'

当您在 Snowflake 中修改表时，更改会自动与 Open Catalog 账户中的外部目录同步。 其他引擎（如 Apache Spark™）可以通过连接到 Open Catalog 查询表。

注意

如果表无法同步到 Open Catalog，请运行 SYSTEM$SEND_NOTIFICATIONS_TO_CATALOG 系统函数来诊断同步失败的原因。有关更多信息，请参阅 SYSTEM$SEND_NOTIFICATIONS_TO_CATALOG。

您学到的内容¶

• 创建 Open Catalog 账户。

• 在您的 Open Catalog 账户中创建内部目录。

• 使用 Spark 在内部目录上创建表。

• 使用 Snowflake 为 Open Catalog 创建目录集成，以便在 Open Catalog 账户的内部目录上创建的表上运行查询。

• 在您的 Open Catalog 账户中创建外部目录。

• 在 Snowflake 中创建托管的 Apache Iceberg™ 表，并将其以及两个父命名空间同步到您的 Open Catalog 账户中的外部目录。在本教程中，您学习了如何在数据库级别设置目录同步。但也可以在账户、架构或表一级进行设置，并与一个父命名空间同步。有关详细信息，请参阅以下主题：

  • 有关在架构级别设置目录同步的示例，请参阅 Snowflake 文档中的 在架构级别设置目录同步。

  • 有关设置目录同步的更多信息，请参阅 Snowflake 文档中的 CATALOG_SYNC。

  • 要使表与一个父命名空间同步，可使用 CREATE DATABASE 命令设置 CATALOG_SYNC_NAMESPACE_MODE 属性。要了解更多信息，请参阅 Snowflake 文档中的 CREATE DATABASE。

    备注

    如果第三方查询引擎只能查询目录中第二级命名空间及以下的表，则必须将表与一个父命名空间同步。否则，Snowflake 会将该表同步至 Open Catalog 中的第三级命名空间，导致您无法查询该表。

相关资源¶

• Snowflake Iceberg 表文档

• [Apache Polaris™ (incubating) GitHub 存储库] (https://github.com/apache/polaris)

• Apache Iceberg 文档 (https://iceberg.apache.org/)