Snowflake 驱动程序

适用于: C/C++、GLib/Ruby、Go、Python、R

Snowflake 驱动程序提供对 Snowflake 数据库仓库的访问。

安装

C/C++

对于 conda-forge 用户

mamba install libadbc-driver-snowflake

Go

go get github.com/apache/arrow-adbc/go/adbc/driver/snowflake

Python

# For conda-forge
mamba install adbc-driver-snowflake

# For pip
pip install adbc_driver_snowflake

R

# install.packages("pak")
pak::pak("apache/arrow-adbc/r/adbcsnowflake")

用法

要连接到 Snowflake 数据库，您可以在构建 AdbcDatabase 时提供“uri”参数。

C++

#include "arrow-adbc/adbc.h"

// Ignoring error handling
struct AdbcDatabase database;
AdbcDatabaseNew(&database, nullptr);
AdbcDatabaseSetOption(&database, "driver", "adbc_driver_snowflake", nullptr);
AdbcDatabaseSetOption(&database, "uri", "<snowflake uri>", nullptr);
AdbcDatabaseInit(&database, nullptr);

Python

import adbc_driver_snowflake.dbapi

with adbc_driver_snowflake.dbapi.connect("<snowflake uri>") as conn:
    pass

R

library(adbcdrivermanager)

# Use the driver manager to connect to a database
uri <- Sys.getenv("ADBC_SNOWFLAKE_TEST_URI")
db <- adbc_database_init(adbcsnowflake::adbcsnowflake(), uri = uri)
con <- adbc_connection_init(db)

Go

import (
   "context"

   "github.com/apache/arrow-adbc/go/adbc"
   "github.com/apache/arrow-adbc/go/adbc/driver/snowflake"
)

func main() {
   var drv snowflake.Driver
   db, err := drv.NewDatabase(map[string]string{
       adbc.OptionKeyURI: "<snowflake uri>",
   })
   if err != nil {
       // handle error
   }
   defer db.Close()

   cnxn, err := db.Open(context.Background())
   if err != nil {
       // handle error
   }
   defer cnxn.Close()
}

URI 格式

Snowflake URI 应采用以下格式之一

• user[:password]@account/database/schema[?param1=value1&paramN=valueN]

• user[:password]@account/database[?param1=value1&paramN=valueN]

• user[:password]@host:port/database/schema?account=user_account[&param1=value1&paramN=valueN]

• host:port/database/schema?account=user_account[&param1=value1&paramN=valueN]

或者，除了提供完整的 URI 之外，还可以使用其他可用选项或 URI 和其他选项的某些组合完全提供配置。如果提供了 URI，它将首先被解析，并且提供的任何显式选项将覆盖从 URI 解析的任何内容。

支持的功能

Snowflake 驱动程序通常支持 ADBC API 规范 1.0.0 中定义的功能，以及一些其他自定义选项。

身份验证

Snowflake 要求启用某种形式的身份验证。默认情况下，它将尝试使用用户名/密码身份验证。用户名和密码可以提供在 URI 中，也可以通过 username 和 password 选项提供给 AdbcDatabase。

或者，可以指定和自定义其他类型的身份验证。“客户端选项”部分详细介绍了所有选项。

SSO 身份验证

Snowflake 支持 单点登录。如果您的帐户已配置为使用 SSO，则可以通过在构建 AdbcDatabase 时设置以下选项来与 Snowflake 驱动程序一起使用

• adbc.snowflake.sql.account：您的 Snowflake 帐户。（例如，如果您登录到 https://foobar.snowflakecomputing.com，则您的帐户标识符为 foobar。）

• adbc.snowflake.sql.auth_type：auth_ext_browser。

• username：您的用户名。（这可能应该是您的电子邮件，例如 [email protected]。）

应该会出现一个新的浏览器选项卡或窗口，您可以在其中继续登录。完成后，您将拥有一个完整的 ADBC 数据库/连接对象。一些用户报告需要其他配置选项，例如 adbc.snowflake.sql.region 和 adbc.snowflake.sql.uri.*（请参见下文以获取列表）。

Python

import adbc_driver_snowflake.dbapi
# This will open a new browser tab, and block until you log in.
adbc_driver_snowflake.dbapi.connect(db_kwargs={
    "adbc.snowflake.sql.account": "foobar",
    "adbc.snowflake.sql.auth_type": "auth_ext_browser",
    "username": "[email protected]",
})

