2022 年 Snowpark Python 库版本说明¶

新功能¶

• 添加了 Session.generator() 以使用 GENERATOR 表函数创建新的 DataFrame。

• 在创建安全 UDF 或 UDTF 的函数中添加了 SECURE 参数。

新功能¶

• 为异步作业添加了新的 APIs ：

  • Session.create_async_job() 从查询 ID 创建 AsyncJob 实例。

  • AsyncJob.result() 现在接受实参 result_type 以不同格式返回结果。

  • AsyncJob.to_df() 返回根据此异步作业的结果构建的 DataFrame。

  • AsyncJob.query() 返回已执行查询的 SQL 文本。

• DataFrame.agg() 和 RelationalGroupedDataFrame.agg() 现在接受可变长度实参。

• 在 DataFrame.join() 和 DataFrame.cross_join() 中添加了参数 lsuffix 和 rsuffix，以方便地重命名重叠的列。

• 添加了 Table.drop_table()，以便您可以在调用 DataFrame.cache_result() 后弃用临时表。Table 也是一个上下文管理器，因此您可以使用 with 语句在使用后弃用缓存临时表。

• 添加了 Session.use_secondary_roles()。

• 添加了函数 first_value() 和 last_value()。（贡献者：@chasleslr）

• 在 DataFrame.join() 中添加了 on 作为 using_columns 的别名，添加了 how 作为 join_type 的别名。

错误修复¶

• 修复了 Session.create_dataframe() 中的一个错误，该错误会在架构名称包含特殊字符时引发错误。

• 修复了在 Session.read.option() 中设置的选项未作为默认值传递给 DataFrame.copy_into_table() 的错误。

• 修复了当复制选项的值中有单引号时 DataFrame.copy_into_table() 会引发错误的错误。

行为变更¶

• Session.add_packages() 现在会在 Snowflake Anaconda 通道中找不到软件包版本时引发 ValueError。以前， Session.add_packages() 会成功完成，但在 UDF 或存储过程注册步骤中会引发 SnowparkSQLException 异常。

新功能¶

• 添加了 FileOperation.get_stream() 方法以支持将暂存文件作为流下载。

• 在 functions.ntiles() 中添加了对接受 int 实参的支持。

• 添加了以下别名：

  • functions.call_function() 用于 functions.call_builtin()。

  • functions.function() 用于 functions.builtin()。

  • DataFrame.order_by() 用于 DataFrame.sort()。

  • DataFrame.orderBy() 用于 DataFrame.sort()。

• 改进了 DataFrame.cache_result() 以返回更准确的 Table 类，而不是 DataFrame 类。

• 添加了在调用 StoredProcedure 时允许将 session 作为第一个实参的支持。

改进¶

• 通过在适用时片展平查询来改进嵌套查询的生成。通过设置 Session.sql_simplifier_enabled = True 可以实现这一改进。DataFrame.select()、DataFrame.with_column()、DataFrame.drop() 和其他与 select 相关的 APIs 现在具有更展平的 SQL。DataFrame.union()、DataFrame.union_all()、DataFrame.except_()、DataFrame.intersect() 和 DataFrame.union_by_name() 具有多个集合运算符链接时生成的展平 SQL。

• 改进了异步作业 APIs 的类型注释。

错误修复¶

• 修复了 Table.update()、Table.delete() 和 Table.merge() 试图引用不存在的临时表的错误。

新功能¶

• 添加了使用异步查询评估 Snowpark 数据帧的实验 APIs ：

  • 在 Snowpark 数据帧（执行查询）的以下操作 APIs 中添加了关键字实参块，以允许异步评估：

    • DataFrame.collect()、DataFrame.to_local_iterator()、DataFrame.to_pandas()、DataFrame.to_pandas_batches()、DataFrame.count()、DataFrame.first()、DataFrameWriter.save_as_table()、DataFrameWriter.copy_into_location()、Table.delete()、Table.update() 和 Table.merge()。

  • 添加了 DataFrame.collect_nowait() 方法以允许异步计算。

  • 添加了 AsyncJob 类以从异步执行的查询中检索结果并检查其状态。

• 在 Session.write_pandas() 中添加了对 table_type 的支持。您现在可以从以下 table_type 选项中进行选择：temporary、temp 和 transient。

• 添加了在 Snowpark 中使用 Python 结构化数据（list、tuple 和 dict）作为文字值的支持。

• 向 functions.sproc() 和 session.sproc.register() 添加了关键字实参 execute_as，以允许将存储过程注册为调用方或所有者。

• 添加了对在 Snowflake 中从暂存区读取文件时指定预配置文件格式的支持。

