Python Connector API¶

常量¶

apilevel¶

字符串常量，表示支持 API 级别。连接器支持 API "2.0"。

threadsafety¶

整数常量，表示界面支持的线程安全级别。Snowflake Connector for Python 支持 2 级别，它表示线程可以共享模块和连接。

paramstyle¶

字符串常量，表示界面预期的参数标记格式的类型。连接器默认支持 "pyformat" 类型，该类型适用于 Python 扩展格式代码（例如 ...WHERE name=%s 或 ...WHERE name=%(name)s）。Connection.connect 可以替换 paramstyle，以将绑定变量格式更改为 "qmark" 或 "numeric"，其中变量分别为 ? 或 :N。

例如：

format: .execute("... WHERE my_column = %s", (value,))
pyformat: .execute("... WHERE my_column = %(name)s", {"name": value})
qmark: .execute("... WHERE my_column = ?", (value,))
numeric: .execute("... WHERE my_column = :1", (value,))

Copy

备注

如果 paramstyle 是 "pyformat" 或 "format"，则绑定变量出现在客户端端；如果是 "qmark" 或 "numeric"，则出现在服务器端。目前，这些选项在性能或功能方面没有显著差异，因为连接器不支持其后进行多次执行的编译 SQL 文本。相反，"qmark" 和 "numeric" 选项与其他驱动程序（即 JDBC、ODBC、Go Snowflake Driver）的查询文本兼容性保持一致，这些驱动程序支持变量格式 ? 或 :N 与服务器端绑定。

函数¶

connect(parameters...)¶

目的:

用于创建数据库连接的构造函数。返回一个 Connection 对象。

默认情况下，自动提交模式处于 启用 状态（即如果连接关闭，则提交所有更改）。如果需要事务，请使用 BEGIN 命令启动事务，并使用 COMMIT 或 ROLLBACK 命令提交或回滚任何更改。

参数:

有效的输入参数为：

