Amazon Athena Snowflake 連接器 - Amazon Athena
先決條件限制條款參數支援的資料類型資料類型轉換分割區和分隔效能傳遞查詢授權資訊其他資源

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Amazon Athena Snowflake 連接器

適用於 Snowflake 的 Amazon Athena 連接器可讓 Amazon Athena 使用 JDBC 對存放在 Snowflake SQL 資料庫或 RDS 執行個體中的資料執行 SQL 查詢。

此連接器可以向 Glue Data Catalog 註冊為聯合目錄。它支援 Lake Formation 中在目錄、資料庫、資料表、資料欄、資料列和標籤層級定義的資料存取控制。此連接器使用 Glue Connections 來集中 Glue 中的組態屬性。

先決條件

AWS 帳戶 使用 Athena 主控台或 CreateDataCatalog API 操作將連接器部署到 。如需詳細資訊，請參閱建立資料來源連線。

限制

  • 不支援寫入 DDL 操作。

  • 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。

  • 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》中的 Lambda 配額。

  • 目前支援採用單一分割方式的 Snowflake 檢視。

  • 在 Snowflake 中，由於物件名稱區分大小寫，因此兩個資料表的名稱可能會相同，分別為小寫和大寫 (例如，EMPLOYEE 和 employee)。在 Athena 聯合查詢中，結構描述資料表名稱會以小寫形式提供給 Lambda 函數。若要解決此問題，您可以提供 @schemaCase 查詢提示以便從名稱區分大小寫的資料表中擷取資料。以下是具有查詢提示的兩個查詢範例。

    SELECT * FROM "lambda:snowflakeconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=upper"     
    SELECT * FROM "lambda:snowflakeconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=lower"

  • 如果您將 Snowflake 連線遷移至 Glue Catalog 和 Lake Formation，Athena 不會將所有請求預設為大寫或支援註釋。Glue Connection 的預設行為不會調整大小寫。

    Snowflake 支援下列大小寫模式：

    • NONE （使用 Glue Connection 的連接器預設值）

    • CASE_INSENSITIVE_SEARCH

    • ANNOTATION （不含 Glue 連線之連接器的預設值）

條款

下列術語與 Snowflake 連接器相關。

  • 資料庫執行個體 - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。

  • 處理常式 - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。

  • 中繼資料處理常式 - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。

  • 記錄處理常式 - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。

  • 複合處理常式 - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。

  • 屬性或參數 - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。

  • 連接字串 - 用來建立資料庫執行個體連線的文字字串。

  • Catalog – 向 Athena 註冊的非AWS Glue 目錄，是 connection_string 屬性的必要字首。

  • 多工處理常式 - 可以接受和使用多個資料庫連接的 Lambda 處理常式。

參數

使用本節中的參數來設定 Snowflake 連接器。

建議您使用 Glue 連線物件來設定 Snowflake 連接器。若要這樣做，請將 Snowflake 連接器 Lambda glue_connection的環境變數設定為要使用的 Glue 連線名稱。

Glue 連線屬性

使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。

aws glue describe-connection-type --connection-type SNOWFLAKE

Lambda 環境屬性

  • glue_connection – 指定與聯合連接器相關聯的 Glue 連線名稱。

  • casing_mode – （選用） 指定如何處理結構描述和資料表名稱的案例。casing_mode 參數使用下列值來指定大小寫的行為：

    • none – 請勿變更指定結構描述和資料表名稱的大小寫。對於具有相關聯黏附連線的連接器，這是預設值。

    • 註釋 – 如果存在註釋，則調整資料表名稱。對於沒有相關聯黏附連線的連接器，這是預設值。

    • case_insensitive_search – 針對 Snowflake 中的結構描述和資料表名稱執行不區分大小寫的搜尋。如果您的查詢包含不符合連接器預設大小寫的結構描述或資料表名稱，請使用此值。

    • upper – 大寫所有指定的結構描述和資料表名稱。

    • 小 – 小寫所有指定的結構描述和資料表名稱。

注意

  • 使用 Glue 連線建立的 Snowflake 連接器不支援使用多工處理常式。

  • 使用 Glue 連線建立的 Snowflake 連接器僅支援 ConnectionSchemaVersion 2。

儲存登入資料

使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。如需詳細資訊，請參閱使用 Snowflake 驗證。