改进¶

• 添加了对显示 Snowpark 会话详细信息的支持。

错误修复¶

• 修复了 DataFrame.copy_into_table() 和 DataFrameWriter.save_as_table() 在表名完全限定且表已存在的情况下错误地创建新表的错误。

弃用¶

• Session.write_pandas() 中弃用的关键字实参 create_temp_table。

• 弃用使用封装在 Python 列表或元组中的实参调用 UDFs。可以使用不带列表或元组的可变长度实参。

依赖项更新¶

• 将 snowflake-connector-python 更新至 2.7.12。

新功能¶

• 添加了注册 UDFs 时在生成的脚本中将源代码显示为注释的支持。默认情况下，此功能处于打开状态。要将其关闭，请在调用 register() 或 @udf() 时将新的关键字实参 source_code_display 作为 False 传递。

• 添加了对从 DataFrame.select()、DataFrame.with_column() 和 DataFrame.with_columns() 调用表函数的支持，这些函数现在为列采用 table_function.TableFunctionCall 类型的参数。

• 向 session.write_pandas() 添加了关键字实参 overwrite，以允许您用 Pandas DataFrame 的内容覆盖 Snowflake 表的内容。

• 向 df.write.save_as_table() 添加了关键字实参 column_order，以指定在追加模式下向表中插入数据时的匹配规则。

• 添加了 FileOperation.put_stream() 方法以通过文件流将本地文件上传到暂存区。

• 添加了方法 TableFunctionCall.alias() 和 TableFunctionCall.as_()，以允许为来自表函数联接输出的列名设置别名。

• 在模块 snowflake.snowpark.context 中添加了函数 get_active_session() 以获取当前活动的 Snowpark 会话。

改进¶

改进了函数 function.uniform() 以推断输入 max_ 和 min_ 的类型，并将限制分别转换为 IntegerType 或 FloatType。

错误修复¶

• 修复了当 statement_params 未传递给函数时批量插入不应引发错误的错误。

• 修复了当使用 dicts 和给定架构调用 session.create_dataframe() 时应引用列名的错误。

• 修复了当调用 df.write.save_as_table() 时，如果表已经存在并处于追加模式，则应跳过表创建的错误。

• 修复了注册 UDFs 时无法添加带下划线的第三方包的错误。

新功能¶

• 向以下方法添加了仅关键字实参 statement_params，以允许指定语句级实参：

  • 类 snowflake.snowpark.Dateframe 上的 collect、to_local_iterator、to_pandas、to_pandas_batches、count、copy_into_table、show、create_or_replace_view、create_or_replace_temp_view、first、cache_result 和 random_split。

  • 类 snowflake.snowpark.Table 上的 update、delete 和 merge。

  • 类 snowflake.snowpark.DataFrameWriter 上的 save_as_table 和 copy_into_location。

  • 类 snowflake.snowpark.DataFrameStatFunctions 上的 approx_quantile、statement_params、cov 和 crosstab。

  • 类 snowflake.snowpark.udf.UDFRegistration 上的 register 和 register_from_file。

  • 类 snowflake.snowpark.udtf.UDTFRegistration 上的 register 和 register_from_file。

  • 类 snowflake.snowpark.stored_procedure.StoredProcedureRegistration 上的 register 和 register_from_file。

  • snowflake.snowpark.functions 中的 udf、udtf 和 sproc。

• 添加了对作为 Column 输入实参的 session.call() 的支持。

• 在 df.write.save_as_table() 中添加了对 table_type 的支持。您现在可以从以下 table_type 选项中进行选择：temporary、temp 和 transient。

改进¶

• 在 session.use_* 方法中添加了对象名验证。

• 更新了 SQL 中的 query 标签，以在包含特殊字符时对其进行转义。

• 添加了检查，以查看在添加缺少的包时是否确认了 Anaconda 术语。

错误修复¶

• 修复了 session.create_dataframe() 中字符串列的有限长度。

• 修复了当输入数据仅为列表时， session.create_dataframe() 错误地将 0 和 False 转换为 None 的错误。

• 修复了使用大型本地数据集调用 session.create_dataframe() 有时会创建临时表两次的错误。

• 将 function.trim() 的定义与 SQL 函数定义对齐。

• 修复了使用 Python 系统定义的（内置函数）sum 与 Snowpark function.sum() 时 snowpark-python 会挂起的问题。

新功能¶

• 添加了对用户定义表函数 (UDTFs) 的支持。

  • 使用函数 snowflake.snowpark.functions.udtf() 注册 UDTF，或将其用作装饰器来注册 UDTF。

  • 您还可以使用 Session.udtf.register() 注册 UDTF。

  • 使用 Session.udtf.register_from_file() 从 Python 文件注册 UDTF。

