Consultar tabelas Apache Iceberg™ com um mecanismo externo por meio do Snowflake Horizon Catalog¶

Faturamento¶

• A REST API Iceberg do Catálogo Horizon está disponível em todas as edições do Snowflake.

• As solicitações de API são faturadas como 0,5 crédito por milhão de chamadas e cobradas como serviços de nuvem.

• Para acesso a dados entre regiões, aplicam-se as tarifas padrão de saída de dados entre regiões, conforme indicado na Tabela de consumo de serviços do Snowflake.

Antes de começar¶

Recupere o identificador da conta Snowflake que contém as tabelas Iceberg que você deseja consultar. Para obter instruções, consulte Identificadores de conta. Você especifica esse identificador ao conectar um mecanismo de consulta externo às suas tabelas Iceberg.

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

Conectividade privada (opcional)¶

Para conectividade segura, considere configurar a conectividade privada de Entrada e Saída para sua conta Snowflake ao acessar o ponto de extremidade do Horizon Catalog.

Fluxo de trabalho para consultar tabelas Iceberg usando um mecanismo de consulta externo¶

Para consultar tabelas Iceberg usando um mecanismo de consulta externo, siga estas etapas:

1. Criar tabelas Iceberg.

2. Configurar o controle de acesso.

3. Obter um token de acesso para autenticação.

4. Verify access token permissions.

5. (Opcional) Configurar políticas de proteção de dados.

6. Conectar um mecanismo de consulta externo às tabelas Iceberg por meio do Horizon Catalog.

7. Consultar tabelas Iceberg.

Etapa 1: Criar tabelas Iceberg¶

Nesta etapa, você cria tabelas Iceberg gerenciadas pelo Snowflake que usam o Snowflake como catálogo, para que possa consultá-las com um mecanismo de consulta externo. Para obter instruções, consulte os seguintes tópicos:

• Tutorial: Crie sua primeira tabela Apache Iceberg™: Um tutorial que mostra como criar um banco de dados, criar uma tabela Iceberg gerenciada pelo Snowflake e carregar dados na tabela.

• Criar uma tabela Iceberg gerenciada pelo Snowflake: Código de exemplo para criar uma tabela Iceberg gerenciada pelo Snowflake.

Etapa 2: Configurar o controle de acesso¶

Nesta etapa, você configura o controle de acesso para as tabelas Iceberg gerenciadas pelo Snowflake que deseja consultar com um mecanismo de consulta externo. Por exemplo, você pode configurar as seguintes funções no Snowflake:

• Função DATA_ENGINEER, que tem acesso a todos os esquemas e a todas as tabelas Iceberg gerenciadas pelo Snowflake em um banco de dados.

• Função DATA_ANALYST, que tem acesso a um esquema no banco de dados e somente a duas tabelas Iceberg gerenciadas pelo Snowflake dentro desse esquema.

Para obter instruções, consulte Configuração do controle de acesso. Para obter mais informações sobre o controle de acesso no Snowflake, consulte Visão geral do controle de acesso.

Etapa 3: Obter um token de acesso para autenticação¶

Nesta etapa, você obtém um token de acesso, necessário para autenticar-se no ponto de extremidade do Horizon Catalog para sua conta Snowflake. Você precisa obter um token de acesso para cada usuário (seja ele de serviço ou humano) e função configurada com acesso às tabelas Iceberg gerenciadas pelo Snowflake. Por exemplo, você precisa obter um token de acesso para um usuário com a função DATA_ENGINEER e outro usuário com a função DATA_ANALYST.

You specify this access token later when you connect an external query engine to Iceberg tables through Horizon Catalog.

Você pode obter um token de acesso usando uma das seguintes opções de autenticação:

• OAuth externo

• Autenticação de pares de chaves

• Programmatic access token (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>'

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>'

Step 4: Verify access token permissions¶

Nesta etapa, você verifica as permissões do token de acesso obtido na etapa anterior.

• Verificar o acesso ao ponto de extremidade IRC no Horizon

• Recuperar os metadados de uma tabela

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"

Etapa 5 (opcional): Configurar políticas de proteção de dados¶

Nesta etapa, você configura as políticas de proteção de dados para tabelas Iceberg. Se você não tiver tabelas que precisa proteger com as políticas de dados do Snowflake, poderá prosseguir para a próxima etapa.

Para obter instruções sobre como configurar políticas de proteção de dados, consulte Configurar políticas de proteção de dados em tabelas Iceberg acessadas por meio da API REST do Horizon Iceberg e usando o Apache Spark™.

Step 6: Connect an external query engine to Iceberg tables through Horizon Catalog¶

In this step, you connect an external query engine to Iceberg tables through Horizon Catalog. With this connection, you can query the tables by using the external query engine.

Os mecanismos externos usam o ponto de extremidade da REST Apache Iceberg™ exposto pelo Snowflake. Para sua conta Snowflake, esse ponto de extremidade tem o seguinte formato:

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

The example code in this step shows how to set up a connection in Spark, and the example code is in PySpark. For more information, see the following sections:

• Conectar-se usando OAuth externo ou autenticação por par de chaves.

• Conecte-se usando um token de acesso programático (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

Step 7: Query Iceberg tables¶

Esta etapa fornece os seguintes exemplos de código para usar o Apache Spark™ para consultar tabelas Iceberg:

• Mostrar namespaces

• Usar namespaces

• Exibição de tabelas

• Consulta a uma tabela

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()

Considerações para consultar tabelas Iceberg com um mecanismo de consulta externo¶

Considere os seguintes itens ao consultar tabelas Iceberg com um mecanismo de consulta externo:

• Para tabelas no Snowflake:

  • Somente tabelas Iceberg gerenciadas pelo Snowflake são compatíveis.

  • Não é possível consultar tabelas Iceberg remotas ou gerenciadas externamente, incluindo tabelas Delta Direct e Parquet Direct e tabelas nativas do Snowflake.

• Você pode consultar, mas não pode gravar em tabelas Iceberg.

• As leituras externas são compatíveis apenas com a versão 2 ou anterior do Iceberg.

• This feature is only supported for Snowflake-managed Iceberg tables that are stored on Amazon S3, Google Cloud, or Microsoft Azure for all public cloud regions. S3-compatible non-AWS storage is not yet supported.

• Tabelas protegidas pelas seguintes políticas de dados refinadas podem ser acessadas pela API REST do Horizon Iceberg e usando o Apache Spark™:

  • Masking policies

  • Políticas de mascaramento baseadas em tags

  • Políticas de acesso a linhas

• Funções do Snowflake que incluem o caractere hífen (-) no nome não são compatíveis durante o acesso a tabelas Iceberg por meio do ponto de extremidade do Horizon Catalog.

• Não é possível conceder explicitamente acesso do ponto de extremidade do Horizon Catalog às suas contas de armazenamento. Recomendamos que você use conectividade privada para conectividade segura de mecanismos externos ao Horizon Catalog e do Horizon Catalog à conta de armazenamento.