注意

2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。

下列參數名稱和定義適用於在沒有相關聯 Glue 連線的情況下建立的 Athena 資料來源連接器。只有在您手動部署舊版的 Athena 資料來源連接器或未指定glue_connection環境屬性時，才能使用下列參數。

Lambda 環境屬性

  • default – 用來連線至 Snowflake 資料庫執行個體的 JDBC 連線字串。例如 snowflake://${jdbc_connection_string}

  • catalog_connection_string – 由多工處理常式使用 （使用黏性連線時不支援）。資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄是 mysnowflakecatalog，則環境變數名稱是 mysnowflakecatalog_connection_string。

  • spill_bucket - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。

  • spill_prefix - (選用) 預設為指定的 spill_bucket 中名為 athena-federation-spill 的子資料夾。我們建議您在此位置設定 Amazon S3 儲存生命週期，以刪除超過預定天數或小時數的溢出。

  • spill_put_request_headers – (選用) 用於溢出的 Amazon S3 putObject 請求的請求標頭和值的 JSON 編碼映射 (例如，{"x-amz-server-side-encryption" : "AES256"})。如需了解其他可能的標頭，請參閱《Amazon Simple Storage Service API 參考》中的 PutObject。

  • kms_key_id - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 a7e63k4b-8loc-40db-a2a1-4d0en2cd8331，您可以指定 KMS 金鑰 ID。

  • disable_spill_encryption - (選用) 當設定為 True 時，停用溢出加密。預設為 False，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用伺服器端加密。

連接字串

使用下列格式的 JDBC 連接字串來連接資料庫執行個體。

snowflake://${jdbc_connection_string}

使用多工處理常式

您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。

處理常式 類別
複合處理常式 SnowflakeMuxCompositeHandler
中繼資料處理常式 SnowflakeMuxMetadataHandler
記錄處理常式 SnowflakeMuxRecordHandler
多工處理常式參數
參數 描述
$catalog_connection_string 必要。資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 mysnowflakecatalog，則環境變數名稱為 mysnowflakecatalog_connection_string。
default 必要。預設的連接字串。目錄為 lambda:${AWS_LAMBDA_FUNCTION_NAME} 時，使用此字串。

下列範例屬性適用於支援兩個資料庫執行個體的 Snowflake MUX Lambda 函數：snowflake1 (預設) 和 snowflake2。

屬性 Value
default snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1&${Test/RDS/Snowflake1}
snowflake_catalog1_connection_string snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}
snowflake_catalog2_connection_string snowflake://jdbc:snowflake://snowflake2.host:port/?warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2
提供憑證

要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。

  • 連接字串 - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。

    重要

    基於安全最佳實務，請勿在環境變數或連線字串中使用硬式編碼登入資料。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱AWS Secrets Manager 《 使用者指南》中的將硬式編碼秘密移至 AWS Secrets Manager 。

  • AWS Secrets Manager – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有網際網路存取或 VPC 端點，以連接至 Secrets Manager。

    您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 username 和 password 值。

    對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON：

    {"username": "${username}", "password": "${password}"}
帶有秘密名稱的連接字串範例

以下字串具有秘密名稱 ${Test/RDS/Snowflake1}。

snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}&...

連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。

snowflake://jdbc:snowflake://snowflake1.host:port/warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2&...

目前，Snowflake 可辨識 user 和 password JDBC 屬性。它也接受格式為 username/password 的使用者名稱和密碼，而不使用金鑰 user 或 password。

使用單一連接處理常式

您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Snowflake 執行個體。

處理常式類型 類別
複合處理常式 SnowflakeCompositeHandler
中繼資料處理常式 SnowflakeMetadataHandler
記錄處理常式 SnowflakeRecordHandler
單一連接處理常式參數
參數 描述
default 必要。預設的連接字串。

單一連接處理常式支援一個資料庫執行個體，並且必須提供 default 連接字串參數。忽略所有其他連接字串。

下列範例屬性適用於 Lambda 函數所支援的單一 Snowflake 執行個體。

屬性 Value
default snowflake://jdbc:snowflake://snowflake1.host:port/?secret=Test/RDS/Snowflake1

溢出參數

Lambda SDK 可能會將資料溢出至 Amazon S3。由相同 Lambda 函數存取的所有資料庫執行個體溢出到相同的位置。