参数	必填	描述
account	是	您的账户标识符。账户标识符 不 包括 snowflakecomputing.cn 后缀。. . 有关详细信息和示例，请参阅 :ref:` 使用说明 <label-account_format_info>`（本主题内容）。
user	是	用户的登录名。
password	是	用户的密码。
application		用于标识建立连接的应用程序的名称。
region		已弃用 此参数说明仅用于向后兼容性。
host		主机名。
port		端口号（默认为 443）。
database		要使用的默认数据库的名称。登录后，您可以使用 USE DATABASE 更改数据库。
schema		要用于数据库的默认架构的名称。登录后，您可以使用 USE SCHEMA 更改架构。
role		要使用的默认角色的名称。登录后，您可以使用 USE ROLE 来更改角色。
warehouse		要使用的默认仓库的名称。登录后，您可以使用 USE WAREHOUSE 更改仓库。
passcode_in_password		默认为 False。如果登录密码中嵌入了 MFA（多重身份验证）密码，则将其设置为 True。
passcode		Duo 在使用 MFA（多重身份验证）登录时提供的密码。
private_key		用于身份验证的私钥。有关更多信息，请参阅 使用密钥对身份验证和密钥对轮换。
private_key_file		指定指定用户的私钥文件的路径。请参阅 使用密钥对身份验证和密钥对轮换。
private_key_file_pwd		指定用于解密指定用户的私钥文件的密码。请参阅 使用密钥对身份验证和密钥对轮换。
autocommit		默认为 None，它遵循 Snowflake 参数 AUTOCOMMIT。分别设置为 True 或 False，以启用或禁用会话中的自动提交模式。
client_fetch_use_mp		当设置为 True 时，它将启用多处理提取，这在许多情况下应该会减少提取时间。默认值：False。
client_prefetch_threads		用于下载结果集的线程数（默认为 4）。增加该值可提高提取性能，但需要更多内存。
client_session_keep_alive		要使会话始终保持活动状态（即便用户没有任何操作），请将此值设置为 True。将此值设置为 True 时，调用 close 方法以正确终止线程；否则，进程可能会挂起。默认值取决于您使用的连接器的版本： 版本 2.4.6 及更高版本： 默认为 None。. 当值为 None 时，CLIENT_SESSION_KEEP_ALIVE 会话参数优先。. . 若要替换会话参数，请为此实参传入 True 或 False。 版本 2.4.5 及更早版本： 默认为 False。. 当值为 False`（通过显式指定值或省略该实参）时，:ref:`label-client_session_keep_alive 会话参数优先。. . 将 client_session_keep_alive=False 传递给 connect 方法 不会 替换 CLIENT_SESSION_KEEP_ALIVE 会话参数中的值 TRUE。
login_timeout		登录超时（以秒为单位）。默认情况下，为 60 秒。如果 HTTP 响应是“成功”，则登录请求在超时时限后放弃。
network_timeout		所有其他操作的超时（以秒为单位）。默认情况下，为无/无限。如果 HTTP 响应不是“成功”，则一般请求在超时时限后放弃。
ocsp_response_cache_filename		OCSP 响应缓存文件的 URI。默认情况下，OCSP 响应缓存文件在缓存目录中创建： Linux：~/.cache/snowflake/ocsp_response_cache macOS：~/Library/Caches/Snowflake/ocsp_response_cache Windows：%USERPROFILE%AppDataLocalSnowflakeCachesocsp_response_cache 要在其他目录中找到文件，请在 URI（例如 file:///tmp/my_ocsp_response_cache.txt）中指定路径和文件名。
authenticator		Snowflake 的身份验证器： :code:`snowflake`（默认），使用内部 Snowflake 身份验证器。 externalbrowser，使用您的 Web 浏览器和 Okta、AD FS 或已为您的账户定义的任何其他符合 SAML 2.0 的身份提供商 (IdP) 进行身份验证。 https://<okta_account_name>.okta.com （即 Okta 账户的 URL 端点），通过原生 Okta 进行身份验证。 oauth，使用 OAuth 进行身份验证。您还必须指定 token 参数并将其值设置为 OAuth 访问令牌。 username_password_mfa，使用 MFA 令牌缓存进行身份验证。有关更多详细信息，请参阅 使用 MFA 令牌缓存，最大限度地减少身份验证过程中的提示次数 – 可选。 用于使用 OAuth 2.0 授权码流程的 OAUTH_AUTHORIZATION_CODE。 用于使用 OAuth 2.0 客户端凭据流程的 OAUTH_CLIENT_CREDENTIALS。 WORKLOAD_IDENTITY to authenticate with the workload identity federation (WIF) authenticator. 如果该值不是 snowflake，则用户和密码参数必须是 IdP 的登录凭据。
validate_default_parameters		默认为 False。如果为 True，则： 如果指定的数据库、架构或仓库不存在，则引发异常。 如果传递了无效的实参名称或错误数据类型的实参值，则向标准错误 (stderr) 打印警告。
paramstyle		对于客户端绑定，默认为 pyformat。指定 qmark 或 numeric 来更改服务器端绑定的绑定变量格式。
timezone		默认为 None，它遵循 Snowflake 参数 TIMEZONE。设置为有效时区（例如 America/Los_Angeles），从而设置会话时区。
arrow_number_to_decimal		默认为 False，这意味着以双精度浮点数 (float64) 的形式返回 NUMBER 列值。. . 将其设置为 True，在调用 fetch_pandas_all() 和 fetch_pandas_batches() 方法时以十进制数 (decimal.Decimal) 的形式返回 DECIMAL 列值。. . 在 Snowflake Connector for Python 版本 2.4.3 中引入此参数。
socket_timeout		套接字级读取和连接请求的超时（以秒为单位）。有关更多信息，请参阅 管理连接超时。
backoff_policy		生成器函数的名称，用于定义重试之间的等待时间。有关更多信息，请参阅 管理重试的连接退避策略。
enable_connection_diag		是否生成连接诊断报告。默认值为 False。
connection_diag_log_path		诊断报告位置的绝对路径。仅在 enable_connection_diag 为 True 的情况下使用。默认为操作系统的默认临时目录，例如 /tmp，适用于 Linux 或 Mac。
connection_diag_allowlist_path		包含 SYSTEM$ALLOWLIST() 或 SYSTEM$ALLOWLIST_PRIVATELINK() 输出的 JSON 文件的绝对路径。只有在连接中定义的用户没有权限运行系统允许列表功能或连接账户 URL 失败时才需要。
iobound_tpe_limit		preprocess_tpe 和 postprocess 线程池执行器 (TPEs) 的大小。默认情况下，该值为文件数和 CPU 核心数中的较小值。
unsafe_file_write		使用 GET 命令，指定要为从暂存区下载的文件分配的文件权限。False`（默认）将文件权限设置为 :codenowrap:`600，这意味着只有所有者可以访问文件。True 将权限设置为 644，这会授予所有者读写权限，并向其他所有人授予只读权限。有关更多信息，请参阅 下载数据。
oauth_client_id		身份提供商为 Snowflake 集成提供的 client id 的值（Snowflake 安全集成元数据）。
oauth_client_secret		身份提供商为 Snowflake 集成提供的 client secret 的值（Snowflake 安全集成元数据）。
oauth_authorization_url		向驱动程序提供授权码的身份提供商端点。当使用 Snowflake 作为身份提供商时，此值源自 server 或 account 参数。
oauth_token_request_url		向驱动程序提供访问令牌的身份提供商端点。当使用 Snowflake 作为身份提供商时，此值源自 server 或 account 参数。
oauth_scope		身份提供商授权请求中请求的范围。默认情况下，它源自角色。当需要多个作用域时，该值应为以空格分隔的多个作用域列表。
oauth_redirect_uri		URI to use for authorization code redirection (Snowflake security integration metadata). Default: http://127.0.0.1:{randomAvailablePort}.
oauth_disable_pkce		禁用代码交换证明密钥 (PKCE)，这是一项安全增强功能，可确保即使恶意攻击者拦截了授权码，也无法将其更改为有效的访问令牌。
oauth_enable_refresh_token		在实际访问令牌过期时启用静默重新身份验证，前提是授权服务器支持该功能并且 client_store_temporary_credential 设置为 True。
oauth_enable_single_use_refresh_tokens		是否选择启用一次性刷新令牌语义。
workload_identity_provider		Platform of the workload identity provider. Possible values include: AWS, AZURE, GCP, and OIDC.