• 更新了 APIs 以查询表函数，包括 Snowflake 内置表函数和 UDTFs。

  • 使用函数 snowflake.snowpark.functions.table_function() 创建表示表函数的 callable，并使用它在查询中调用表函数。

  • 或者，使用函数 snowflake.snowpark.functions.call_table_function() 调用表函数。

  • 增加了对 over 子句的支持，该子句在横向连接表函数时指定分区依据和排序依据。

  • 更新了 Session.table_function() 和 DataFrame.join_table_function() 以接受 TableFunctionCall 实例。

重大变更¶

• 使用 functions.udf() 和 functions.sproc() 创建函数时，现在可以为导入或包实参指定一个空列表，以指示此 UDF 或存储过程不使用任何导入或包。以前，指定空列表意味着函数将使用会话级导入或包。

• 改进了 types.py 中数据类型的 __repr__ 实现。未使用的 type_name 属性已被移除。

• 为 SQL 错误添加了 Snowpark 特定的异常类。这将替换 Python Connector 中先前的 ProgrammingError 错误。

改进¶

• 在每个线程第一次调用 UDF 或 UDTF 时，为其添加一个锁。

• 改进了 UDF 创建过程中出现的 pickling 错误的错误消息。

• 记录失败的查询时包括查询 ID。

错误修复¶

• 修复了调用 DataFrame.to_pandas() 时非整数数据（如时间戳）偶尔会转换为整数的错误。

• 修复了 DataFrameReader.parquet() 在其列包含空格时无法读取 parquet 文件的错误。

• 修复了通过读取具有推断架构的文件创建 DataFrame.copy_into_table() 失败的错误。

弃用¶

• Session.flatten() 和 DataFrame.flatten()

依赖项更新¶

• 限制了 cloudpickle <= 2.0.0 的版本。

新功能¶

