2023 年 Snowpark Python 库版本说明¶

向 SnowflakeSQLException 添加了 conn_error 属性，该属性存储来自 snowflake-connector-python 的整个底层异常。

添加了对 RelationalGroupedDataframe.pivot() 的支持，可在以下模式 Dataframe.group_by(...).pivot(...) 中访问 pivot。

添加了实验功能 Local Testing Mode，允许您在本地创建和操作 Snowpark Python DataFrames，无需连接到 Snowflake 账户。您可以使用此本地测试框架在开发机器或 CI（持续集成）管道中，本地测试您的 DataFrame 操作，然后再将代码变更部署到账户。

添加了对 snowflake.snowpark.functions 中 arrays_to_object 新函数的支持：

添加了对向量数据类型的支持。

升级了 cloudpickle 依赖项，以兼容 cloudpickle==2.2.1。

将 snowflake-connector-python 更新到了版本 3.4.0。

DataFrame 列名引用检查现在支持换行字符。

修复了在执行 df.write.save_as_table 时 session.read.with_metadata 生成的 DataFrame 会创建不一致表的错误。

在 DataFrame.to_local_iterator() 中添加了对大小写敏感性管理的支持。

通过在 UDTFRegistration.register、UDTFRegistration.register_file 和 functions.pandas_udtf 中使用可选参数 input_names，添加了对指定矢量化 UDTF 输入列名称的支持。默认情况下， RelationalGroupedDataFrame.applyInPandas 将根据当前 DataFrame 架构推断列名称。

为由 SQL 异常引起的 SnowflakeSQLException 添加了 sql_error_code 和 raw_message 属性。

修复了 DataFrame.to_pandas() 中的一个错误，该错误会导致将 Snowpark DataFrames 转换为 Pandas DataFrames 时，超过 19 位的整数失去精度。

修复了 session.add_packages 中的一个错误，该错误会导致无法处理包含带有下划线和版本项目名称的需求说明符。

修复了使用 offset 且父 DataFrame 使用 limit 时， DataFrame.limit() 中的一个错误。offset 现在不会影响父 DataFrame 的 limit。

修复了 DataFrame.write.save_as_table 中的一个错误，该错误会导致通过读取 API 创建的 DataFrames 无法将数据保存到 Snowflake 中，原因是 $1 列名无效。

更改了 date_format 的行为：

• format 实参从可选更改为必填。

• 返回的结果从日期对象更改为日期格式字符串。

使用窗口函数或序列相关数据生成器（normal、zipf、uniform、seq1、seq2、seq4、seq8）函数时，生成查询时将不再对排序和筛选操作进行展平处理。

添加了对 Python 3.11 运行时环境的支持。

为 ARRAY 和 OBJECT 字面量支持 PythonObjJSONEncoder JSON 可序列化对象。

重新添加了 typing-extensions 的依赖项。

修复了一个错误，即对于临时存储过程、UDTFs、UDFs 和 UDAFs，从永久暂存区位置进行的导入会被忽略。

DataFrameWriter.save_as_table 恢复为使用 CTAS (CREATE TABLE AS SELECT) 语句，该语句在写入表时不需要插入权限。

添加了在注册 UDFs 时对 VOLATILE 和 IMMUTABLE 关键字的支持。

添加了使用 DataFrame.save_as_table 保存 DataFrame 时，对指定群集密钥的支持。

使用 Session.create_dataframe 创建 DataFrame 时，接受 schema 的 Iterable 对象输入。

添加了 DataFrame.session 属性以返回 Session 对象。

添加了 Session.session_id 属性以返回表示会话 ID 的整数。

添加了 Session.connection 属性以返回 SnowflakeConnection 对象。

添加了对从配置文件或环境变量创建 Snowpark 会话的支持。

snowflake-connector-python 已更新到 3.2.0。

修复了一个错误，即使在 session.add_packages 中添加了兼容的包版本，自动包上传也会引发 ValueError。

修复了导致在使用 register_from_file 时正确注册表存储过程的错误。

修复了 DataFrame 联接失败时出现 invalid_identifier 的错误。

修复了 DataFrame.copy 在返回副本时禁用 SQL 简化器的错误。

修复了如果为 session.sql() 指定任何参数， session.sql().select() 将会失败的错误。

在使用参数 is_permanent=False 创建存储过程、UDFs、UDTFs 和 UDAFs 时，即使提供了 stage_name，也会创建临时对象。is_permanent 的默认值为 False，因此如果不明确地将永久对象的该值设置为 True，用户就会发现行为发生了变化。

types.StructField 现在默认引用列标识符。