属性¶

Error, Warning, ...

Python 数据库 API 标准定义的所有异常类。Snowflake Connector for Python 提供属性 msg、errno、sqlstate、sfqid 和 raw_msg。

account 参数的用法说明（适用于 connect 方法）¶

对于 必填 account 的参数，请指定您的 :doc:` 账户标识符 </user-guide/gen-conn-config>`。

请注意，账户标识符 不 包括 snowflakecomputing.cn 域名。Snowflake 会在创建连接时自动追加此内容。

以下示例示例使用 账户名称作为标识符，该账户 myaccount 位于组织 myorganization 中。

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='myorganization-myaccount',
    ... )

以下示例使用 账户定位器 xy12345 作为账户标识符：

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='xy12345',
    ... )

请注意，此示例使用 AWS US 西部（俄勒冈）区域中的账户。如果账户位于不同的区域，或者账户使用不同的云提供商，则需要 在账户定位器之后指定其他分段。

方法¶

autocommit(True|False)¶

目的:

启用或禁用自动提交模式。默认情况下，自动提交处于启用状态 (True)。

close()¶

目的:

关闭连接。如果在连接关闭时事务仍处于打开状态，则 :emph:` 回滚 ` 更改。

关闭连接会从服务器显式移除活动会话；否则，活动会话将继续进行，直到最终从服务器中清除，从而限制并发查询的数量。

例如：

# context manager ensures the connection is closed
with snowflake.connector.connect(...) as con:
    con.cursor().execute(...)

# try & finally to ensure the connection is closed.
con = snowflake.connector.connect(...)
try:
    con.cursor().execute(...)
finally:
    con.close()

Copy

commit()¶

目的:

如果禁用了自动提交，则提交当前事务。如果启用了自动提交，则忽略此方法。

rollback()¶

目的:

如果禁用了自动提交，则回滚当前事务。如果启用了自动提交，则忽略此方法。

cursor()¶

目的:

用于创建 Cursor 对象的构造函数。来自 fetch*() 调用的返回值将是一个单序列或序列列表。

cursor(snowflake.connector.DictCursor)

目的:

用于创建 DictCursor 对象的构造函数。来自 fetch*() 调用的返回值将是单一字典或字典对象列表。这对于从结果中按列名提取值非常有用。

execute_string(sql_text, remove_comments=False, return_cursors=True)¶

目的:

执行作为字符串传递的一个或多个 SQL 语句。如果将 remove_comments 设置为 True，则从查询中移除注释。如果将 return_cursors 设置为 True，则此方法按执行顺序返回一系列 Cursor 对象。

示例:

此示例展示了如何在单个字符串中执行多个命令，然后使用返回的游标序列：

cursor_list = connection1.execute_string(
    "SELECT * FROM testtable WHERE col1 LIKE 'T%';"
    "SELECT * FROM testtable WHERE col2 LIKE 'A%';"
    )

for cursor in cursor_list:
   for row in cursor:
      print(row[0], row[1])

Copy

备注

允许在单个字符串中使用多个 SQL 语句的方法（例如 execute_string() ）容易受到 SQL 注入攻击。 避免使用字符串串联或函数（如 Python 的 format() 函数），通过把 SQL 与来自用户的数据相组合，来动态撰写 SQL 语句，除非您已验证用户数据。下面的示例演示了该问题：

# "Binding" data via the format() function (UNSAFE EXAMPLE)
value1_from_user = "'ok3'); DELETE FROM testtable WHERE col1 = 'ok1'; select pi("
sql_cmd = "insert into testtable(col1) values('ok1'); "                  \
          "insert into testtable(col1) values('ok2'); "                  \
          "insert into testtable(col1) values({col1});".format(col1=value1_from_user)
# Show what SQL Injection can do to a composed statement.
print(sql_cmd)

connection1.execute_string(sql_cmd)

Copy

动态组合语句如下所示（为便于阅读，已添加换行符）：

insert into testtable(col1) values('ok1');
insert into testtable(col1) values('ok2');
insert into testtable(col1) values('ok3');
DELETE FROM testtable WHERE col1 = 'ok1';
select pi();

Copy

如果将 SQL 语句与不受信任的用户输入的字符串相组合，则将数据绑定到语句比编写字符串更安全。此 execute_string() 方法不采用绑定参数，因此要绑定参数，请使用 Cursor.execute() 或 Cursor.executemany()。

execute_stream(sql_stream, remove_comments=False)¶

目的:

执行作为流对象传递的一个或多个 SQL 语句。如果将 remove_comments 设置为 True，则从查询中移除注释。此生成器在 SQL 语句运行时生成每个 Cursor 对象。

如果 sql_stream 以注释行结束，则必须将 remove_comments 设置为 True，类似于下面的设置：

sql_script = """
-- This is first comment line;
select 1;
select 2;
-- This is comment in middle;
-- With some extra comment lines;
select 3;
-- This is the end with last line comment;
"""
sql_stream = StringIO(sql_script)
with con.cursor() as cur:
        for result_cursor in con.execute_stream(sql_stream,remove_comments=True):
            for result in result_cursor:
                print(f"Result: {result}")

Copy

get_query_status(query_id)¶

目的:

返回查询的状态。

参数:

query_id

查询的 ID。请参阅 检索 Snowflake 查询 ID。

返回:

返回表示查询状态的 QueryStatus 对象。

示例:

请参阅 检查查询的状态。

get_query_status_throw_if_error(query_id)¶

目的:

返回查询的状态。如果查询导致错误，此方法将引发 ProgrammingError`（就像 :py:meth:`execute 方法一样）。

参数:

query_id

查询的 ID。请参阅 检索 Snowflake 查询 ID。

返回:

返回表示查询状态的 QueryStatus 对象。

示例:

请参阅 检查查询的状态。

is_valid()¶

目的:

如果连接稳定到足以接收查询，则返回 True。

is_still_running(query_status)¶

目的:

如果查询状态指示查询尚未完成或仍在进行中，则返回 True。

参数:

query_status

表示查询状态的 QueryStatus 对象。若要获取此查询对象，请参阅 检查查询的状态。

示例:

请参阅 检查查询的状态。

is_an_error(query_status)¶

目的:

如果查询状态指示查询导致错误，则返回 True。

参数:

query_status

表示查询状态的 QueryStatus 对象。若要获取此查询对象，请参阅 检查查询的状态。

示例:

请参阅 检查查询的状态。

属性¶

expired¶

跟踪连接的主令牌是否已过期。

messages¶

列表对象，包括从基础数据库接收的用于此连接的所有消息的序列（异常类、异常值）。

任何方法调用都会自动清除此列表。

errorhandler¶