R

library(adbcdrivermanager)
db <- adbc_database_init(
  adbcsnowflake::adbcsnowflake(),
  adbc.snowflake.sql.account = 'foobar',
  adbc.snowflake.sql.auth_type = 'auth_ext_browser'
  username = '[email protected]',
)
# This will open a new browser tab, and block until you log in.
con <- adbc_connection_init(db)

Go

import (
   "context"

   "github.com/apache/arrow-adbc/go/adbc"
   "github.com/apache/arrow-adbc/go/adbc/driver/snowflake"
)

func main() {
   var drv snowflake.Driver
   db, err := drv.NewDatabase(map[string]string{
       snowflake.OptionAccount: "foobar",
       snowflake.OptionAuthType: snowflake.OptionValueAuthExternalBrowser,
       adbc.OptionKeyUsername: "[email protected]",
   })
   if err != nil {
       // handle error
   }
   defer db.Close()

   cnxn, err := db.Open(context.Background())
   if err != nil {
       // handle error
   }
   defer cnxn.Close()
}

批量导入

支持批量导入。Arrow 类型到 Snowflake 类型的映射如下所示。

批量导入是通过将 Arrow 数据写入 Parquet 文件并将其上传（通过 PUT）到临时内部阶段来实现的。执行一个或多个 COPY 查询以将数据加载到目标表中。

为了使驱动程序能够利用此临时阶段，用户必须对架构具有 CREATE STAGE <https://docs.snowflake.com/en/sql-reference/sql/create-stage> 权限。此外，必须设置会话的当前数据库和架构。如果未设置这些内容，则驱动程序执行的 CREATE TEMPORARY STAGE 命令可能会因以下错误而失败

CREATE TEMPORARY STAGE ADBC$BIND FILE_FORMAT = (TYPE = PARQUET USE_LOGICAL_TYPE = TRUE BINARY_AS_TEXT = FALSE)
CANNOT perform CREATE STAGE. This session does not have a current schema. Call 'USE SCHEMA' or use a qualified name.

以下非正式基准测试演示了使用默认导入设置的预期性能

Running on GCP e2-standard-4 (4 vCPU, 16GB RAM)
Snowflake warehouse size M, same GCP region as Snowflake account
Default ingestion settings

TPC-H Lineitem (16 Columns):
   Scale Factor 1 (6M Rows): 9.5s
   Scale Factor 10 (60M Rows): 45s

导入的默认设置应针对许多现实世界的配置实现良好的平衡。如果需要，可以使用 AdbcStatement 对象上的以下选项调整性能和资源使用情况

adbc.snowflake.statement.ingest_writer_concurrency

并行写入的 Parquet 文件数。默认情况下尝试根据检测到的逻辑核心最大化工作程序，但如果在受限环境中运行，可能需要进行调整。如果设置为 0，则使用默认值。不能为负数。

adbc.snowflake.statement.ingest_upload_concurrency

并行上传的 Parquet 文件数。更大的并发性可以平滑 TCP 拥塞并帮助利用可用的网络带宽，但会增加内存利用率。默认值为 8。如果设置为 0，则使用默认值。不能为负数。

adbc.snowflake.statement.ingest_copy_concurrency

并发运行的 COPY 操作的最大数量。批量导入性能通过在文件仍在上传时执行 COPY 查询来优化。Snowflake COPY 速度随仓库大小而扩展，因此较小的仓库可能会受益于将此值设置得更高，以确保长时间运行的 COPY 查询不会阻止新上传的文件被加载。默认值为 4。如果设置为 0，则仅在所有文件上传完成后，作为导入的一部分执行单个 COPY 查询。不能为负数。

adbc.snowflake.statement.ingest_target_file_size

导入期间写入的 Parquet 文件的大致大小。实际大小会略大，具体取决于页脚/元数据的大小。默认值为 10 MB。如果设置为 0，则文件大小没有限制。不能为负数。

分区结果集

目前不支持分区结果集。

性能

查询 Snowflake 数据时，结果可能会从多个端点并行获取。每个端点排队的批次数量有限，尽管数据始终按端点的顺序返回给客户端。

要管理结果获取的性能，有两个选项可以控制缓冲和并发行为。这些选项只能在 AdbcStatement 对象上设置