添加了 external_access_integrations 和 secrets 参数，可在从 Snowpark Python 创建 UDF、UDTF 或存储过程时使用，以便与外部访问集成。

在 snowflake.snowpark.functions 中添加了对以下新函数的支持： array_flatten 和 flatten。

在 snowflake.snowpark.relational_grouped_dataframe 中添加了对 apply_in_pandas 的支持。

添加了通过 Session.replicate_local_environment 在Snowflake 上复制本地 Python 环境的支持。

修复了在无效性受顺序影响或已给出数据时， session.create_dataframe 无法正确设置可为 null 的列的错误。

修复了在使用表格函数时，当表格函数的输出列与 DataFrame 中的列重叠时， DataFrame.select 无法识别和别名列的错误。

对于用户提供的架构，或根据用户输入的数据推断的架构，DataFrameWriter.save_as_table 现在支持可为 null 的字段。

添加了对 snowflake.snowpark.functions 中新函数的支持：

• array_sort

• sort_array

• array_min

• array_max

• explode_outer

添加了对通过 Session.add_requirements 或 Session.add_packages 指定的纯 Python 包的支持。现在，即使 Snowflake Anaconda 通道上不存在包，它们也可以在存储过程和 UDFs 中使用。

添加了会话参数 custom_packages_upload_enabled 和 custom_packages_force_upload_enabled，以启用上述纯 Python 软件包支持功能。这两个参数默认都为 False。

通过将 conda 环境 YAML 文件传递给 Session.add_requirements，添加了对指定包要求的支持。

添加了对包含绑定变量的多查询 DataFrame 的异步执行的支持。

添加了对重命名 DataFrame.rename 中多个列的支持。

添加了对几何图形数据类型的支持。

添加了对存储过程中 session.sql() 内的参数的支持。

添加了对用户定义聚合函数 (UDAFs) 的支持。此功能目前处于非公开预览阶段。

添加了对矢量化用户定义表函数（矢量化 UDTFs）的支持。此功能目前处于公开预览阶段。

添加了对 Snowflake 时间戳变体（即 TIMESTAMP_NTZ、TIMESTAMP_LTZ、TIMESTAMP_TZ）的支持：

• 在 TimestampType 构造函数中添加 TimestampTimezone 为实参。

• 添加了类型提示：NTZ、LTZ、TZ 和时间戳，用于在注册 UDFs 时对函数进行注释。

移除了冗余的依赖项类型扩展。

现在，DataFrame.cache_result 会在当前数据库和架构下创建完全限定名称的临时表。

修复了在导入 pandas 之前对 pandas 进行类型检查的错误。

修复了从 numpy.ufunc 创建 UDF 时的一个错误。

修复了启用 SQL 简化器时， DataFrame.union 无法生成正确 Selectable.schema_query 的错误。

snowflake-connector-python 已更新至版本 3.0.4。

添加了对 Python 3.10 运行时环境的支持。

DataFrame.agg 和 DataFrame.describe 等函数的聚合结果不再从列名中剥离非打印字符。

添加了对 Python 3.9 运行时环境的支持。

添加了对 snowflake.snowpark.functions 中新函数的支持：

array_generate_range

array_unique_agg

collect_set

sequence

添加了对使用 TABLE 返回类型注册和调用存储过程的支持。

添加了对 StringType() 中参数长度的支持，以便指定列可以存储的最大字符数。

为 functions.get() 添加了别名 functions.element_at()。

为 functions.contains 添加了别名 Column.contains。

添加了实验功能 DataFrame.alias。

添加了对使用 DataFrameReader 创建 DataFrame 时从暂存区查询元数据列的支持。

添加了对 StructType.add 的支持，以便在现有 StructType 对象中追加更多字段。

添加了对 StoredProcedureRegistration.register_from_file() 中参数 execute_as 的支持，以便指定存储过程调用者权限。

修复了在启用 Dataframe.join_table_function 简化器时， SQL 无法运行所有必要查询来设置联接表函数的错误。

修复了自定义类型的类型提示声明：会中断 mypy 检查的 ColumnOrName、ColumnOrLiteralStr、ColumnOrSqlExpr、LiteralType 和 ColumnOrLiteral。

修复了 DataFrame.copy_into_table 和 DataFrameWriter.save_as_table 无法解析完全限定表名的错误。

添加了对 session.getOrCreate 的支持。

添加了对别名 Column.getField 的支持。

添加了对 snowflake.snowpark.functions 中新函数的支持：

• date_add 和 date_sub 让使加减运算变得更简单。

• ddaydiff

• dexplode

• darray_distinct

• dregexp_extract

• dstruct

• dformat_number

• dbround

• dsubstring_index