參數 描述
spill_bucket 必要。溢出儲存貯體名稱。
spill_prefix 必要。溢出儲存貯體金鑰字首。
spill_put_request_headers (選用) 用於溢出的 Amazon S3 putObject 請求的請求標頭和值的 JSON 編碼映射 (例如，{"x-amz-server-side-encryption" : "AES256"})。如需了解其他可能的標頭，請參閱《Amazon Simple Storage Service API 參考》中的 PutObject。

支援的資料類型

下表顯示 JDBC 和 Apache Arrow 的相應資料類型。

JDBC Arrow
Boolean 位元
Integer Tiny
Short Smallint
Integer Int
Long Bigint
float Float4
Double Float8
日期 DateDay
時間戳記 DateMilli
字串 Varchar
位元組 Varbinary
BigDecimal Decimal (小數)
ARRAY 清單

資料類型轉換

除了 JDBC 到 Arrow 轉換之外，連接器還會執行一些其他轉換，以使 Snowflake 來源和 Athena 資料類型相容。這些轉換有助於確保成功執行查詢。下表顯示了這些轉換。

來源資料類型 (Snowflake) 轉換後的資料類型 (Athena)
TIMESTAMP TIMESTAMPMILLI
DATE TIMESTAMPMILLI
INTEGER INT
DECIMAL BIGINT
TIMESTAMP_NTZ TIMESTAMPMILLI

所有其他不受支援的資料類型都會轉換為 VARCHAR。

分割區和分隔

分割區用於決定如何產生連接器的分割。Athena 建構了類型 varchar 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。

若要建立此合成資料欄和分割區，Athena 需要定義主索引鍵。不過，由於 Snowflake 不會強制執行主要金鑰限制，您必須自行強制執行唯一性。否則，Athena 會預設為單一分割。

效能

為了獲得最佳效能，請盡可能在查詢中使用篩選條件。此外，我們強烈建議使用原生分割來擷取具有統一分割區分佈的龐大資料集。選取資料欄子集可大幅加速查詢執行期，並減少掃描的資料。Snowflake 連接器由於並行而對限流保有彈性。

Athena Snowflake 連接器執行述詞下推，以減少查詢掃描的資料。LIMIT 子句、簡單述詞和複雜的表達式會下推至連接器，以減少掃描的資料量並縮短查詢執行期。

LIMIT 子句

LIMIT N 陳述句可減少查詢掃描的資料。透過 LIMIT N 下推，連接器只會向 Athena 傳回 N 個資料列。

述詞

述詞是 SQL 查詢的 WHERE 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Snowflake 連接器可以合併這些表達式，並將其直接推送至 Snowflake，以增強功能並減少掃描的資料量。

下列 Athena Snowflake 連接器運算子支援述詞下推：

  • 布林值：AND、OR、NOT

  • 等式：EQUAL、NOT_EQUAL、LESS_THAN、LESS_THAN_OR_EQUAL、GREATER_THAN、GREATER_THAN_OR_EQUAL、IS_DISTINCT_FROM、NULL_IF、IS_NULL

  • 算術：ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE

  • 其他：LIKE_PATTERN、IN

合併下推範例

如需增強的查詢功能，請合併下推類型，如以下範例所示：

SELECT * 
FROM my_table 
WHERE col_a > 10 
    AND ((col_a + col_b) > (col_c % col_d))
    AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') 
LIMIT 10;

傳遞查詢

Snowflake 連接器支援傳遞查詢。傳遞查詢使用資料表函數，將您的完整查詢向下推送至資料來源以進行執行。

若要搭配 Snowflake 使用傳遞查詢，您可以使用下列語法：

SELECT * FROM TABLE(
        system.query(
            query => 'query string'
        ))

下列範例查詢會將查詢下推至 Snowflake 中的資料來源。查詢會選取customer資料表中的所有資料欄，將結果限制為 10。

SELECT * FROM TABLE(
        system.query(
            query => 'SELECT * FROM customer LIMIT 10'
        ))

授權資訊

使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 pom.xml 檔案中找到其清單，並同意 GitHub.com 上 LICENSE.txt 檔案中提供的相應第三方授權中的條款。

其他資源

如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Snowflake 連接器的 pom.xml 檔案。

如需此連接器的其他資訊，請造訪 GitHub.com 上的相應網站。