读/写属性，该属性在满足错误条件时引用要调用的错误处理程序。

此处理程序必须是接受以下实参的 Python 可调用处理程序：

errorhandler(connection, cursor, errorclass, errorvalue)

Error, Warning, ...

Python 数据库 API 标准定义的所有异常类。

方法¶

close()

目的:

关闭游标对象。

describe(command [, parameters][, timeout][, file_stream])¶

目的:

返回有关结果集的元数据，而不 执行数据库命令。这将返回执行查询后在 description 属性中可用的相同元数据。

在 Snowflake Connector for Python 的 2.4.6 版本中引入此方法。

参数:

请参阅 execute() 方法的参数。

返回:

返回描述结果集中的列的 ResultMetadata 对象列表。

示例:

请参阅 检索列元数据。

execute(command [, parameters][, timeout][, file_stream])¶

目的:

准备并执行数据库命令。

参数:

command

包含要执行的 SQL 语句的字符串。

parameters

（可选）如果在 SQL 语句中使用 绑定数据 的参数，请将其设置为应绑定到这些参数的变量列表或字典。

有关将变量的 Python 数据类型映射到相应列的 SQL 数据类型的更多信息，请参阅 qmark 和 numeric 绑定的数据类型映射。

timeout

（可选）等待查询完成的秒数。如果在此时间过后查询仍未完成，则应中止查询。

file_stream

（可选）执行 PUT 命令时，可以使用此参数上传内存中类似文件的对象（例如，从 Python open() 函数返回的 I/O 对象），而不是文件系统上的文件。将此参数设置为该 I/O 对象。

为 PUT 命令中的数据文件指定 URI 时：

• 您可以使用任何目录路径。您在 URI 中指定的目录路径将被忽略。

• 对于文件名，指定应在暂存区上创建的文件的名称。

例如，要将文件从文件流上传到名为以下项的文件：

@mystage/myfile.csv

Copy

使用以下调用：

cursor.execute(
    "PUT file://this_directory_path/is_ignored/myfile.csv @mystage",
    file_stream=<io_object>)

Copy

返回:

返回 Cursor 对象的引用。

executemany(command, seq_of_parameters)¶

目的:

准备一个数据库命令，并针对 seq_of_parameters 中找到的所有参数序列执行该命令。您可以使用此方法 执行批量插入操作。

参数:

command

该命令是包含要执行的代码的字符串。字符串应包含 绑定数据 的一个或多个占位符（如问号）。

例如：

"insert into testy (v1, v2) values (?, ?)"

Copy

seq_of_parameters

这应该是列表或元组的序列（列表或元组）。有关示例序列，请参阅下面的示例代码。

返回:

返回 Cursor 对象的引用。

示例:

# This example uses qmark (question mark) binding, so
# you must configure the connector to use this binding style.
from snowflake import connector
connector.paramstyle='qmark'

stmt1 = "create table testy (V1 varchar, V2 varchar)"
cs.execute(stmt1)

# A list of lists
sequence_of_parameters1 = [ ['Smith', 'Ann'], ['Jones', 'Ed'] ]
# A tuple of tuples
sequence_of_parameters2 = ( ('Cho', 'Kim'), ('Cooper', 'Pat') )

stmt2 = "insert into testy (v1, v2) values (?, ?)"
cs.executemany(stmt2, sequence_of_parameters1)
cs.executemany(stmt2, sequence_of_parameters2)

Copy

在内部，调用多个 execute 方法，并保留上次 execute 调用的结果集。

备注

executemany 方法只能用于执行单个参数化 SQL 语句并向其传递多个绑定值。

不支持在一次 execute 调用中执行以分号分隔的多个 SQL 语句。相反，请为每个语句发出单独的 execute 调用。

execute_async(...)¶

目的:

准备并提交用于异步执行的数据库命令。请参阅 执行异步查询。

参数:

此方法使用与 execute() 方法相同的参数。

返回:

返回 Cursor 对象的引用。

示例:

请参阅 异步查询示例。

fetch_arrow_all()¶

目的:

此方法提取游标中的所有行并将它们加载到 PyArrow 表。

参数:

无。

返回:

返回一个 PyArrow 表，它包含结果集中所有行。

如果没有行，则返回 None。

示例:

请参阅 使用 Snowflake Connector for Python 分发提取结果的工作负载。

