Snowflake Horizon Catalogを介した外部エンジンによる|iceberg-tm|テーブルへのアクセス¶

Icebergテーブルのクエリ¶

Horizonカタログを介して外部クエリエンジンをIcebergテーブルに接続することで、次のタスクを実行できます。

• オープンIceberg REST プロトコルをサポートする外部クエリエンジンを使用して、Apache Spark™など、これらのテーブルをクエリします。

• 単一のHorizonカタログエンドポイントを使用して、新規または既存のSnowflakeアカウント内の既存および新規のSnowflake管理のIcebergテーブルをクエリします。

• Snowflakeの既存のユーザー、ロール、ポリシー、および認証を使用してテーブルをクエリします。

• ベンディングされた認証情報を使用します。

Snowflake Horizonカタログの詳細については、 Snowflake Horizon カタログ をご参照ください。

Icebergテーブルへの書き込み¶

Horizon Catalogを介した外部クエリエンジンを使用したIcebergテーブルへの書き込みは公開プレビュー中です。テーブルに書き込むには、:ref:`外部クエリエンジンを使用してIcebergテーブルにアクセスするワークフロー<label-tables_iceberg_query_using_external_query_engine_snowflake_horizon_workflow>`に従ってください。アクセス制御を構成するときは、必ず:ref:`テーブルへの書き込みアクセスを構成<label-tables_iceberg_query_using_external_query_engine_snowflake_horizon_configure_write_access>`してください。

その後、Icebergテーブルに書き込みます。

次の図は、Horizon Catalogを介してSnowflake管理のIcebergテーブルの読み書きを行う外部クエリエンジンと、これらのテーブルの読み書きを行うSnowflakeを示しています。

請求¶

• Horizon Iceberg REST カタログ API はすべてのSnowflakeエディションで利用可能です。

• その API リクエストは100万件のコールごとに0.5クレジットとして請求され、クラウドサービスとして課金されます。

• クロスリージョンデータアクセスの場合、 Snowflakeサービス利用表 に記載されている標準のクロスリージョンデータエグレス料金が適用されます。

サポートされる外部エンジンとカタログ¶

以下の表は、すべてを網羅しているわけではありませんが、Horizon Iceberg REST カタログ API と統合する多くの外部エンジンとカタログを示しています。この統合により、外部システムからSnowflakeが管理するIcebergテーブルにアクセスできるようになります。

前提条件¶

アクセスするIcebergテーブルを含むSnowflakeアカウントのアカウント識別子を取得します。手順については、 アカウント識別子 をご参照ください。次の場合にこの識別子を指定します。 Icebergテーブルに外部クエリエンジンを接続する 。

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

（オプション）プライベート接続¶

安全な接続のために、Horizon カタログエンドポイントにアクセスする際の、Snowflakeアカウント用 :doc:` インバウンド </user-guide/private-connectivity-inbound>` および :doc:` アウトバウンド </user-guide/private-connectivity-outbound>` プライベート接続の構成を検討してください。

外部クエリエンジンを使用してIcebergテーブルにアクセスするワークフロー¶

外部クエリエンジンを使用してIcebergテーブルにアクセスするには、以下のステップを完了します。

1. Icebergテーブルを作成する

2. アクセス制御を構成する

3. 認証用アクセストークンを取得する

4. アクセストークンの権限を確認する

5. （オプション）データ保護ポリシーを構成する

6. Horizonカタログを介する外部クエリエンジンとIcebergテーブルを接続する

7. Icebergテーブルのクエリ

ステップ1：Icebergテーブルの作成¶

このステップでは、Snowflakeをカタログとして使用するSnowflake管理のIcebergテーブルを作成し、外部クエリエンジンでアクセスできるようにします。手順については、以下のトピックをご参照ください。

• チュートリアル: 初めてのApache Iceberg™テーブルを作成する:データベースを作成し、Snowflake管理のIcebergテーブルを作成し、テーブルにデータをロードする方法を示すチュートリアル。

• Snowflake管理のIcebergテーブルを作成する:Snowflake管理のIcebergテーブルを作成するコード例。

ステップ2：アクセス制御の構成¶