adbc.rpc.result_queue_size

记录读取器中要排队的批次数。默认为 200。必须是大于 0 的整数。

adbc.snowflake.rpc.prefetch_concurrency

一次从 Snowflake 获取的并发流数。默认为 10。必须是大于 0 的整数。

事务

支持事务。请记住，如果运行任何 DDL 语句（例如 CREATE TABLE），Snowflake 事务将隐式提交。

客户端选项

用于创建 Snowflake 数据库连接的选项可以自定义。这些选项与 Snowflake Config 对象 <https://pkg.go.dev/github.com/snowflakedb/gosnowflake#Config> 一一对应。

adbc.snowflake.sql.db

此会话应默认使用的数据库。

adbc.snowflake.sql.schema

此会话应默认使用的架构。

adbc.snowflake.sql.warehouse

此会话应默认使用的仓库。

adbc.snowflake.sql.role

应用于身份验证的角色。

adbc.snowflake.sql.region

用于构建连接 URI 的 Snowflake 区域。

adbc.snowflake.sql.account

应用于身份验证和构建连接 URI 的 Snowflake 帐户。

adbc.snowflake.sql.uri.protocol

这应该是 http 或 https。

adbc.snowflake.sql.uri.port

用于构建连接 URI 的端口。

adbc.snowflake.sql.uri.host

用于构建要连接到的 URL 的显式主机。

adbc.snowflake.sql.auth_type

允许指定备用类型的身份验证，允许的值为

• auth_snowflake：通用用户名/密码身份验证（这是默认值）

• auth_oauth：对 Snowflake 连接使用 OAuth 身份验证。

• auth_ext_browser：使用外部浏览器访问 FED 并执行 SSO 身份验证。

• auth_okta：使用本机 Okta URL 使用 Okta 执行 SSO 身份验证

• auth_jwt：使用提供的 JWT 执行身份验证。

• auth_mfa：使用带 MFA 的用户名和密码。

adbc.snowflake.sql.client_option.auth_token

如果使用 OAuth 或其他形式的身份验证，则此选项是您可以显式指定用于连接的令牌的方式。

adbc.snowflake.sql.client_option.okta_url

如果使用 auth_okta，则此选项是必需的，以便指定要连接到的用于 SSO 身份验证的 Okta URL。

adbc.snowflake.sql.client_option.login_timeout

指定登录重试超时，不包括网络往返时间和读取 http 响应。值的格式应如 此处 <https://pkg.go.dev/time#ParseDuration> 所述，例如 300ms、1.5s 或 1m30s。即使接受负值，也将使用此持续时间的绝对值。

adbc.snowflake.sql.client_option.request_timeout

指定请求重试超时，不包括网络往返时间和读取 http 响应。值的格式应如 此处 <https://pkg.go.dev/time#ParseDuration> 所述，例如 300ms、1.5s 或 1m30s。即使接受负值，也将使用此持续时间的绝对值。

adbc.snowflake.sql.client_option.jwt_expire_timeout

JWT 过期将在此超时后发生。值的格式应如 此处 <https://pkg.go.dev/time#ParseDuration> 所述，例如 300ms、1.5s 或 1m30s。即使接受负值，也将使用此持续时间的绝对值。

adbc.snowflake.sql.client_option.client_timeout

指定网络往返时间和读取 http 响应的超时。值的格式应如 此处 <https://pkg.go.dev/time#ParseDuration> 所述，例如 300ms、1.5s 或 1m30s。即使接受负值，也将使用此持续时间的绝对值。

adbc.snowflake.sql.client_option.app_name

允许为连接指定 Snowflake 的应用程序名称。

adbc.snowflake.sql.client_option.tls_skip_verify

禁用服务器 TLS 证书的验证。值应为 true 或 false。

adbc.snowflake.sql.client_option.ocsp_fail_open_mode

控制 OCSP 的故障打开模式。默认为 true。值应为 true 或 false。

adbc.snowflake.sql.client_option.keep_session_alive

即使连接关闭后，也启用会话保持。值应为 true 或 false。

adbc.snowflake.sql.client_option.jwt_private_key

指定应用于对 JWT 进行身份验证签名的 RSA 私钥。这应该是包含要读取和解析的 PKCS1 私钥的文件的路径。通常以“RSA 私钥”类型的 PEM 块进行编码。