fetch_arrow_batches()¶

目的:

此方法提取游标中行的子集，并将它们传递给 PyArrow 表。

参数:

无。

返回:

返回一个 PyArrow 表，它包含结果集中行的子集。

如果没有更多要提取的行，则返回 None。

示例:

请参阅 使用 Snowflake Connector for Python 分发提取结果的工作负载。

get_result_batches()¶

目的:

返回 ResultBatch 对象的列表，该对象可用于从结果集中提取行的子集。

参数:

无。

返回:

如果查询尚未完成执行，则返回 ResultBatch 对象列表或者 None。

示例:

请参阅 使用 Snowflake Connector for Python 分发提取结果的工作负载。

get_results_from_sfqid(query_id)¶

目的:

检索异步查询或之前提交的同步查询的结果。

参数:

query_id

查询的 ID。请参阅 检索 Snowflake 查询 ID。

示例:

请参阅 使用查询 ID 检索查询结果。

fetchone()¶

目的:

当没有更多可用数据时，提取查询结果集的下一行，并返回单个序列/字典或 None。

fetchmany([size=cursor.arraysize])¶

目的:

提取查询结果集的下一行，并返回序列/字典的列表。当没有更多可用行时，将返回空序列。

fetchall()¶

目的:

提取查询结果集的全部行或剩余行，并返回序列/字典的列表。

fetch_pandas_all()¶

目的:

此方法提取游标中的所有行并将它们加载到 pandas DataFrame 中。

参数:

无。

返回:

返回包含结果集中的所有行的 DataFrame。

如果没有行，这会返回 None。

使用说明:

• 此方法不能完全取代 pandas 的 read_sql() 方法；此方法提供一种从 SELECT 查询中检索数据并将数据存储在 pandas DataFrame 中的快速方法。

• 目前，此方法仅适用于 SELECT 语句。

示例:

ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the pandas DataFrame.
df = cur.fetch_pandas_all()

# ...

Copy

fetch_pandas_batches()¶

目的:

此方法提取游标中行的子集，并将它们传递给 pandas DataFrame。

参数:

无。

返回:

返回一个 DataFrame，它包含结果集中行的子集。

如果没有更多行可提取，则返回 None。

使用说明:

• 根据结果集中的行数以及方法调用中指定的行数，可能需要多次调用该方法，或者如果所有行都适合，则可能需要返回单个批处理中的所有行。

• 此方法不能完全取代 pandas 的 read_sql() 方法；此方法提供一种从 SELECT 查询中检索数据并将数据存储在 pandas DataFrame 中的快速方法。

• 目前，此方法仅适用于 SELECT 语句。

示例:

ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the pandas DataFrame.
for df in cur.fetch_pandas_batches():
    my_dataframe_processing_function(df)

# ...

Copy

__iter__()¶

返回 Self 以使游标与迭代协议兼容。

属性¶

description¶

只读属性，返回有关结果集中列的元数据。

此属性是在调用 execute() 方法执行查询后设置的。（在 2.4.6 版本或更高版本中，可以通过调用 describe() 方法在不执行查询的情况下检索此元数据。）

此属性设置为下列属性之一：

• 2.4.5 版本及更早版本： 此属性设置为元组列表。

• 2.4.6 版本及更高版本： 此属性设置为 ResultMetadata 对象的列表。

每个元组或 ResultMetadata 对象都包含描述结果集中的列的元数据。您可以按索引访问元数据，或者在 2.4.6 版本及更高版本中，按 ResultMetadata 对象属性访问元数据：

价值指数	ResultMetadata 属性	描述
0	name	列名称。
1	type_code	内部 类型代码。
2	display_size	（未使用。与 internal_size 相同。）
3	internal_size	内部数据大小。
4	precision	数值数据的精度。
5	scale	数值数据的小数位数。
6	is_nullable	如果列或 False 允许 NULL 值，则为 True。

有关获取此属性的示例，请参阅 检索列元数据。

rowcount¶

只读属性，返回上次 execute 生成的行数。如果未执行 execute，则该值为 -1 或 None。

sfqid¶

只读属性，返回上次 execute 或 execute_async 执行中的 Snowflake 查询 ID。

arraysize¶

读/写属性，指定使用 fetchmany() 一次提取的行数。默认为 1，它意味着一次提取一行。