このステップでは、外部クエリエンジンでアクセスするSnowflake管理のIcebergテーブルのアクセス制御を構成します。たとえば、Snowflakeでは次のロールを設定できます:

• data_engineerロール。データベース内のすべてのスキーマとSnowflake管理のすべてのIcebergテーブルにアクセスできます。

• data_analyst role ロール。データベース内の1つのスキーマにアクセスし、そのスキーマ内の2つのSnowflake管理のIcebergテーブルにのみアクセスできます。

詳細は以下のセクションをご覧ください。

• Icebergテーブルへの読み取りアクセスを構成する

• Icebergテーブルへの書き込みアクセスを構成する

CREATE OR REPLACE ROLE data_engineer;

GRANT USAGE ON DATABASE iceberg_test_db TO ROLE data_engineer;
GRANT USAGE ON SCHEMA iceberg_test_db.public TO ROLE data_engineer;

GRANT SELECT ON TABLE iceberg_test_db.public.test_table TO ROLE data_engineer;

CREATE OR REPLACE USER horizon_rest_srv_account_user TYPE=SERVICE DEFAULT_ROLE=data_engineer;

GRANT ROLE data_engineer TO USER horizon_rest_srv_account_user;

GRANT SELECT ON FUTURE ICEBERG TABLES IN SCHEMA my_db.my_schema TO ROLE data_engineer;

ステップ3：認証用アクセストークンの取得¶

このステップでは、SnowflakeアカウントのHorizonカタログエンドポイントを認証するために必要なアクセストークンを取得します。各ユーザー（サービスまたは人間）用のアクセストークンと、Snowflake管理のIcebergテーブルへのアクセスで構成されたロールを取得する必要があります。たとえば、DATA_ENGINEER ロールを持つユーザーと DATA_ANALYST ロールを持つ別のユーザーに対して、1つのアクセストークンを取得する必要があります。

Horizon Catalogを介して外部クエリエンジンをIcebergテーブルに接続する ときに、このアクセストークンを指定します。

次の認証オプションのいずれかを使用して、アクセストークンを取得できます。

• 外部 OAuth

• キーペア認証

• プログラムアクセストークン（PAT）

GRANT ROLE ENGINEER to user my_service_user;

snowsql --private-key-path "<private_key_file>" \
  --generate-jwt \
  -h "<account_identifier>.snowflakecomputing.com" \
  -a "<account_locator>" \
  -u "<user_name>"

curl -i --fail -X POST "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens" \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials' \
 --data-urlencode 'scope=session:role:<role>' \
 --data-urlencode 'client_secret=<JWT_token>'

ALTER USER IF EXISTS HORIZON_REST_SRV_ACCOUNT_USER
ADD PAT HORIZON_REST_SRV_ACCOUNT_USER_PAT
  DAYS_TO_EXPIRY = 7
  ROLE_RESTRICTION = 'DATA_ENGINEER'
  COMMENT = 'HORIZON REST API PAT FOR SERVICE ACCOUNT';

curl -i --fail -X POST "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens" \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials' \
 --data-urlencode 'scope=session:role:<role>' \
 --data-urlencode 'client_secret=<PAT_token>'

ステップ4：アクセストークンの権限を確認する¶

このステップでは、前のステップで取得したアクセストークンの権限を確認します。

• Horizon IRC エンドポイントへのアクセスを確認する

• テーブルのメタデータを取得する

curl -i --fail -X GET "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<database_name>" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"

{
  "defaults": {
    "default-base-location": ""
  },
  "overrides": {
    "prefix": "MY-DATABASE"
  }
}

curl -i --fail -X GET "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog/v1/<database_name>/namespaces/<namespace_name>/tables/<table_name>" \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json"

（任意）ステップ5:データ保護ポリシーを構成する¶

このステップでは、Icebergテーブルのデータ保護ポリシーを構成します。Snowflakeデータポリシーで保護する必要があるテーブルがない場合は、次のステップに進むことができます。

データ保護ポリシーの構成方法については、 Horizon Iceberg RESTAPI 経由およびApache Spark™を使用してアクセスされるIcebergテーブルのデータ保護ポリシーを構成する をご参照ください。