adbc.snowflake.sql.client_option.jwt_private_key_pkcs8_value

解析加密或未加密的 PKCS #8 私钥，无需从文件系统读取。如果使用加密，则需要 adbc.snowflake.sql.client_option.jwt_private_key_pkcs8_password 值并用于解密。

adbc.snowflake.sql.client_option.jwt_private_key_pkcs8_password

传递加密的 PKCS #8 值时使用的密码。

adbc.snowflake.sql.client_option.disable_telemetry

Snowflake 驱动程序允许进行遥测信息，可以通过将其设置为 true 来禁用。值应为 true 或 false。

adbc.snowflake.sql.client_option.config_file

指定客户端配置 JSON 文件的位置。有关更多详细信息，请参阅 [Snowflake Go 文档](https://github.com/snowflakedb/gosnowflake/blob/a26ac8a1b9a0dda854ac5db9c2c145f79d5ac4c0/doc.go#L130)。

adbc.snowflake.sql.client_option.tracing

设置日志记录级别

adbc.snowflake.sql.client_option.cache_mfa_token

当 true 时，MFA 令牌将缓存在凭据管理器中。在 Windows/OSX 上默认为 true，在 Linux 上默认为 false。

adbc.snowflake.sql.client_option.store_temp_creds

当 true 时，ID 令牌将缓存在凭据管理器中。在 Windows/OSX 上默认为 true，在 Linux 上默认为 false。

adbc.snowflake.sql.client_option.use_high_precision

当 true 时，类型为 NUMBER 的定点 Snowflake 列将作为 Decimal128 类型 Arrow 列返回，使用 NUMBER 类型的精度和小数位数。当 false 时，小数位数为 0 的 NUMBER 列将作为 Int64 类型 Arrow 列返回，非零小数位数的列将作为 Float64 类型 Arrow 列返回。默认为 true。

元数据

调用 AdbcConnectionGetTableSchema() 时，返回的 Arrow Schema 将包含每个字段的元数据

DATA_TYPE

这将是一个包含此列的原始 Snowflake 数据类型的字符串。

PRIMARY_KEY

这将是 Y 或 N，以指示列是否为主键。

此外，查询结果流上的模式将在每个字段上包含以下元数据键

logicalType

此列的 Snowflake 逻辑类型。将是以下之一：fixed、real、text、date、variant、timestamp_ltz、timestamp_ntz、timestamp_tz、object、array、binary、time、boolean。

precision

表示字段的 Snowflake 精度的整数。

scale

表示此字段中值的 Snowflake 小数位数的整数。

charLength

如果是文本字段，这将等效于 VARCHAR(#) 参数 #。

byteLength

将包含从 Snowflake 发送回的原始数据的长度（以字节为单位），无论 Arrow 中字段的类型是什么。

类型支持

由于 Snowflake 类型不一定与 Arrow 类型一一对应，因此在请求数据时应该预期以下内容。任何指示的转换都是为了确保记录批次的流的一致性。

Snowflake 类型	Arrow 类型	注释
整数类型	number(38, 0)	Snowflake 中的所有整数类型都存储为数字，对于这些数字，无法指定精度和小数位数。
float/double	float64	Snowflake 不区分 float 或 double。两者都是 64 位值。
decimal/numeric	numeric	Snowflake 将尊重 Arrow 类型的精度和小数位数。有关此行为的例外情况，请参阅 adbc.snowflake.sql.client_option.use_high_precision。
time	time64[ns]	对于摄取，也可以使用 time32。
date	date32	对于摄取，也可以使用 date64。
timestamp_ltz timestamp_ntz timestamp_tz	timestamp[ns]	将使用本地时区，除了 timestamp_ntz 不是瞬时值。在这种情况下，类型中将不存在时区。物理值将是 UTC 规范化的。
variant object array	string	Snowflake 不提供有关嵌套类型的信息。值将是以类似 JSON 的格式表示的字符串，可以进行解析。Arrow 类型将包含一个元数据键 logicalType，其中包含 Snowflake 字段类型。Arrow 结构体和映射类型在摄取时将存储为对象。列表类型将存储为数组。
geography geometry	string	目前没有这些类型的规范 Arrow（扩展）类型，因此它们将作为 Snowflake 提供的字符串值返回。