connection¶

只读属性，返回对在其上创建游标的 Connection 对象的引用。

messages

列表对象，包含从游标的基础数据库接收的所有消息的序列（异常类、异常值）。

除 fetch*() 调用外，任何方法调用都会自动清除该列表。

errorhandler

读/写属性，该属性在满足错误条件时引用要调用的错误处理程序。

此处理程序必须是接受以下实参的 Python 可调用处理程序：

errorhandler(connection, cursor, errorclass, errorvalue)

类型代码¶

在 Cursor 对象中，description 属性和 describe() 方法提供描述结果集中列的元组（或 2.4.6 版本及更高版本中的 ResultMetadata 对象）列表。

在元组中，索引 1 的值（ResultMetadata 对象中的 type_code 属性）表示列数据类型。Snowflake Connector for Python 使用以下映射根据类型代码获取字符串的表示形式：

qmark 和 numeric 绑定的数据类型映射¶

如果 paramstyle 为 "qmark" 或 "numeric"，则使用以下从 Python 到 Snowflake 数据类型的默认映射：

如果需要映射到另一个 Snowflake 类型（例如从 datetime 到 TIMESTAMP_LTZ），请在元组中指定 Snowflake 数据类型，该元组由值前面的 Snowflake 数据类型组成。有关示例，请参阅 :ref:` 绑定日期时间 TIMESTAMP <label-python_connector_binding_timestmamp_qmark>`。

方法¶

没有可用于 Exception 对象的方法。

属性¶

errno¶

Snowflake DB 错误代码。

msg¶

错误消息包括错误代码、SQL 状态代码和查询 ID。

raw_msg¶

错误消息。不包含错误代码、SQL 状态代码或查询 ID。

sqlstate¶

符合 ANSI 的 SQL 状态代码

sfqid

Snowflake 查询 ID。

属性¶

方法¶

to_arrow()¶

目的:

此方法返回一个 PyArrow 表，它包含 ResultBatch 对象中的行。

参数:

无。

返回:

返回一个 PyArrow 表，它包含来自 ResultBatch 对象中的行。

如果没有行，则返回 None。

to_pandas()¶

目的:

此方法返回一个 pandas DataFrame，它包含 ResultBatch 对象中的行。

参数:

无。

返回:

返回一个 pandas DataFrame，它包含 ResultBatch 对象中的行。

如果没有行，则返回一个空的 pandas DataFrame。

方法¶

无。

属性¶

name¶

列的名称

type_code¶

内部 类型代码。

display_size¶

未使用。与 internal_size 相同。

internal_size¶

内部数据大小。

precision¶

数值数据的精度。

scale¶

数值数据的小数位数。

is_nullable¶

如果列或 False 允许 NULL 值，则为 True。

枚举¶

class QueryStatus¶

表示异步查询的状态。此枚举具有以下常量：

枚举常量	描述
RUNNING	查询仍在运行。
ABORTING	查询正在服务器端中止。
SUCCESS	查询已成功完成。
FAILED_WITH_ERROR	查询未成功完成。
QUEUED	查询排队等待执行（即尚未开始运行），通常是因为它正在等待资源。
DISCONNECTED	会话的连接已断开。查询的状态将很快更改为“FAILED_WITH_ERROR”。
RESUMING_WAREHOUSE	仓库正在启动，但查询尚未运行。
BLOCKED	该语句正在等待另一个语句所持有的锁。
NO_DATA	有关语句的数据尚不可用，通常是因为语句尚未开始执行。

函数¶

write_pandas(parameters...)¶

目的:

将 pandas DataFrame 写入 Snowflake 数据库中的表。

若要将数据写入表，该函数将数据保存到 Parquet 文件，使用 PUT 命令将这些文件上传到临时暂存区，然后使用命令 COPY INTO <table> 将数据从文件复制到表中。您可以使用一些函数参数来控制 PUT 和 COPY INTO <table> 语句的执行方式。

参数:

有效的输入参数为：