ステップ6：Horizonカタログを介する外部クエリエンジンとIcebergテーブルの接続¶

このステップでは、Horizonカタログを介して外部クエリエンジンをIcebergテーブルに接続します。この接続により、外部クエリエンジンを使用してテーブルにアクセスできます。

外部エンジンはSnowflakeによって公開される Apache Iceberg™ REST エンドポイントを使用します。Snowflakeアカウントの場合、このエンドポイントは次の形式をとります。

https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog

このステップのコード例は、Sparkで接続を設定する方法を示しています。コード例は PySpark です。詳細は以下のセクションをご覧ください。

• 外部 OAuth またはキーペア認証を使用した接続

• プログラムのアクセストークン（PAT）を使用した接続

# Snowflake Horizon Catalog Configuration, change as per your environment

CATALOG_URI = "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog"
HORIZON_SESSION_ROLE = f"session:role:<role>"
CATALOG_NAME = "<database_name>" #provide in UPPER CASE

# Cloud Service Provider Region Configuration (where the Iceberg data is stored)
REGION = "eastus2"

# Paste the External Oauth Access token that you generated in Snowflake here
ACCESS_TOKEN = "<your_access_token>"

# Iceberg Version
ICEBERG_VERSION = "1.9.1"

def create_spark_session():
  """Create and configure Spark session for Snowflake Iceberg access."""
  spark = (
      SparkSession.builder
      .appName("SnowflakeIcebergReader")
      .master("local[*]")

# JAR Dependencies for Iceberg and Azure
      .config(
          "spark.jars.packages",
          f"org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:{ICEBERG_VERSION},"
          f"org.apache.iceberg:iceberg-aws-bundle:{ICEBERG_VERSION}"
          # for Azure storage, use the below package and comment above azure bundle
          # f"org.apache.iceberg:iceberg-azure-bundle:{ICEBERG_VERSION}"
      )

      # Iceberg SQL Extensions
      .config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions")
      .config("spark.sql.defaultCatalog", CATALOG_NAME)

      # Horizon REST Catalog Configuration
      .config(f"spark.sql.catalog.{CATALOG_NAME}", "org.apache.iceberg.spark.SparkCatalog")
      .config(f"spark.sql.catalog.{CATALOG_NAME}.type", "rest")
      .config(f"spark.sql.catalog.{CATALOG_NAME}.uri", CATALOG_URI)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.warehouse", CATALOG_NAME)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.token", ACCESS_TOKEN)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.scope", HORIZON_SESSION_ROLE)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.client.region", REGION)

      # Required for vended credentials
      .config(f"spark.sql.catalog.{CATALOG_NAME}.header.X-Iceberg-Access-Delegation", "vended-credentials")
      .config("spark.sql.iceberg.vectorization.enabled", "false")
      .getOrCreate()
  )
  spark.sparkContext.setLogLevel("ERROR")
  return spark

# Snowflake Horizon Catalog Configuration, change as per your environment

CATALOG_URI = "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog"
HORIZON_SESSION_ROLE = f"session:role:<role>"
CATALOG_NAME = "<database_name>" #provide in UPPER CASE

# Cloud Service Provider Region Configuration (where the Iceberg data is stored)
REGION = "eastus2"

# Paste the PAT you generated in Snowflake here
PAT_TOKEN = "<your_PAT_token>"

# Iceberg Version
ICEBERG_VERSION = "1.9.1"

