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 中提供，或透過 AdbcDatabase 的 username 和 password 選項提供。

或者，可以指定和自訂其他類型的身份驗證。有關所有選項的詳細資訊，請參閱下面的「用戶端選項」。

SSO 身份驗證

Snowflake 支援 單一登入。如果您的帳戶已配置 SSO，則可以透過在建構 AdbcDatabase 時設定以下選項來與 Snowflake 驅動程式一起使用

• adbc.snowflake.sql.account：您的 Snowflake 帳戶。（例如，如果您登入 https://foobar.snowflakecomputing.com，則您的帳戶識別碼為 foobar。）

• adbc.snowflake.sql.auth_type：auth_ext_browser。

• username：您的使用者名稱。（這應該是您的電子郵件，例如 jdoe@example.com。）

應該會出現新的瀏覽器標籤頁或視窗，您可以在其中繼續登入。完成此操作後，您將擁有完整的 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": "jdoe@example.com",
})

R

library(adbcdrivermanager)
db <- adbc_database_init(
  adbcsnowflake::adbcsnowflake(),
  adbc.snowflake.sql.account = 'foobar',
  adbc.snowflake.sql.auth_type = 'auth_ext_browser'
  username = 'jdoe@example.com',
)
# 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: "jdoe@example.com",
   })
   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> 1:1 對應。

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：使用 OAuth 身份驗證進行 Snowflake 連線。

• 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 PRIVATE KEY” 類型的 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 綱要將包含每個欄位的中繼資料

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 類型 1 對 1 匹配，因此以下是請求資料時應預期的內容。指示的任何轉換都是為了確保記錄批次串流的一致性而完成的。

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 類型將包含具有 Snowflake 欄位類型中繼資料金鑰 logicalType。Arrow Struct 和 Map 類型將在載入時儲存為物件。List 類型將儲存為陣列。
geography geometry	string	這些類型目前沒有標準的 Arrow（擴充）類型，因此它們將以 Snowflake 提供的字串值傳回。