• 添加了通过 Python UDF 批处理 API 对矢量化 UDFs 的支持。Python UDF 批处理 API 可用于定义 Python 函数，以 Pandas DataFrames (https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) 的形式接收成批的输入行，并以 Pandas 数组 (https://pandas.pydata.org/docs/reference/api/pandas.array.html) 或 序列 (https://pandas.pydata.org/docs/reference/series.html) 的形式返回成批的结果。这可以提高 Snowpark 中 UDFs 的性能。

• 添加了对通过读取暂存区中的 Parquet、Avro 或 ORC 文件创建 DataFrame 时，默认情况下推断其架构的支持。

• 向 snowflake.snowflake.functions 添加了函数 current_session()、current_statement()、current_user()、current_version()、current_warehouse()、date_from_parts()、date_trunc()、dayname()、dayofmonth()、dayofweek()、dayofyear()、grouping()、grouping_id()、hour()、last_day()、minute()、next_day()、previous_day()、second()、month()、monthname()、quarter()、year()、current_database()、current_role()、current_schema()、current_schemas()、current_region()、current_avaliable_roles()、add_months()、any_value()、bitnot()、bitshiftleft()、bitshiftright()、convert_timezone()、uniform()、strtok_to_array()、sysdate()、time_from_parts()、timestamp_from_parts()、timestamp_ltz_from_parts()、timestamp_ntz_from_parts()、timestamp_tz_from_parts()、weekofyear()、percentile_cont()。

改进¶

• 添加了对使用 Session.create_dataframe() 方法创建具有特定架构的空 DataFrame 的支持。

• 评估数据帧时，将多个日志（例如执行的查询）的日志记录级别从 INFO 更改为 DEBUG。

• 改进了由于 pickle 错误而无法创建 UDF 时的错误消息。

• 移除了 0.4.0 中不推荐使用的以下 APIs：DataFrame.groupByGroupingSets()、DataFrame.naturalJoin()、DataFrame.joinTableFunction、DataFrame.withColumns()、Session.getImports()、Session.addImport()、Session.removeImport()、Session.clearImports()、Session.getSessionStage()、Session.getDefaultDatabase()、Session.getDefaultSchema()、Session.getCurrentDatabase()、Session.getCurrentSchema()、Session.getFullyQualifiedCurrentSchema()。

• 添加了 typing-extension 作为版本 >= 4.1.0 的新依赖项。

错误修复¶

• 移除了 Session.create_dataframe() 方法中的 Pandas 硬依赖项。

新功能¶

• 添加了存储过程 API。

• 在 snowflake.snowpark.functions 中添加了 Session.sproc 属性和 sproc()，以便您可以注册存储过程。

• 添加了 Session.call 以按名称调用存储过程。

• 添加了 UDFRegistration.register_from_file() 以允许直接从 Python 源文件或 zip 文件注册 UDFs。

• 添加了 UDFRegistration.describe() 来描述 UDF。

• 添加了 DataFrame.random_split() 以提供随机分割数据帧的方法。

• 向 snowflake.snowpark.functions 添加了函数 md5()、sha1()、sha2()、ascii()、initcap()、length()、lower()、lpad()、ltrim()、rpad()、rtrim()、repeat()、soundex()、regexp_count()、replace()、charindex()、collate()、collation()、insert()、left()、right()、endswith()。

• call_udf() 函数现在也接受字面量值。

• 在 array_agg() 中提供了不同的关键字。

错误修复¶

• 修复了在使用 Column.cast(IntegerType()) 时导致 DataFrame.to_pandas() 具有字符串列的问题。

• 修复了 DataFrame.describe() 中存在多个字符串列时的错误。

新功能¶

• 现在，您可以指定在定义 UDFs 时要使用的 Anaconda 包。

• 向类会话添加了 add_packages()、get_packages()、clear_packages() 和 remove_package()。

• 将 add_requirements() 添加到会话中，以便您可以使用需求文件来指定此会话将使用的包。

• 向函数 snowflake.snowpark.functions.udf() 和方法 UserDefinedFunction.register() 添加了参数包，以指示创建 UDF 时 UDF 级 Anaconda 包的依赖项。

• 向 snowflake.snowpark.functions.udf() 和 UserDefinedFunction.register() 添加了参数导入以指定 UDF 级代码导入。

• 向函数 udf() 和 UserDefinedFunction.register() 添加了参数会话，以便在有多个会话的情况下指定使用哪个会话来创建 UDF。

• 向 snowflake.snowpark.types 添加了地理和变体类型，在定义 UDF 时用作地理和变体数据的类型提示。

• 添加了对地理 geoJSON 数据的支持。

• 添加了表，用于表操作的 DataFrame 的子类。

• 方法 update 和 delete 更新和删除 Snowflake 中表的行。

• 方法 merge 将 DataFrame 中的数据合并到表中。

• 用附加参数 seed 替换了 DataFrame.sample() 方法，该方法适用于表，但不适用于视图和子查询。

• 添加了 DataFrame.to_local_iterator() 和 DataFrame.to_pandas_batches()，以允许在从 Snowflake 数据库返回的结果集太大时从迭代器获取结果。

• 添加了 DataFrame.cache_result()，用于在临时表中缓存对 DataFrame 执行的操作。对原始 DataFrame 的后续操作对缓存的结果 DataFrame 没有影响。

• 添加了属性 DataFrame.queries 以获取 SQL 查询，将执行这些查询来评估 DataFrame。

• 添加了 Session.query_history() 作为上下文管理器来跟踪会话中执行的 SQL 查询，包括评估从会话创建的 DataFrames 的所有 SQL 查询。将记录查询 ID 和查询文本。

• 现在，您可以从现有已建立的 snowflake.connector.SnowflakeConnection 创建会话实例。在 Session.builder.configs() 中使用参数连接。

• 向类 Session 添加了 use_database()、use_schema()、use_warehouse() 和 use_role()，以在创建会话后切换 database/schema/warehouse/role。

• 添加了 DataFrameWriter.copy_into_table() 以将 DataFrame 卸载到暂存文件。

• 添加了 DataFrame.unpivot()。

• 添加了 Column.within_group()，用于使用一些聚合函数按列对行进行排序。

• 向 snowflake.snowpark.functions 添加了函数 listagg()、mode()、div0()、acos()、asin()、atan()、atan2()、cos()、cosh()、sin()、sinh()、tan()、tanh()、degrees()、radians()、round()、trunc() 和 factorial()。

• 在函数 lead() 和 lag() 中添加了一个可选实参 ignore_nulls。

• 函数 when() 和 iff() 的条件参数现在接受 SQL 表达式。

改进¶

• 所有函数和方法名称都已重命名，以使用 snake case 命名样式，这更像是 Pythonic。为了方便起见，一些 camel case 名称被保留为 snake case APIs 的别名。建议使用 snake case APIs。

• 在类 Session 上弃用了这些方法，并将它们替换为它们的 snake case 等效项：getImports()、addImports()、removeImport()、clearImports()、getSessionStage()、getDefaultSchema()、getDefaultSchema()、getCurrentDatabase() 和 getFullyQualifiedCurrentSchema()。

• 在类 DataFrame 上弃用了这些方法，并将它们替换为它们的 snake case 等效项： groupingByGroupingSets()、naturalJoin()、withColumns() 和 joinTableFunction()。

• 属性 DataFrame.columns 现在与 DataFrame.schema.names 和 Snowflake 数据库标识符要求一致。

• Column.__bool__() 现在引发 TypeError。这将禁止在列对象上使用逻辑运算符 and、or、not。例如，col("a") > 1 和 col("b") > 2 将引发 TypeError。请改用 (col("a") > 1) & (col("b") > 2)。

• 将 PutResult 和 GetResult 更改为子类 NamedTuple。

• 修复了当本地路径或暂存区位置具有空格或其他特殊字符时引发错误的错误。

• 更改 DataFrame.describe()，以便忽略非数字和非字符串列，而不是引发异常。

依赖项更新¶

• 将 snowflake-connector-python 更新至 2.7.4。

新功能¶

• 添加了别名为 Column.in_() 的 Column.isin()。

• 添加了 Column.try_cast()，这是 cast() 的特殊版本。它尝试将字符串表达式强制转换为其他类型，如果无法强制转换，则返回 null。

• 添加了 Column.startswith() 和 Column.substr() 来处理字符串列。

• 除了 DataType 实例之外，Column.cast() 现在还接受一个 str 值来指示转换类型。

• 添加了 DataFrame.describe() 以汇总 DataFrame 的统计信息。

• 添加了 DataFrame.explain() 以打印 DataFrame 的查询计划。

• DataFrame.filter() 和 DataFrame.select_expr() 现在接受 SQL 表达式。

• 向方法 DataFrame.saveAsTable() 和 Session.write_pandas() 添加了一个名为 create_temp_table 的新布尔参数，可以选择创建一个临时表。

• 将 DataFrame.minus() 和 DataFrame.subtract() 作为别名添加到 DataFrame.except_()。

• 向 snowflake.snowpark.functions module 添加了 regexp_replace()、concat()、concat_ws()、to_char()、current_timestamp()、current_date()、current_time()、months_between()、cast()、try_cast()、greatest()、least() 和 hash()。

错误修复¶

• 修复了当 Pandas DataFrame 的列名中有空格时 Session.createDataFrame(pandas_df) 和 Session.write_pandas(pandas_df) 引发异常的问题。

• 修复了 DataFrame.copy_into_table() 有时会错误地打印错误级别日志条目的问题。

• 修复了一个 API 文档问题，其中一些 DataFrame APIs 从文档中丢失。

依赖项更新¶

• 将 snowflake-connector-python 更新到 2.7.2，将 pyarrow 依赖项升级到 6.0.x。有关详细信息，请参阅 Python Connector 2.7.2 版本说明。

新功能¶

• 添加了用于从 Pandas DataFrame 创建 DataFrame 的 createDataFrame() 方法。

• 添加了 write_pandas() 方法，用于将 Pandas DataFrame 写入 Snowflake 中的表并取回 Snowpark DataFrame 对象。

• 添加了用于调用窗口函数的新类和方法。

• 添加了新函数 cume_dist() 和 row_number()，前者用于查找某个值相对于窗口分区中其他值的累积分布，后者为窗口分区中的每一行返回唯一的行号。

• 在 DataFrameStatFunctions 类中添加了用于计算 DataFrames 统计数据的函数。

• 在 DataFrameNaFunctions 类中添加了用于处理 DataFrame 中缺失值的函数。

• 向 DataFrame 类添加了新方法：rollup()、cube() 和 pivot()。

• 添加了 GroupingSets 类，该类可与 DataFrame groupByGroupingSets 方法一起使用，以执行 SQL GROUP BY GROUPING SETS。

• 添加了新的 FileOperation(session) 类，您可以使用该类从暂存区上传和下载文件。

• 添加了 copy_into_table() 方法，用于将数据从暂存区中的文件加载到表中。

• 在 CASE 表达式中，函数 when 和 otherwise 现在除了接受列对象外，还接受 Python 类型。

• 注册 UDF 时，现在可以选择将替换参数设置为 True 以覆盖同名的现有 UDF。

改进¶

• UDFs 现在在上传到服务器之前进行压缩。这使它们小了大约 10 倍，这在使用大型 ML 模型文件时很有帮助。

• 当 UDF 的大小小于 8196 字节时，它将作为内联代码上传，而不是上传到暂存区。

错误修复¶

• 修复了引发异常问题的语句 df.select(when(col("a") == 1, 4).otherwise(col("a"))), [Row(4), Row(2), Row(3)]。

• 修复了从大型本地数据创建 DataFrame 时 df.toPandas() 引发异常的问题。