def create_spark_session():
  """Create and configure Spark session for Snowflake Iceberg access."""
  spark = (
      SparkSession.builder
      .appName("SnowflakeIcebergReader")
      .master("local[*]")

# JAR Dependencies for Iceberg and Azure
      .config(
          "spark.jars.packages",
          f"org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:{ICEBERG_VERSION},"
          f"org.apache.iceberg:iceberg-aws-bundle:{ICEBERG_VERSION}"
          # for Azure storage, use the below package and comment above azure bundle
          # f"org.apache.iceberg:iceberg-azure-bundle:{ICEBERG_VERSION}"
      )

      # Iceberg SQL Extensions
      .config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions")
      .config("spark.sql.defaultCatalog", CATALOG_NAME)

      # Horizon REST Catalog Configuration
      .config(f"spark.sql.catalog.{CATALOG_NAME}", "org.apache.iceberg.spark.SparkCatalog")
      .config(f"spark.sql.catalog.{CATALOG_NAME}.type", "rest")
      .config(f"spark.sql.catalog.{CATALOG_NAME}.uri", CATALOG_URI)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.warehouse", CATALOG_NAME)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.credential", PAT_TOKEN)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.scope", HORIZON_SESSION_ROLE)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.client.region", REGION)

      # Required for vended credentials
      .config(f"spark.sql.catalog.{CATALOG_NAME}.header.X-Iceberg-Access-Delegation", "vended-credentials")
      .config("spark.sql.iceberg.vectorization.enabled", "false")
      .getOrCreate()
  )
  spark.sparkContext.setLogLevel("ERROR")
  return spark

ステップ7：Icebergテーブルへのアクセス¶

このセクションでは、Apache Spark™を使用してIcebergテーブルにクエリを実行し、Icebergテーブルに書き込むためのコード例を示します。

spark.sql("show namespaces").show()

spark.sql("use namespace <your_schema_name_in_snowflake>")

spark.sql("show tables").show()

spark.sql("use namespace spark_demo")
spark.sql("select * from <your_table_name_in_snowflake>").show()

spark.sql("CREATE TABLE MY_TABLE (COLUMN1 INT) USING ICEBERG").show();

spark.sql("INSERT INTO MY_TABLE VALUES (600)").show()

spark.sql("ALTER TABLE MY_TABLE ADD COLUMN COLUMN2 INT").show()

spark.sql("UPDATE MY_TABLE SET COLUMN2 = 10 WHERE COLUMN1 = 100").show()

spark.sql("DELETE FROM MY_TABLE WHERE COLUMN2 = 10").show()

spark.sql("TRUNCATE TABLE MY_TABLE").show()

spark.sql("ALTER TABLE MY_TABLE RENAME TO MY_NEW_TABLE")

spark.sql("DROP TABLE MY_TABLE")

外部クエリエンジンを使用してIcebergテーブルにアクセスする際の考慮事項¶

このセクションでは、外部クエリエンジンを使用してIcebergテーブルにアクセス、クエリ実行、および書き込みを行う際の考慮事項を示します。

外部クエリエンジンでIcebergテーブルにアクセスする場合は、以下の項目を考慮してください。

• Iceberg

  • Snowflakeのテーブルの場合:

    • Snowflake管理Icebergテーブルのみがサポートされています。

• リスト:

  • リスト作成の自動フルフィルメント を介して共有するIcebergテーブルは、コンシューマーアカウントのHorizon Iceberg REST カタログ API からアクセスできません

• ネットワークおよびプライベート接続:

  • ユーザーレベルで設定されたネットワークポリシーの使用は、この機能ではサポートされていません。

  • Snowflakeが管理するネットワークルール の場合、静的であるエグレス IP アドレスはサポートされていません。

  • Horizonカタログエンドポイントのアクセス権をご利用のストレージアカウントに明示的に付与することは、サポートされていません。外部エンジンからHorizonカタログへ、およびHorizonカタログからストレージアカウントへの安全な接続のために、プライベート接続を使用することをお勧めします。

• クラウド:

  • 商用:この機能は、すべての商用クラウドリージョンで、Amazon S3、Google Cloud、またはMicrosoft Azureに保存されているSnowflake管理のIcebergテーブルでのみサポートされています。S3互換の非 AWS ストレージはまだサポートされていません。

  • FedRAMP（Moderate）:この機能は、us-east-1およびus-west-2リージョンのAWS Commercial Gov（US）におけるFedRAMP（Moderate）デプロイメントに保存されているSnowflake管理のIcebergテーブルでサポートされています。

  • Amazon S3に保存されているIcebergテーブルの場合:

    • SSE-KMS 暗号化を使用する場合は、アクセスを有効にする際のサポートについて、カスタマーサポートまたはアカウントチームにお問い合わせください。

      注釈

      KMSで暗号化された外部ボリュームへの書き込みはサポートされていません。

  • Azureに保存されているIcebergテーブルの場合:

    • Azure仮想ネットワーク（VNet）はサポートされていません。

