snowflake

DolphinDB Server 2.00.16 及更高版本、3.00.4 及更高版本，安装包类型为 Linux x86_64 或 Linux x86_64 ABI。

1. 在 DolphinDB 客户端中使用 listRemotePlugins 函数查看可供安装的插件。

   login("admin", "123456")
   listRemotePlugins()

2. 使用 installPlugin 函数安装插件。

   installPlugin("snowflake")

3. 使用 loadPlugin 函数加载插件。

   loadPlugin("snowflake")

语法

snowflake::connect(config)

详情

建立与 Snowflake 数据库的连接，并返回一个连接句柄。

参数

config 字典（Dictionary<STRING, ANY>），指定连接配置，支持以下键值对：

options 字典支持以下键值对：

返回值

一个连接句柄。

示例

// 基本配置
config = dict(STRING, ANY)
config["account"] = "myorg-myaccount"
config["user"] = "DDB_READER"
config["privateKeyPath"] = "/opt/dolphindb/keys/snowflake_rsa_key.p8"
config["warehouse"] = "DDB_WH"
config["database"] = "SALES_DB"
config["schema"] = "PUBLIC"
config["role"] = "DDB_READER_ROLE"

// 通过 options 字典设置私钥口令和超时时间
connOptions = dict(STRING, ANY)
connOptions["privateKeyPassphrase"] = "<PRIVATE_KEY_PASSPHRASE>"
connOptions["connectTimeoutSeconds"] = 20
connOptions["requestTimeoutSeconds"] = 120
connOptions["pollIntervalMillis"] = 1000
connOptions["maxPollSeconds"] = 1800
connOptions["maxRetry"] = 5
config["options"] = connOptions

conn = snowflake::connect(config)

语法

snowflake::close(conn)

详情

关闭指定的连接。连接关闭后，若将对应的句柄传给任意插件接口，运行接口时将报错：Invalid connection object.

参数

conn 由 connect 创建的连接句柄。

返回值

字符串 "Connection is closed."

语法

snowflake::showTables(conn, [database], [schema])

详情

查看当前 Snowflake 用户可见的表或视图。

参数

conn 由 connect 创建的连接句柄。

database STRING 类型标量，指定要查询的数据库。默认为创建对应连接句柄时指定的数据库。

schema STRING 类型标量，指定要查询的架构。默认为创建对应连接句柄时指定的架构。

返回值

一张表，包含以下列，没有可见对象时返回空表：

示例

// 查询连接默认的数据库和架构
objects = snowflake::showTables(conn)

// 指定数据库，架构仍使用连接默认值
objects = snowflake::showTables(conn, "ARCHIVE_DB")

// 同时指定数据库和架构
objects = snowflake::showTables(conn, "ARCHIVE_DB", "REPORTING")

// 只指定架构，可把 database 参数设置为 NULL
objects = snowflake::showTables(conn, NULL, "REPORTING")

语法

snowflake::extractTableSchema(conn, sourceTableName)

详情

获取 Snowflake 表的结构。

参数

conn 由 connect 创建的连接句柄。

sourceTableName STRING 类型标量，指定 Snowflake 表的名称，支持 1-3 段表名形式：TABLE_NAME、SCHEMA_NAME.TABLE_NAME、DATABASE_NAME.SCHEMA_NAME.TABLE_NAME。

返回值

一张表，包含以下列：

语法

snowflake::extractQuerySchema(conn, sql)

详情

对 Snowflake 表执行指定的 SELECT 语句，获取查询结果的结构。

参数

conn 由 connect 创建的连接句柄。

sql STRING 类型标量，指定查询 SQL。插件会删除 SQL 尾部的分号，并将查询包装为类似以下的语句：

SELECT *
FROM (<sql>) AS SNOWFLAKE_PLUGIN_SCHEMA
WHERE 1 = 0

因此，sql 必须是可作为子查询使用的 SELECT 语句。DDL 或 DML 语句不适合传给该接口。

返回值

一张表，包含以下列：

语法

snowflake::loadTable(conn, sourceTableName, [options])

