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. Conectar um mecanismo de consulta externo às tabelas Iceberg por meio do Horizon Catalog.

5. 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"

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

Nesta etapa, você conecta um mecanismo de consulta externo às tabelas Iceberg por meio do Horizon Catalog. Essa conexão permite consultar as tabelas usando o mecanismo de consulta externo.

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

O código de exemplo nesta etapa mostra como configurar uma conexão no Spark e está em PySpark. Para obter mais informações, consulte os seguintes tópicos:

• 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 6: 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.

• Esse recurso é compatível apenas com tabelas Iceberg gerenciadas pelo Snowflake e armazenadas no Amazon S3, Google Cloud ou Azure para todas as regiões de nuvem pública. O armazenamento não AWS compatível com S3 ainda não é aceito.

• Você não poderá consultar uma tabela Iceberg por meio da REST API do Horizon Iceberg se as seguintes políticas de controle de acesso granular (FGAC) estiverem definidas na tabela:

  • Políticas de acesso a linhas

  • Segurança em nível de coluna

• 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.