在使用 register_from_file 创建 UDFs、UDTFs 和存储过程时，添加了参数 skip_upload_on_content_match，用于在暂存区中已有相同版本的文件时，跳过将文件上传到暂存区。

添加了 DataFrame.save_as_table 方法的支持，以获取包含点的表名。

当 DataFrame.filter() 或 DataFrame.order_by() 后跟投影语句（例如 DataFrame.select()、DataFrame.with_column()）时，生成的 SQL 将变得扁平化。

添加了对使用 Dataframe.create_or_replace_dynamic_table 创建动态表（专用预览版）的支持。

在 session.sql() 中添加了可选实参 params，以支持绑定变量。请注意，存储过程中尚不支持此实参。

修复了 strtok_to_array 中在传入分隔符时会产生异常的错误。

修复了 session.add_import 中可导致模块与其他依赖项使用相同命名空间的错误。

添加了 functions.initcap() 中分隔符参数的支持。

添加了对 functions.hash() 接受变量数输入表达式的支持。

添加了 API Session.conf，用于获取、设置或检查任何运行时配置的可变性。

添加了对使用 case_sensitive 参数管理来自 DataFrame.collect 的 Row 结果的大小写敏感性的支持。

为 snowflake.snowpark.types.StructType 添加了索引器支持。

为 Dataframe.collect 和 Dataframe.collect_no_wait 添加了关键字实参 log_on_exception，可以选择性地禁用 SQL 异常的错误日志记录。

修复了在调用另一个 DataFrame 设置操作和 DataFrame.select 或 DataFrame.with_column 之后，调用 DataFrame 操作（DataFrame.subtract、DataFrame.union 等）会引发异常的错误。

修复了链式排序语句被 SQL 简化器覆盖的错误。

简化了 JOIN 查询，默认情况下使用常量子查询别名（SNOWPARK_LEFT、SNOWPARK_RIGHT）。用户可以在运行时使用 session.conf.set('use_constant_subquery_alias', False) 禁用此功能，改用随机生成的别名。

允许在 session.call() 中指定语句参数。

在存储过程中启用上传大型 pandas DataFrames 的功能，默认块大小为 100,000 行。

添加了对在注册存储过程时在生成的脚本中以注释形式显示源代码的支持。默认情况下，此功能处于启用状态，可在注册时指定 source_code_display=False 将其关闭。

在从 Snowpark Python 创建 UDF、UDTF 或存储过程时添加了参数 if_not_exists，以在指定函数或过程已存在的情况下忽略创建该函数或过程。

调用 snowflake.snowpark.functions.get 从数组中提取值时接受整数。

在函数中添加了 functions.reverse，以开放对 Snowflake 内置函数 REVERSE 的访问。

在 snowflake.snowflake.files.SnowflakeFile.open() （专用预览版中）中添加了参数 require_scoped_url，以取代已标记弃用的 is_owner_file。

修复了在创建 Snowpark 会话时将 paramstyle 重写为 qmark 的错误。

修复了 df.join(..., how="cross") 失败并出现 SnowparkJoinException: (1112): Unsupported using join type 'Cross' 的错误。

修复了查询通过链式函数调用创建的 DataFrame 列时使用错误列名的错误。

添加了 asc、asc_nulls_first、asc_nulls_last、desc、desc_nulls_first、desc_nulls_last、date_part 和 unix_timestamp 函数。

添加 DataFrame.dtypes 属性，用于返回列名和数据类型对的列表。

添加了以下别名：

• functions.expr() for functions.sql_expr()。

• functions.date_format() for functions.to_date()。

• functions.monotonically_increasing_id() for functions.seq8()。

• functions.from_unixtime() for functions.to_timestamp()。

修复了 SQL 简化器中在某些情况下无法很好地处理列别名和连接的错误。有关详细信息，请参阅 https://github.com/snowflakedb/snowpark-python/issues/658 (https://github.com/snowflakedb/snowpark-python/issues/658)。

修复了 SQL 简化器中为函数调用、NaN 和 INF 生成错误列名的错误。

Snowflake 7.3 发布后，会话参数 PYTHON_SNOWPARK_USE_SQL_SIMPLIFIER 将变为 True。在 snowpark-python 中，session.sql_simplifier_enabled 默认读取 PYTHON_SNOWPARK_USE_SQL_SIMPLIFIER 的值，这意味着在 Snowflake 7.3 版本发布后，SQL 简化器将默认启用。要关闭此功能，请将 Snowflake 中的 PYTHON_SNOWPARK_USE_SQL_SIMPLIFIER 设置为 False，或从 Snowpark 运行 session.sql_simplifier_enabled = False。建议使用 SQL 简化器，因为它有助于生成更简洁的 SQL。