详情

加载 Snowflake 表数据并返回为 DolphinDB 内存表。

参数

conn 由 connect 创建的连接句柄。

sourceTableName STRING 类型标量，指定 Snowflake 表的名称，支持 1-3 段表名形式：TABLE_NAME、SCHEMA_NAME.TABLE_NAME、DATABASE_NAME.SCHEMA_NAME.TABLE_NAME。

options 可选参数，字典（Dictionary<STRING, ANY>），支持 "columnSchema"、"offset"、"limit"、"allowEmptyResult" 键，详情参见数据查询接口的公共参数。

返回值

DolphinDB 内存表。

示例

// 不指定额外配置 options
orders = snowflake::loadTable(conn, "SALES_DB.PUBLIC.ORDERS")

// 分页返回数据
options = dict(STRING, ANY)
options["offset"] = 1000
options["limit"] = 500
options["allowEmptyResult"] = true

ordersPage = snowflake::loadTable(
    conn,
    "SALES_DB.PUBLIC.ORDERS",
    options
)

// 自定义列类型
columnSchema = table(
    ["order_id", "customer", "amount"] as name,
    ["LONG", "STRING", "DOUBLE"] as type
)

options = dict(STRING, ANY)
options["columnSchema"] = columnSchema

orders = snowflake::loadTable(
    conn,
    "SALES_DB.PUBLIC.ORDER_SUMMARY",
    options
)

语法

snowflake::query(conn, sql, [options])

详情

对 Snowflake 表执行指定的 SELECT 语句，并将查询结果返回为 DolphinDB 内存表。

参数

conn 由 connect 创建的连接句柄。

sql STRING 类型标量，指定查询 SQL。插件会删除 SQL 尾部的分号，并将查询包装为类似以下的语句：

SELECT *
FROM (<sql>) AS SNOWFLAKE_PLUGIN_SCHEMA
WHERE 1 = 0

因此，sql 必须是可作为子查询使用的 SELECT 语句。DDL 或 DML 语句不适合传给该接口。

options 可选参数，字典（Dictionary<STRING, ANY>），支持 "columnSchema"、"allowEmptyResult" 键，详情参见数据查询接口的公共参数。

返回值

DolphinDB 内存表。

示例

// 不指定额外配置 options
sql = "SELECT ORDER_ID, AMOUNT FROM SALES_DB.PUBLIC.ORDERS WHERE AMOUNT > 100 ORDER BY ORDER_ID"
result = snowflake::query(conn, sql)

// 分页返回数据
sql = "SELECT ORDER_ID, AMOUNT FROM SALES_DB.PUBLIC.ORDERS ORDER BY ORDER_ID LIMIT 500 OFFSET 1000"

options = dict(STRING, ANY)
options["allowEmptyResult"] = true

result = snowflake::query(conn, sql, options)

语法

snowflake::loadTableInto(conn, sourceTableName, targetTable, [options])

详情

加载 Snowflake 表数据并将其写入 DolphinDB 表。

参数

conn 由 connect 创建的连接句柄。

sourceTableName STRING 类型标量，指定 Snowflake 表的名称，支持 1-3 段表名形式：TABLE_NAME、SCHEMA_NAME.TABLE_NAME、DATABASE_NAME.SCHEMA_NAME.TABLE_NAME。

targetTable 一个表对象，可以是 DolphinDB 内存表或分布式表。

options 可选参数，字典（Dictionary<STRING, ANY>），支持 "columnSchema"、"offset"、"limit"、"batchTransform" 键，详情参见数据查询接口的公共参数。

返回值

无

示例