• 認証:

  • キーペア認証について、キーペアのローテーションはサポートされていません。

  • ワークロードIDフェデレーションは、この機能ではサポートされていません。

外部クエリエンジンでIcebergテーブルをクエリ（読み取り）する場合は、以下の項目を考慮してください。

• Iceberg

  • 以下のテーブルのクエリはサポートされていません。

    • リモートテーブル

    • Snowflakeネイティブテーブル

    • デルタベースのIcebergテーブルや、Iceberg互換のParquetデータファイルから COPYINTO テーブルコマンドを使用してデータをロードしたSnowflake管理のIcebergテーブルを含む、外部管理Icebergテーブル。

  • Iceberg v2テーブルの読み取りはサポートされています。

  • Iceberg V3テーブルの読み取り（公開プレビュー）は、以下の機能でサポートされています。

    • Variantデータ型

    • 行系統

    デフォルト値やgeographyデータ型など、他のすべてのIceberg V3機能はサポートされていません。

• アクセス制御：

  • 以下に示す詳細なデータポリシーで保護されたテーブルには、Snowflake Horizonカタログを通じてApache Spark™を介してアクセスできます。

    • マスキングポリシー

    • タグベースのマスキングポリシー

    • 行アクセスポリシー

    詳細については、 Apache Spark™から Apache Iceberg™ テーブルをクエリするときにデータ保護ポリシーを適用する をご参照ください。

• クローンおよび変換されたテーブル:

  • クローンまたは変換されたテーブルの読み取りは、提供された認証情報ではサポートされていません。これらのテーブルを読み取るには、オブジェクトストレージへの直接アクセスを使用します。

外部クエリエンジンでIcebergテーブルに書き込む場合は、以下の項目を考慮してください。

• テーブル操作:

  • CREATE TABLEステートメントでベースロケーションを指定することはできません。

    ベースロケーションを指定せずにSnowflake管理テーブルを作成すると、Snowflakeはテーブルに対して以下のパスを構築します。STORAGE_BASE_URL/database/schema/table_name.randomId/[data | metadata]/

  • 外部エンジンからのCREATE TABLE AS SELECT（CTAS）はサポートされていません。

  • 等価削除はサポートされていません。

  • 行レベルの削除を使用してテーブルに書き込むことはできません。コピーオンライトモードのみがサポートされています。

  • Icebergタグとブランチの作成はサポートされていません。

  • 外部エンジンの書き込みはIcebergバージョン2でのみサポートされています。Icebergバージョン3（v3）テーブル（公開プレビュー）への書き込みは現在サポートされていません。

  • KMSで暗号化された外部ボリュームへの書き込みはサポートされていません。

  • Snowflakeのダイナミックテーブルへの書き込みはサポートされていません。

  • 共有Icebergテーブルへの書き込みはサポートされていません。

  • Icebergテーブルの登録はサポートされていません。

• メンテナンス操作

  • テーブルを以前のスナップショットにロールバックすることはできません。

  • スナップショットの有効期限切れ操作はサポートされていません。

  • Icebergテーブルをv2からv3にアップグレードすることはできません。

• クローンおよび変換されたテーブル:

  • クローンまたは変換されたテーブルへの書き込みは、提供された認証情報ではサポートされていません。これらのテーブルに書き込むには、テーブルが格納されているオブジェクトストレージに外部クエリエンジンを直接接続します。

  • 外部管理からSnowflake管理に変換されたIcebergテーブルには書き込みできません。

• ストリーム:

  • Iceberg V2テーブルにおいて、コピーオンライト操作が行われると、標準ストリームは更新または再配置された行を、DELETEレコードとその後に続く同じ行のINSERTレコードとして表します。

• きめ細かいアクセス制御ポリシー:

  • きめ細かいアクセス制御ポリシーやタグを持つテーブルへの書き込みはサポートされていません。