参数	必填	描述
conn	是	Connection 对象，用于保持与 Snowflake 数据库的连接。
df	是	pandas.DataFrame 对象，包含要复制到表中的数据。
table_name	是	应将数据复制到其中的表的名称。
database		包含表的数据库名称。默认情况下，该函数将写入在会话中正在使用的数据库。注意：如果指定此参数，则还必须指定该 schema 参数。
schema		包含表的架构名称。默认情况下，该函数写入架构中的表，该架构正在会话中使用。
bulk_upload_chunks		如果将此参数设置为 True，则会更改 write_pandas 函数的行为，即先将所有数据块写入到本地磁盘，然后将数据块文件夹以通配符的形式上传至暂存区。当设置为 :codenowrap:`False`（默认）时，数据块将逐一保存、上传和删除。
chunk_size		一次要插入的元素数量。默认情况下，该函数将所有元素一次插入到一个块中。
compression		用于 Parquet 文件的压缩算法。您可以指定 "gzip" 以压缩得更好，或指定 "snappy" 以压缩得更快。默认情况下，该函数使用 "gzip"。
on_error		指定应如何处理错误。将其设置为 ON_ERROR :ref:` 复制选项 <label-copy_into_table_copyoptions>` 中记录的字符串值之一。默认情况下，该函数使用 "ABORT_STATEMENT"。
parallel		将 Parquet 文件上传到临时暂存区时要使用的线程数。有关使用的默认线程数和选择线程数的准则，请参阅 :ref:` PUT 命令的 parallel 参数<label-put_parameter_parallel>`。
quote_identifiers		若为 False，则阻止连接器在将标识符发送到服务器之前 在标识符周围加上双引号。默认情况下，连接器在标识符两边加上双引号。

返回:

返回 (success, num_chunks, num_rows, output) 的元组，其中：

• 如果函数成功将数据写入表，则 success 为 True。

• num_chunks 是函数复制的数据块数。

• num_rows 是函数插入的行数。

• output 是 COPY INTO <table> 命令的输出。

示例:

以下示例将 pandas DataFrame 中的数据写入名为“customers”的表。

import pandas
from snowflake.connector.pandas_tools import write_pandas

# Create the connection to the Snowflake database.
cnx = snowflake.connector.connect(...)

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Write the data from the DataFrame to the table named "customers".
success, nchunks, nrows, _ = write_pandas(cnx, df, 'customers')

Copy

pd_writer(parameters...)¶

目的:

pd_writer 是一种插入方法，用于将数据插入 Snowflake 数据库。

在调用 pandas.DataFrame.to_sql 时，传入 method=pd_writer，以指定您希望将 pd_writer 用作插入数据的方法。（您不需要从自己的代码调用 pd_writer。此 to_sql 方法调用 pd_writer 并提供所需的输入参数。）

备注

请注意，当 pandas DataFrame 中的列名仅包含小写字母时，必须将列名放在双引号内；否则连接器会引发 ProgrammingError。

创建表时，snowflake-sqlalchemy 库对小写的列名不加引号，而 pd_writer 在默认情况下对列名加引号。出现此问题的原因是因为 COPY INTO 命令，列名用加引号除外。

今后将对 snowflake-sqlalchemy 库进行改进。

例如：

import pandas as pd
from snowflake.connector.pandas_tools import pd_writer

sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['NAME', 'NEWEST_VERSION'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "driver_versions"
# in the Snowflake database.
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)

# When the column names consist of only lower case letters, quote the column names
sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['"name"', '"newest_version"'])
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)

Copy

此 pd_writer 函数使用 write_pandas() 函数将 DataFrame 中的数据写入 Snowflake 数据库。

参数:

有效的输入参数为：

参数	必填	描述
table	是	表的 pandas.io.sql.SQLTable 对象。
conn	是	sqlalchemy.engine.Engine 或 sqlalchemy.engine.Connection 对象，用于连接 Snowflake 数据库。
keys	是	要插入数据的表列的名称。
data_iter	是	迭代器，包含要插入的数据的行。

示例:

下面的示例将 method=pd_writer 传递给 pandas.DataFrame.to_sql 方法，该方法又调用 pd_writer 函数，将 pandas DataFrame 中的数据写入 Snowflake 数据库。

import pandas
from snowflake.connector.pandas_tools import pd_writer

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "customers"
# in the Snowflake database.
df.to_sql('customers', engine, index=False, method=pd_writer)

Copy

提取数据¶

提取日期和时间数据时，Snowflake 数据类型将转换为 Python 数据类型：

更新数据¶

更新日期和时间数据时，Python 数据类型将转换为 Snowflake 数据类型：