// 写入 DolphinDB 内存表
target = table(
    100000:0,
    `order_id`customer`amount,
    [LONG, STRING, DOUBLE]
)

writtenRows = snowflake::loadTableInto(
    conn,
    "SALES_DB.PUBLIC.ORDER_SUMMARY",
    target
)

// 限制读取行数
options = dict(STRING, ANY)
options["limit"] = 10000

writtenRows = snowflake::loadTableInto(
    conn,
    "SALES_DB.PUBLIC.ORDER_SUMMARY",
    target,
    options
)

语法

snowflake::queryInto(conn, sql, targetTable, [options])

详情

对 Snowflake 表执行指定的 SELECT 语句，将查询结果写入 DolphinDB 表。

参数

conn 由 connect 创建的连接句柄。

sql STRING 类型标量，指定查询 SQL。插件会删除 SQL 尾部的分号，并将查询包装为类似以下的语句：

SELECT *
FROM (<sql>) AS SNOWFLAKE_PLUGIN_SCHEMA
WHERE 1 = 0

因此，sql 必须是可作为子查询使用的 SELECT 语句。DDL 或 DML 语句不适合传给该接口。

targetTable 一个表对象，可以是 DolphinDB 内存表或分布式表。

options 可选参数，字典（Dictionary<STRING, ANY>），支持 "columnSchema"、"batchTransform" 键，详情参见数据查询接口的公共参数。

返回值

无

示例

// 写入 DolphinDB 内存表
target = table(
    100000:0,
    `order_id`customer`amount,
    [LONG, STRING, DOUBLE]
)

sql = "SELECT ORDER_ID, CUSTOMER, AMOUNT FROM SALES_DB.PUBLIC.ORDERS ORDER BY ORDER_ID"
writtenRows = snowflake::queryInto(conn, sql, target)

// 写入 DolphinDB 分布式表
target = loadTable("dfs://sales", `orders)

sql = "SELECT ORDER_ID, CUSTOMER, AMOUNT FROM SALES_DB.PUBLIC.ORDERS"
writtenRows = snowflake::queryInto(conn, sql, target)

插件根据 Snowflake SQL API 返回的 metadata 中的 type、precision 和 scale 进行类型映射，而不是仅根据建表 DDL 中使用的类型名称进行判断。

以下 Snowflake 数据类型当前通常映射为 STRING：

• CHAR、VARCHAR、TEXT

• DATE、TIME

• TIMESTAMP_NTZ、TIMESTAMP_LTZ、TIMESTAMP_TZ

• BINARY、VARBINARY

• ARRAY、OBJECT、VARIANT

• GEOGRAPHY、GEOMETRY、VECTOR

• 其他未在上述映射规则中列出的类型

对于映射为 STRING 的类型，返回值为 Snowflake SQL API 返回值的文本表示。特别是 DATE、TIME 和 TIMESTAMP 类型，当前不应假定其返回值为 DolphinDB 原生时间类型。

columnSchema 支持以下目标类型及其别名。类型名大小写不敏感。

非 NULL 文本是指 Snowflake SQL API 返回的非 NULL 字段值的文本表示。

如果 columnSchema 中指定了上述列表之外的类型，接口将返回错误：schema type ... is not supported yet

插件请求 Snowflake SQL API 时设置 nullable=true，并按以下规则处理返回值：

• Snowflake SQL NULL：以 JSON null 返回，并转换为对应 DolphinDB 类型的 NULL。

• 字符串 "null"：作为普通字符串处理，不视为 NULL。

• 非 NULL 空字符串：DolphinDB 使用空字符串表示 NULL。因此，Snowflake 中的非 NULL 空字符串如果直接转换会被误认为 NULL，插件将阻止转换并报错。

• 非 NULL 数值：如果 Snowflake 返回的非 NULL 数值等于 DolphinDB 对应类型的 NULL 表示值，直接转换会被误认为 NULL。为避免数据错误，插件将阻止转换并报错。例如，Snowflake 返回的 INT 最小值、LONG 最小值，或等于 DolphinDB DOUBLE NULL 表示值的数值，均无法作为非 NULL 值转换。

• 数值转换：数值文本必须能够被完整解析为目标类型。包含多余字符或超出目标类型可表示范围时，将报转换错误。

• NUMBER/DECIMAL：当 scale != 0 时，默认映射为 DOUBLE，可能产生浮点精度损失。如需完整保留原始数值文本，可通过 columnSchema 将该列指定为 STRING 类型。