ɯei#7WdZddlZddlZddlZddlmZddlZddlmZddlm Z ddlm Z m Z m Z m Z mZmZmZddlZddlmcmcmcmcmZddlmZddlmZmZddlZdd lm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)dd l*m+Z+dd l,m-Z-m.Z.m/Z/m0Z0m1Z1dd l2m3Z3m4Z4m5Z5m6Z6m7Z7m8Z8dd l9m:Z:m;Z;mZ>m?Z?ddl@mAZAddlBmCZCmDZDmEZEmFZFmGZGmHZHmIZIddlJddlKmLZLmMZMmNZNmOZOmPZPmQZQddlRmSZSmTZTddlUmVZVmWZWmXZXmYZYmZZZm[Z[m\Z\m]Z]ddl^m_Z_m`Z`ddlambZbmcZcddldmeZemfZfejdkrddlmhZhnddlimhZheeE ddddejdekdekdeMfd ZleeE dddd!ejdejdekdekdeMf d"ZleE dddd#ejd$e ejdekdekdeMf d%ZleeE ddddejdekdekdeMfd&ZmeeE dddd!ejdejdekdekdeMf d'ZmeE dddd#ejd$e ejdekdekdeMf d(ZmeE dd)e:d*e eWdekdeMfd+ZneEdd,ejdekdeMfd-ZoeE dd.ejd/ejd0ejd1e e ejdekf d2ZpeEddekdeMfd3ZqeEddekdeMfd4ZreEddekdeMfd5ZseEddekdeMfd6ZteEddekdeMfd7ZueEddekdeMfd8ZveEddekdeMfd9ZweEddekdeMfd:ZxeEddekdeMfd;ZyeEddekdeMfd<ZzeEddekdeMfd=Z{eEddekdeMfd>Z|eE dd?eZ#eEddWdXeeEddJeeMehe>eheMfdekdeMfdZeEddekdeMfdZeEddekdeMfdZeEddekdeMfdZeEddekdeMfdZeEddekdeMfdZeE ddBe<de}de e:dekdekdeMf dZeE ddBe<de}de eeMe>fdekdekdeMf dZeE ddBe<dekdekdeMfdZeE ddBe<dekdekdeMfdZeE ddBeZeZeeZeWZeZeZeZeZeoZeZeZɐe"Zʐe#ZeZ̐edZ͐eZZΐefZeE ddBe>> df = session.create_dataframe([[1, 'a', True, '2022-03-16'], [3, 'b', False, '2023-04-17']], schema=["a", "b", "c", "d"]) >>> res1 = df.filter(col("a") == 1).collect() >>> res2 = df.filter(lit(1) == col("a")).collect() >>> res3 = df.filter(sql_expr("a = 1")).collect() >>> assert res1 == res2 == res3 >>> res1 [Row(A=1, B='a', C=True, D='2022-03-16')] Some :class:`DataFrame` methods accept column names or SQL expressions text aside from a Column object for convenience. For instance: >>> df.filter("a = 1").collect() # use the SQL expression directly in filter [Row(A=1, B='a', C=True, D='2022-03-16')] >>> df.select("a").collect() [Row(A=1), Row(A=3)] whereas :class:`Column` objects enable you to use chained column operators and transformations with Python code fluently: >>> # Use columns and literals in expressions. >>> df.select(((col("a") + 1).cast("string")).alias("add_one")).show() ------------- |"ADD_ONE" | ------------- |2 | |4 | ------------- The Snowflake database has hundreds of `SQL functions `_ This module provides Python functions that correspond to the Snowflake SQL functions. They typically accept :class:`Column` objects or column names as input parameters and return a new :class:`Column` objects. The following examples demonstrate the use of some of these functions: >>> # This example calls the function that corresponds to the TO_DATE() SQL function. >>> df.select(dateadd('day', lit(1), to_date(col("d")))).show() --------------------------------------- |"DATEADD('DAY', 1, TO_DATE(""D""))" | --------------------------------------- |2022-03-17 | |2023-04-18 | --------------------------------------- If you want to use a SQL function in Snowflake but can't find the corresponding Python function here, you can create your own Python function with :func:`function`: >>> my_radians = function("radians") # "radians" is the SQL function name. >>> df.select(my_radians(col("a")).alias("my_radians")).show() ------------------------ |"MY_RADIANS" | ------------------------ |0.017453292519943295 | |0.05235987755982988 | ------------------------ or call the SQL function directly: >>> df.select(call_function("radians", col("a")).as_("call_function_radians")).show() --------------------------- |"CALL_FUNCTION_RADIANS" | --------------------------- |0.017453292519943295 | |0.05235987755982988 | --------------------------- Similarly, to call a table function, you can use :func:`~snowflake.snowpark.functions.table_function`, or :func:`~snowflake.snowpark.functions.call_table_function`. **How to find help on input parameters of the Python functions for SQL functions** The Python functions have the same name as the corresponding `SQL functions `_. By reading the API docs or the source code of a Python function defined in this module, you'll see the type hints of the input parameters and return type. The return type is always ``Column``. The input types tell you the acceptable values: - ``ColumnOrName`` accepts a :class:`Column` object, or a column name in str. Most functions accept this type. If you still want to pass a literal to it, use `lit(value)`, which returns a ``Column`` object that represents a literal value. >>> df.select(avg("a")).show() ---------------- |"AVG(""A"")" | ---------------- |2.000000 | ---------------- >>> df.select(avg(col("a"))).show() ---------------- |"AVG(""A"")" | ---------------- |2.000000 | ---------------- - ``LiteralType`` accepts a value of type ``bool``, ``int``, ``float``, ``str``, ``bytearray``, ``decimal.Decimal``, ``datetime.date``, ``datetime.datetime``, ``datetime.time``, or ``bytes``. An example is the third parameter of :func:`lead`. >>> import datetime >>> from snowflake.snowpark.window import Window >>> df.select(col("d"), lead("d", 1, datetime.date(2024, 5, 18), False).over(Window.order_by("d")).alias("lead_day")).show() --------------------------- |"D" |"LEAD_DAY" | --------------------------- |2022-03-16 |2023-04-17 | |2023-04-17 |2024-05-18 | --------------------------- - ``ColumnOrLiteral`` accepts a ``Column`` object, or a value of ``LiteralType`` mentioned above. The difference from ``ColumnOrLiteral`` is ``ColumnOrLiteral`` regards a str value as a SQL string value instead of a column name. When a function is much more likely to accept a SQL constant value than a column expression, ``ColumnOrLiteral`` is used. Yet you can still pass in a ``Column`` object if you need to. An example is the second parameter of :func:``when``. >>> df.select(when(df["a"] > 2, "Greater than 2").else_("Less than 2").alias("compare_with_2")).show() -------------------- |"COMPARE_WITH_2" | -------------------- |Less than 2 | |Greater than 2 | -------------------- - ``int``, ``bool``, ``str``, or another specific type accepts a value of that type. An example is :func:`to_decimal`. >>> df.with_column("e", lit("1.2")).select(to_decimal("e", 5, 2)).show() ----------------------------- |"TO_DECIMAL(""E"", 5, 2)" | ----------------------------- |1.20 | |1.20 | ----------------------------- - ``ColumnOrSqlExpr`` accepts a ``Column`` object, or a SQL expression. For instance, the first parameter in :func:``when``. >>> df.select(when("a > 2", "Greater than 2").else_("Less than 2").alias("compare_with_2")).show() -------------------- |"COMPARE_WITH_2" | -------------------- |Less than 2 | |Greater than 2 | -------------------- N)reduce)randint) ModuleType)CallableDictListOptionalTupleUnionoverload)general_functions)_call_function_check_column_parameters) CaseWhenFunctionExpressionIntervalListAggLiteralModelExpressionServiceExpressionMultipleExpressionStarNamedFunctionExpression)Alias) FirstValueLag LastValueLeadNthValue)build_builtin_fn_applybuild_call_table_function_apply-build_expr_from_snowpark_column_or_python_val*build_expr_from_snowpark_column_or_sql_strwith_src_positionbuild_function_expr)ColumnOrLiteralColumnOrLiteralStr ColumnOrNameColumnOrSqlExpr LiteralTypetype_string_to_type_object)check_decorator_args)parse_duration_stringparse_positional_args_to_list publicapivalidate_object_namecheck_create_map_parameter deprecatedprivate_preview)*)CaseExprColumn_to_col_if_lit_to_col_if_sql_expr_to_col_if_str_to_col_if_str_or_int)StoredProcedureStoredProcedureRegistration) ArrayTypeDataType FloatTypePandasDataFrameType StringType StructTypeTimestampTimeZone TimestampType)UDAFRegistrationUserDefinedAggregateFunction)UDFRegistrationUserDefinedFunction)UDTFRegistrationUserDefinedTableFunction) )IterableTF_is_qualified_namecol_name _emit_astrOreturncy)zReturns the :class:`~snowflake.snowpark.Column` with the specified name. Args: col_name: The name of the column. Example:: >>> df = session.sql("select 1 as a") >>> df.select(col("a")).collect() [Row(A=1)] NrPrQrOs ^/var/www/html/glpi_dashboard/venv/lib/python3.12/site-packages/snowflake/snowpark/functions.pycolrWdf_aliascy)zReturns the :class:`~snowflake.snowpark.Column` with the specified dataframe alias and column name. Example:: >>> df = session.sql("select 1 as a") >>> df.alias("df").select(col("df", "a")).collect() [Row(A=1)] NrTrZrPrQrOs rVrWrW rYname1name2c4tj||||S)NrN)r rWr^r_rQrOs rVrWrW(s!   ui4F rYcy)aReturns a :class:`~snowflake.snowpark.Column` with the specified name. Alias for col. Args: col_name: The name of the column. Example:: >>> df = session.sql("select 1 as a") >>> df.select(column("a")).collect() [Row(A=1)] NrTrUs rVcolumnrc5rXrYcy)aReturns a :class:`~snowflake.snowpark.Column` with the specified name and dataframe alias name. Alias for col. Example:: >>> df = session.sql("select 1 as a") >>> df.alias("df").select(column("df", "a")).collect() [Row(A=1)] NrTr\s rVrcrcGr]rYc\t|||t|||dSt||||dS)Nrc)rOrQ _caller_name)rr6ras rVrcrcZsJUE* } 1!     1!   rYliteraldatatypec0tj|||S)ai Creates a :class:`~snowflake.snowpark.Column` expression for a literal value. It supports basic Python data types, including ``int``, ``float``, ``str``, ``bool``, ``bytes``, ``bytearray``, ``datetime.time``, ``datetime.date``, ``datetime.datetime`` and ``decimal.Decimal``. Also, it supports Python structured data types, including ``list``, ``tuple`` and ``dict``, but this container must be JSON serializable. If a ``Column`` object is passed, it is returned as is. Example:: >>> import datetime >>> columns = [lit(1), lit("1"), lit(1.0), lit(True), lit(b'snow'), lit(datetime.date(2023, 2, 2)), lit([1, 2]), lit({"snow": "flake"}), lit(lit(1))] >>> session.create_dataframe([[]]).select([c.as_(str(i)) for i, c in enumerate(columns)]).show() --------------------------------------------------------------------------------------------- |"0" |"1" |"2" |"3" |"4" |"5" |"6" |"7" |"8" | --------------------------------------------------------------------------------------------- |1 |1 |1.0 |True |bytearray(b'snow') |2023-02-02 |[ |{ |1 | | | | | | | | 1, | "snow": "flake" | | | | | | | | | 2 |} | | | | | | | | |] | | | --------------------------------------------------------------------------------------------- )r lit)rgrhrQs rVrjrjus:  (I >>rYsqlcd}|rQtj}t|j}||_tj}t |d|t j||S)aCreates a :class:`~snowflake.snowpark.Column` expression from raw SQL text. Note that the function does not interpret or check the SQL text. Example:: >>> df = session.create_dataframe([[1, 2], [3, 4]], schema=["A", "B"]) >>> df.select(sql_expr("a + 1").as_("c"), sql_expr("a = 1").as_("d")).collect() # use SQL expression [Row(C=2, D=True), Row(C=4, D=False)] Nsql_expr)ast)protoExprr$rmrkr r6_expr)rkrQrn sql_expr_asts rVrmrmsX Czz|  5 56jjlsJ = << %%rY object_typeobject_identifierscope privilegesc`|xsg}|rtd|||g|znd}td|||g|||dS)a Returns a reference to an object (a table, view, or function). When you execute SQL actions on a reference to an object, the actions are performed using the role of the user who created the reference. Example:: >>> df = session.create_dataframe([(1,)], schema=["A"]) >>> df.write.save_as_table("my_table", mode="overwrite", table_type="temporary") >>> df.select(substr(system_reference("table", "my_table"), 1, 14).alias("identifier")).collect() [Row(IDENTIFIER='ENT_REF_TABLE_')] system_referenceNzsystem$reference_astrQ)r%r)rsrtrurvrQrns rVrxrxsl&!rJ    +U 3j @          rYctd|S)a Returns a unique system identifier for the Snowflake session corresponding to the present connection. This will generally be a system-generated alphanumeric string. It is NOT derived from the user name or user account. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_session()).collect() >>> assert result[0]['CURRENT_SESSION()'] is not None current_sessionrQrr}s rVr|r|s +y AArYctd|S)a Returns the SQL text of the statement that is currently executing. Example: >>> # Return result is tied to session, so we only test if the result exists >>> session.create_dataframe([1]).select(current_statement()).collect() # doctest: +SKIP [Row(CURRENT_STATEMENT()='SELECT current_statement() FROM ( SELECT "_1" FROM ( SELECT $1 AS "_1" FROM VALUES (1 :: INT)))')] current_statementr}r~r}s rVrr - CCrYctd|S)a: Returns the name of the user currently logged into the system. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_user()).collect() >>> assert result[0]['CURRENT_USER()'] is not None current_userr}r~r}s rVrrs .I >>rYctd|S)a( Returns the current Snowflake version. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_version()).collect() >>> assert result[0]['CURRENT_VERSION()'] is not None current_versionr}r~r}s rVrrs +y AArYctd|S)aG Returns the name of the warehouse in use for the current session. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_warehouse()).collect() >>> assert result[0]['CURRENT_WAREHOUSE()'] is not None current_warehouser}r~r}s rVrrrrYctd|S)a?Returns the name of the database in use for the current session. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_database()).collect() >>> assert result[0]['CURRENT_DATABASE()'] is not None current_databaser}r~r}s rVrrs , BBrYctd|S)a3Returns the name of the role in use for the current session. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_role()).collect() >>> assert result[0]['CURRENT_ROLE()'] is not None current_roler}r~r}s rVrr! .I >>rYctd|S)a9Returns the name of the schema in use for the current session. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_schema()).collect() >>> assert result[0]['CURRENT_SCHEMA()'] is not None current_schemar}r~r}s rVrr- *i @@rYctd|S)a Returns active search path schemas. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_schemas()).collect() >>> assert result[0]['CURRENT_SCHEMAS()'] is not None current_schemasr}r~r}s rVrr9 +y AArYctd|S)aNReturns the name of the region for the account where the current user is logged in. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_region()).collect() >>> assert result[0]['CURRENT_REGION()'] is not None current_regionr}r~r}s rVrrErrYctd|S)a9Returns the name of the account used in the current session. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_account()).collect() >>> assert result[0]['CURRENT_ACCOUNT()'] is not None current_accountr}r~r}s rVrrQrrYctd|S)aTReturns a JSON string that lists all roles granted to the current user. Example: >>> # Return result is tied to session, so we only test if the result exists >>> result = session.create_dataframe([1]).select(current_available_roles()).collect() >>> assert result[0]['CURRENT_AVAILABLE_ROLES()'] is not None current_available_rolesr}r~r}s rVrr]s 3y IIrYdate_or_timestampnumber_of_monthsc8t|d}td|||S)aOAdds or subtracts a specified number of months to a date or timestamp, preserving the end-of-month information. Example: >>> import datetime >>> df = session.create_dataframe([datetime.date(2022, 4, 6)], schema=["d"]) >>> df.select(add_months("d", 4)).collect()[0][0] datetime.date(2022, 8, 6) add_monthsr}r9r)rrrQcs rVrris# (,7A ,+;y QQrYec6t|d}td||S)aRReturns a non-deterministic any value for the specified column. This is an aggregate and window function. Example: >>> df = session.create_dataframe([[1, 2], [3, 4]], schema=["a", "b"]) >>> result = df.select(any_value("a")).collect() >>> assert len(result) == 1 # non-deterministic value in result. any_valuer}rrrQrs rVrr{s q+&A +qI >>rYc6t|d}td||S)zReturns the bitwise negation of a numeric expression. Example: >>> df = session.create_dataframe([1], schema=["a"]) >>> df.select(bitnot("a")).collect()[0][0] -2 bitnotr}rrs rVrrs q(#A (A ;;rYto_shift_columnnc8t|d}td|||S)zReturns the bitwise negation of a numeric expression. Example: >>> df = session.create_dataframe([2], schema=["a"]) >>> df.select(bitshiftleft("a", 1)).collect()[0][0] 4 bitshiftleftr}rrrrQrs rVrrs! 7A .!Q) DDrYc |rtd||gnd}t|d}ttdddd}t |dkt ||z|dt ||dd}t d||dz || S) a Returns the bitwise negation of a numeric expression. Example: >>> df = session.createDataFrame([(-1999)], ['a']) >>> df.select(bitshiftright_unsigned('a', 1)).collect()[0][0] 9223372036854774808 >>> df = session.createDataFrame([(42)], ['a']) >>> df.select(bitshiftright_unsigned('a', 1)).collect()[0][0] 21 >>> df = session.createDataFrame([(-21)], ['a']) >>> df.select(bitshiftright_unsigned('a', 1)).collect()[0][0] 9223372036854775797 bitshiftright_unsignedNFr}@rbitandry)r%r9rrjiff bitshiftrightr)rrrQrnrmax_bit unsigned_cs rVrrs,  46JK  (@AA3qE2B%HG Aa'k16ae, J *gky rYc8t|d}td|||S)zReturns the bitwise negation of a numeric expression. Example: >>> df = session.create_dataframe([2], schema=["a"]) >>> df.select(bitshiftright("a", 1)).collect()[0][0] 1 rr}rrs rVrrs! 8A /1a9 EErYrWscalec |rtd||gnd}t|d}t|d}td||t dd||S)a[ Rounds the number using `HALF_TO_EVEN` option. The `HALF_TO_EVEN` rounding mode rounds the given decimal value to the specified scale (number of decimal places) as follows: * If scale is greater than or equal to 0, round to the specified number of decimal places using half-even rounding. This rounds towards the nearest value with ties (equally close values) rounding to the nearest even digit. * If scale is less than 0, round to the integral part of the decimal. This rounds towards 0 and truncates the decimal places. Note: 1. The data type of the expression must be one of the `data types for a fixed-point number `_. 2. Data types for floating point numbers (e.g. FLOAT) are not supported with this argument. 3. If the expression data type is not supported, the expression must be explicitly cast to decimal before calling. Example: >>> import decimal >>> data = [(decimal.Decimal(1.235)),(decimal.Decimal(3.5))] >>> df = session.createDataFrame(data, ["value"]) >>> df.select(bround('VALUE',1).alias("VALUE")).show() # Rounds to 1 decimal place ----------- |"VALUE" | ----------- |1.2 | |3.5 | ----------- >>> df.select(bround('VALUE',0).alias("VALUE")).show() # Rounds to 1 decimal place ----------- |"VALUE" | ----------- |1 | |4 | ----------- broundNROUND HALF_TO_EVENFr}ry)r%r9r7rrj)rWrrQrns rVrrs[P:C he 5C h 'C 5( +E    Ne,   rYtarget_timezone source_timesource_timezonec| t|dnd}t|d}t|d}|rtd||g|gn|gznd}|td||||Std|||||S)a=Converts the given source_time to the target timezone. For timezone information, refer to the `Snowflake SQL convert_timezone notes `_ Args: target_timezone: The time zone to which the input timestamp should be converted.= source_time: The timestamp to convert. When it's a TIMESTAMP_LTZ, use ``None`` for ``source_timezone``. source_timezone: The time zone for the ``source_time``. Required for timestamps with no time zone (i.e. TIMESTAMP_NTZ). Use ``None`` if the timestamps have a time zone (i.e. TIMESTAMP_LTZ). Default is ``None``. Note: The sequence of the 3 params is different from the SQL function, which two overloads: - ``CONVERT_TIMEZONE( , , )`` - ``CONVERT_TIMEZONE( , )`` The first parameter ``source_tz`` is optional. But in Python an optional argument shouldn't be placed at the first. So ``source_timezone`` is after ``source_time``. Example: >>> import datetime >>> from dateutil import tz >>> datetime_with_tz = datetime.datetime(2022, 4, 6, 9, 0, 0, tzinfo=tz.tzoffset("myzone", -3600*7)) >>> datetime_with_no_tz = datetime.datetime(2022, 4, 6, 9, 0, 0) >>> df = session.create_dataframe([[datetime_with_tz, datetime_with_no_tz]], schema=["a", "b"]) >>> result = df.select(convert_timezone(lit("UTC"), col("a")), convert_timezone(lit("UTC"), col("b"), lit("Asia/Shanghai"))).collect() >>> result[0][0] datetime.datetime(2022, 4, 6, 16, 0, tzinfo=) >>> result[0][1] datetime.datetime(2022, 4, 6, 1, 0) Nconvert_timezonery)r9r%r)rrrrQ source_tz target_tzsource_time_to_convertrns rVrrsN  & (:;  0BCI+K9KL    k *$,r?2C E    "       rYc6t|d}td||S)aUses HyperLogLog to return an approximation of the distinct cardinality of the input (i.e. HLL(col1, col2, ... ) returns an approximation of COUNT(DISTINCT col1, col2, ... )). Example:: >>> df = session.create_dataframe([[1, 2], [3, 4], [5, 6]], schema=["a", "b"]) >>> df.select(approx_count_distinct("a").alias("result")).show() ------------ |"RESULT" | ------------ |3 | ------------ approx_count_distinctr}rrs rVrr[s! q12A 11 JJrYc6t|d}td||S)aReturns the average of non-NULL records. If all records inside a group are NULL, the function returns NULL. Example:: >>> df = session.create_dataframe([[1], [2], [2]], schema=["d"]) >>> df.select(avg(df.d).alias("result")).show() ------------ |"RESULT" | ------------ |1.666667 | ------------ avgr}rrs rVrro q% A %i 88rYcolumn1column2cPt|d}t|d}td|||S)aReturns the correlation coefficient for non-null pairs in a group. Example: >>> df = session.create_dataframe([[1, 2], [1, 2], [4, 5], [2, 3], [3, None], [4, None], [6,4]], schema=["a", "b"]) >>> df.select(corr(col("a"), col("b")).alias("result")).show() --------------------- |"RESULT" | --------------------- |0.813681508328809 | --------------------- corrr}r)rrrQc1c2s rVrrs-  (B  (B &"bI >>rYc|r td|gnd}t|d}t|jtr t dn |j}t d|||S)aIReturns either the number of non-NULL records for the specified columns, or the total number of records. Example: >>> df = session.create_dataframe([[1], [None], [3], [4], [None]], schema=["a"]) >>> df.select(count(col("a")).alias("result")).show() ------------ |"RESULT" | ------------ |3 | ------------ >>> df.select(count("*").alias("result")).show() ------------ |"RESULT" | ------------ |5 | ------------ countNrry)r%r9 isinstance _expressionrrr)rrQrnrexprs rVrrsP.09 gs +dCq'"A#AMM4871:ammD '4cY GGrYr}colsc |Dcgc]}t|d}}|r td|nd}ttd|Dcgc]}|jc}d||Scc}wcc}w)aHReturns either the number of non-NULL distinct records for the specified columns, or the total number of the distinct records. Example: >>> df = session.create_dataframe([[1, 2], [1, 2], [3, None], [2, 3], [3, None], [4, None]], schema=["a", "b"]) >>> df.select(count_distinct(col("a"), col("b")).alias("result")).show() ------------ |"RESULT" | ------------ |2 | ------------ >>> # The result should be 2 for {[1,2],[2,3]} since the rest are either duplicate or NULL records count_distinctNrT) is_distinctry)r9r%r6rr)rQrrcsrns rVrrsj"8< >> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([[1, 2], [1, 2], [4, 5], [2, 3], [3, None], [4, None], [6,4]], schema=["a", "b"]) >>> df.select(covar_pop(col("a"), col("b")).cast(DecimalType(scale=3)).alias("result")).show() ------------ |"RESULT" | ------------ |1.840 | ------------ covar_popr}rrrrQcol1col2s rVrrs-" '; /D '; /D +tTY GGrYcPt|d}t|d}td|||S)aReturns the sample covariance for non-null pairs in a group. Example: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([[1, 2], [1, 2], [4, 5], [2, 3], [3, None], [4, None], [6,4]], schema=["a", "b"]) >>> df.select(covar_samp(col("a"), col("b")).cast(DecimalType(scale=3)).alias("result")).show() ------------ |"RESULT" | ------------ |2.300 | ------------ covar_sampr}rrs rVrrs-" '< 0D '< 0D ,di HHrYct|}d}|r)tj}|rt|dg|r|n|ndt |dk(rt |dt tfr|d}t|ddi}||_ |S)aiTransforms multiple column pairs into a single map :class:`~snowflake.snowpark.Column` where each pair of columns is treated as a key-value pair in the resulting map. Args: *cols: A variable number of column names or :class:`~snowflake.snowpark.Column` objects that can also be expressed as a list of columns. The function expects an even number of arguments, where each pair of arguments represents a key-value pair for the map. Returns: A :class:`~snowflake.snowpark.Column` where each row contains a map created from the provided column pairs. Example: >>> from snowflake.snowpark.functions import create_map >>> df = session.create_dataframe([("Paris", "France"), ("Tokyo", "Japan")], ("city", "country")) >>> df.select(create_map("city", "country").alias("map")).show() ----------------------- |"MAP" | ----------------------- |{ | | "Paris": "France" | |} | |{ | | "Tokyo": "Japan" | |} | ----------------------- >>> df.select(create_map([df.city, df.country]).alias("map")).show() ----------------------- |"MAP" | ----------------------- |{ | | "Paris": "France" | |} | |{ | | "Tokyo": "Japan" | |} | ----------------------- N create_maprrrQF) r1rorpr lenrlisttupleobject_construct_keep_nullrz)rQrvariadicrnrWs rVrrs\*40H Cjjl   (0d   4yA~*T!WtUm<Aw $d >> from snowflake.snowpark.functions import kurtosis >>> df = session.create_dataframe([1, 3, 10, 1, 3], schema=["x"]) >>> df.select(kurtosis("x").as_("x")).collect() [Row(X=Decimal('3.613736609956'))] kurtosisr}rrs rVrr:s q*%A *a9 ==rYc6t|d}td||S)aE Returns the maximum value for the records in a group. NULL values are ignored unless all the records are NULL, in which case a NULL value is returned. Example:: >>> df = session.create_dataframe([1, 3, 10, 1, 3], schema=["x"]) >>> df.select(max("x").as_("x")).collect() [Row(X=10)] maxr}rrs rVrrK q% A %i 88rYcrt|d}t|d}|rtd|g|_|Sd|_|S)a Return the average for the specific numeric columns. Alias of :func:`avg`. Example:: >>> df = session.create_dataframe([1, 3, 10, 1, 3], schema=["x"]) >>> df.select(mean("x").as_("x")).collect() [Row(X=Decimal('3.600000'))] meanFr}N)r9rr%rz)rrQranss rVrr[sD q&!A a5 !C3<"6A3/CH JCGCH JrYc6t|d}td||S)aU Returns the median value for the records in a group. NULL values are ignored unless all the records are NULL, in which case a NULL value is returned. Example:: >>> df = session.create_dataframe([1, 3, 10, 1, 3], schema=["x"]) >>> df.select(median("x").as_("x")).collect() [Row(X=Decimal('3.000'))] medianr}rrs rVrrls q(#A (A ;;rYc6t|d}td||S)aD Returns the minimum value for the records in a group. NULL values are ignored unless all the records are NULL, in which case a NULL value is returned. Example:: >>> df = session.create_dataframe([1, 3, 10, 1, 3], schema=["x"]) >>> df.select(min("x").as_("x")).collect() [Row(X=1)] minr}rrs rVrr|rrYc6t|d}td||S)aT Returns the most frequent value for the records in a group. NULL values are ignored. If all the values are NULL, or there are 0 rows, then the function returns NULL. Example:: >>> df = session.create_dataframe([1, 3, 10, 1, 4], schema=["x"]) >>> df.select(mode("x").as_("x")).collect() [Row(X=1)] moder}rrs rVrr q&!A &!y 99rYc6t|d}td||S)aReturns the sample skewness of non-NULL records. If all records inside a group are NULL, the function returns NULL. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe( ... [10, 10, 20, 25, 30], ... schema=["a"] ... ).select(skew("a").cast(DecimalType(scale=4))) >>> df.collect() [Row(CAST (SKEW("A") AS NUMBER(38, 4))=Decimal('0.0524'))] skewr}rrs rVrrs q&!A &!y 99rYc6t|d}td||S)aReturns the sample standard deviation (square root of sample variance) of non-NULL values. If all records inside a group are NULL, returns NULL. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe( ... [4, 9], ... schema=["N"], ... ).select(stddev(col("N")).cast(DecimalType(scale=4))) >>> df.collect() [Row(CAST (STDDEV("N") AS NUMBER(38, 4))=Decimal('3.5355'))] stddevr}rrs rVrrs q(#A (A ;;rYc6t|d}td||S)a Returns the sample standard deviation (square root of sample variance) of non-NULL values. If all records inside a group are NULL, returns NULL. Alias of :func:`stddev`. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe( ... [4, 9], ... schema=["N"], ... ).select(stddev_samp(col("N")).cast(DecimalType(scale=4))) >>> df.collect() [Row(CAST (STDDEV_SAMP("N") AS NUMBER(38, 4))=Decimal('3.5355'))] stddev_sampr}rrs rVrrs q-(A -i @@rYc6t|d}td||S)amReturns the population standard deviation (square root of variance) of non-NULL values. If all records inside a group are NULL, returns NULL. Example:: >>> df = session.create_dataframe( ... [4, 9], ... schema=["N"], ... ).select(stddev_pop(col("N"))) >>> df.collect() [Row(STDDEV_POP("N")=2.5)] stddev_popr}rrs rVrrs q,'A ,Y ??rYc6t|d}td||S)aReturns the sum of non-NULL records in a group. You can use the DISTINCT keyword to compute the sum of unique non-null values. If all records inside a group are NULL, the function returns NULL. Example:: >>> df = session.create_dataframe( ... [4, 9], ... schema=["N"], ... ).select(sum(col("N"))) >>> df.collect() [Row(SUM("N")=13)] sumr}rrs rVrr q% A %i 88rYc\|r td|gnd}t|d}td|d||S)aReturns the sum of non-NULL distinct records in a group. You can use the DISTINCT keyword to compute the sum of unique non-null values. If all records inside a group are NULL, the function returns NULL. Example:: >>> df = session.create_dataframe( ... [1, 2, None, 3], ... schema=["N"], ... ).select(sum_distinct(col("N"))) >>> df.collect() [Row(SUM( DISTINCT "N")=6)] sum_distinctNrTrrzrQr%r9rrrQrnrs rVrrs77@ nqc 2TCq.)A %3) TTrYc6t|d}td||S)alReturns the sample variance of non-NULL records in a group. If all records inside a group are NULL, a NULL is returned. For a single row, NULL is returned as sample variance. Example:: >>> df = session.create_dataframe([1, -1, 1, -1, -1], schema=["a"]) >>> df.select(variance(col("a"))).collect() [Row(VARIANCE("A")=Decimal('1.200000'))] >>> df = session.create_dataframe([1, None, 2, 3, None, 5, 6], schema=["a"]) >>> df.select(variance(col("a"))).collect() [Row(VARIANCE("A")=Decimal('4.300000'))] >>> df = session.create_dataframe([None, None, None], schema=["a"]) >>> df.select(variance(col("a"))).collect() [Row(VARIANCE("A")=None)] >>> df = session.create_dataframe([42], schema=["a"]) >>> df.select(variance(col("a"))).collect() [Row(VARIANCE("A")=None)] variancer}rrs rVrr s0 q*%A *a9 ==rYcZ|r td|gnd}t|d}td|||S)aReturns the sample variance of non-NULL records in a group. If all records inside a group are NULL, a NULL is returned. For a single row, NULL is returned as sample variance. Alias of :func:`variance` Example:: >>> df = session.create_dataframe([1, -1, 1, -1, -1], schema=["a"]) >>> df.select(var_samp(col("a"))).collect() [Row(VARIANCE("A")=Decimal('1.200000'))] >>> df = session.create_dataframe([1, None, 2, 3, None, 5, 6], schema=["a"]) >>> df.select(var_samp(col("a"))).collect() [Row(VARIANCE("A")=Decimal('4.300000'))] >>> df = session.create_dataframe([None, None, None], schema=["a"]) >>> df.select(var_samp(col("a"))).collect() [Row(VARIANCE("A")=None)] >>> df = session.create_dataframe([42], schema=["a"]) >>> df.select(var_samp(col("a"))).collect() [Row(VARIANCE("A")=None)] var_sampNrryrrs rVrr's443< j1# .Cq*%A *acY GGrYc6t|d}td||S)apReturns the population variance of non-NULL records in a group. If all records inside a group are NULL, a NULL is returned. The population variance of a single row is 0.0. Example:: >>> df = session.create_dataframe([1, -1, 1, -1, -1], schema=["a"]) >>> df.select(var_pop(col("a"))).collect() [Row(VAR_POP("A")=Decimal('0.960000'))] >>> df = session.create_dataframe([1, None, 2, 3, None, 5, 6], schema=["a"]) >>> df.select(var_pop(col("a"))).collect() [Row(VAR_POP("A")=Decimal('3.440000'))] >>> df = session.create_dataframe([None, None, None], schema=["a"]) >>> df.select(var_pop(col("a"))).collect() [Row(VAR_POP("A")=None)] >>> df = session.create_dataframe([42], schema=["a"]) >>> df.select(var_pop(col("a"))).collect() [Row(VAR_POP("A")=Decimal('0.000000'))] var_popr}rrs rVrrGs0 q)$A )Q) <>> df = session.create_dataframe([0,1,2,3,4,5,6,7,8,9], schema=["a"]) >>> df.select(approx_percentile("a", 0.5).alias("result")).show() ------------ |"RESULT" | ------------ |4.5 | ------------ approx_percentileNFr}ryr9r%rrj)rWr rQrrns rVr r csT s/0AFO/!ZATX   J%(   rYc6t|d}td||S)a_Returns the internal representation of the t-Digest state (as a JSON object) at the end of aggregation. This function uses the t-Digest algorithm. Example:: >>> df = session.create_dataframe([1,2,3,4,5], schema=["a"]) >>> df.select(approx_percentile_accumulate("a").alias("result")).show() ------------------------------ |"RESULT" | ------------------------------ |{ | | "state": [ | | 1.000000000000000e+00, | | 1.000000000000000e+00, | | 2.000000000000000e+00, | | 1.000000000000000e+00, | | 3.000000000000000e+00, | | 1.000000000000000e+00, | | 4.000000000000000e+00, | | 1.000000000000000e+00, | | 5.000000000000000e+00, | | 1.000000000000000e+00 | | ], | | "type": "tdigest", | | "version": 1 | |} | ------------------------------ approx_percentile_accumulater}rrWrQrs rVrrs!< s:;A 8!y QQrYstatectt|d}|rtd||gnd}td|t|d||S)a^Returns the desired approximated percentile value for the specified t-Digest state. APPROX_PERCENTILE_ESTIMATE(APPROX_PERCENTILE_ACCUMULATE(.)) is equivalent to APPROX_PERCENTILE(.). Example:: >>> df = session.create_dataframe([1,2,3,4,5], schema=["a"]) >>> df_accu = df.select(approx_percentile_accumulate("a").alias("app_percentile_accu")) >>> df_accu.select(approx_percentile_estimate("app_percentile_accu", 0.5).alias("result")).show() ------------ |"RESULT" | ------------ |3.0 | ------------ approx_percentile_estimateNFr}ryr )rr rQrrns rVrrsT& u:;A  81j/J  $  J%(   rYc6t|d}td||S)a%Combines (merges) percentile input states into a single output state. This allows scenarios where APPROX_PERCENTILE_ACCUMULATE is run over horizontal partitions of the same table, producing an algorithm state for each table partition. These states can later be combined using APPROX_PERCENTILE_COMBINE, producing the same output state as a single run of APPROX_PERCENTILE_ACCUMULATE over the entire table. Example:: >>> df1 = session.create_dataframe([1,2,3,4,5], schema=["a"]) >>> df2 = session.create_dataframe([6,7,8,9,10], schema=["b"]) >>> df_accu1 = df1.select(approx_percentile_accumulate("a").alias("app_percentile_accu")) >>> df_accu2 = df2.select(approx_percentile_accumulate("b").alias("app_percentile_accu")) >>> df_accu1.union(df_accu2).select(approx_percentile_combine("app_percentile_accu").alias("result")).show() ------------------------------ |"RESULT" | ------------------------------ |{ | | "state": [ | | 1.000000000000000e+00, | | 1.000000000000000e+00, | | 2.000000000000000e+00, | | 1.000000000000000e+00, | | 3.000000000000000e+00, | | 1.000000000000000e+00, | | 4.000000000000000e+00, | | 1.000000000000000e+00, | | 5.000000000000000e+00, | | 1.000000000000000e+00, | | 6.000000000000000e+00, | | 1.000000000000000e+00, | | 7.000000000000000e+00, | | 1.000000000000000e+00, | | 8.000000000000000e+00, | | 1.000000000000000e+00, | | 9.000000000000000e+00, | | 1.000000000000000e+00, | | 1.000000000000000e+01, | | 1.000000000000000e+00 | | ], | | "type": "tdigest", | | "version": 1 | |} | ------------------------------ approx_percentile_combiner}r)rrQrs rVrrs"\ u9:A 5qI NNrYz3snowflake.snowpark.table_function.TableFunctionCallc|r td|gnd}t|d}tjjj |t dd}|jd||_|S)aYFlattens a given array or map type column into individual rows. The default column name for the output column in case of array input column is ``VALUE``, and is ``KEY`` and ``VALUE`` in case of map input column. Examples:: >>> df = session.create_dataframe([[1, [1, 2, 3], {"Ashi Garami": "Single Leg X"}, "Kimura"], ... [2, [11, 22], {"Sankaku": "Triangle"}, "Coffee"]], ... schema=["idx", "lists", "maps", "strs"]) >>> df.select(df.idx, explode(df.lists)).sort(col("idx")).show() ------------------- |"IDX" |"VALUE" | ------------------- |1 |1 | |1 |2 | |1 |3 | |2 |11 | |2 |22 | ------------------- >>> df.select(df.strs, explode(df.maps)).sort(col("strs")).show() ----------------------------------------- |"STRS" |"KEY" |"VALUE" | ----------------------------------------- |Coffee |Sankaku |"Triangle" | |Kimura |Ashi Garami |"Single Leg X" | ----------------------------------------- >>> df.select(explode(col("lists")).alias("uno")).sort(col("uno")).show() --------- |"UNO" | --------- |1 | |2 | |3 | |11 | |22 | --------- >>> df.select(explode('maps').as_("primo", "secundo")).sort(col("primo")).show() -------------------------------- |"PRIMO" |"SECUNDO" | -------------------------------- |Ashi Garami |"Single Leg X" | |Sankaku |"Triangle" | -------------------------------- explodeNFr}zfunctions.explode r%r9 snowflakesnowparktable_function_ExplodeFunctionCallrj_set_api_call_sourcerzrWrQrn func_calls rVrrsjn4= i# /$C i (C""11FF S% (I""#67IN rYc|r td|gnd}t|d}tjjj |t dd}|jd||_|S)a/Flattens a given array or map type column into individual rows. Unlike :func:`explode`, if array or map is empty, null or empty, then null values are produced. The default column name for the output column in case of array input column is ``VALUE``, and is ``KEY`` and ``VALUE`` in case of map input column. Args: col: Column object or string name of the desired column Examples:: >>> df = session.create_dataframe([[1, [1, 2, 3], {"Ashi Garami": "Single Leg X"}], ... [2, [11, 22], {"Sankaku": "Triangle"}], ... [3, [], {}]], ... schema=["idx", "lists", "maps"]) >>> df.select(df.idx, explode_outer(df.lists)).sort(col("idx")).show() ------------------- |"IDX" |"VALUE" | ------------------- |1 |1 | |1 |2 | |1 |3 | |2 |11 | |2 |22 | |3 |NULL | ------------------- >>> df.select(df.idx, explode_outer(df.maps)).sort(col("idx")).show() ---------------------------------------- |"IDX" |"KEY" |"VALUE" | ---------------------------------------- |1 |Ashi Garami |"Single Leg X" | |2 |Sankaku |"Triangle" | |3 |NULL |NULL | ---------------------------------------- See Also: :func:`explode` explode_outerNTFr}zfunctions.explode_outerrrs rVr r >skX:C ou 5C o .C""11FF S 'I""#<=IN rYpathouter recursiver)objectarraybothc  |rtd|||||gnd}t|d}tjjj d|t |t |t |t |d}|jd||_|S)a FLATTEN explodes compound values into multiple rows. This table function takes a VARIANT, OBJECT, or ARRAY column and produces a lateral view. Args: col: Column object or string name of the desired column. path: The path to the element within VARIANT data structure which needs to be flattened. Defaults to "". outer: When ``False``, any input rows that cannot be expanded are completely omitted from the output. When ``True``, exactly one row s generated for zero-row expansions. Defaults to ``False``. recursive: When ``False``, only the reference by ``path`` is expanded. When ``True``, the expansion is performed for all sub-elements recursively. Defaults to ``False``. mode: Specifies whether only objects, arrays, or both should be flattened. Defaults to "both". Examples:: >>> df = session.create_dataframe([[1, [1, 2, 3], {"Ashi Garami": ["X", "Leg Entanglement"]}, "Kimura"], ... [2, [11, 22], {"Sankaku": ["Triangle"]}, "Coffee"], ... [3, [], {}, "empty"]], ... schema=["idx", "lists", "maps", "strs"]) >>> df.select(df.idx, flatten(df.lists, outer=True)).select("idx", "value").sort("idx").show() ------------------- |"IDX" |"VALUE" | ------------------- |1 |1 | |1 |2 | |1 |3 | |2 |11 | |2 |22 | |3 |NULL | ------------------- >>> df.select(df.strs, flatten(df.maps, recursive=True)).select("strs", "key", "value").where("key is not NULL").sort("strs").show() ----------------------------------------------- |"STRS" |"KEY" |"VALUE" | ----------------------------------------------- |Coffee |Sankaku |[ | | | | "Triangle" | | | |] | |Kimura |Ashi Garami |[ | | | | "X", | | | | "Leg Entanglement" | | | |] | ----------------------------------------------- >>> df.select(df.strs, flatten(df.maps, recursive=True)).select("strs", "key", "value").where("key is NULL").sort("strs", "value").show() --------------------------------------- |"STRS" |"KEY" |"VALUE" | --------------------------------------- |Coffee |NULL |"Triangle" | |Kimura |NULL |"Leg Entanglement" | |Kimura |NULL |"X" | --------------------------------------- See Also: - :func:`explode` - `Flatten `_ flattenNF)inputr!r"r#rrQzfunctions.flatten) r%r9rrrTableFunctionCallrjrrz)rWr!r"r#rrQrnrs rVr(r(vsT  IT5)T'JK  i (C""11CC Y%ji. YDI""#67IN rYc\|Dcgc]}t|d}}tdg|d|iScc}w)a Describes which of a list of expressions are grouped in a row produced by a GROUP BY query. :func:`grouping_id` is an alias of :func:`grouping`. Example:: >>> from snowflake.snowpark import GroupingSets >>> df = session.create_dataframe([[1, 2, 3], [4, 5, 6]],schema=["a", "b", "c"]) >>> grouping_sets = GroupingSets([col("a")], [col("b")], [col("a"), col("b")]) >>> df.group_by_grouping_sets(grouping_sets).agg([count("c").alias("count_c"), grouping("a").alias("ga"), grouping("b").alias("gb"), grouping("a", "b").alias("gab")]).sort("a", "b").collect() [Row(A=None, B=2, COUNT_C=1, GA=1, GB=0, GAB=2), Row(A=None, B=5, COUNT_C=1, GA=1, GB=0, GAB=2), Row(A=1, B=None, COUNT_C=1, GA=0, GB=1, GAB=1), Row(A=1, B=2, COUNT_C=1, GA=0, GB=0, GAB=0), Row(A=4, B=None, COUNT_C=1, GA=0, GB=1, GAB=1), Row(A=4, B=5, COUNT_C=1, GA=0, GB=0, GAB=0)] groupingrQrrQrrcolumnss rVr,r,s8&7;;~a,;G; * Dw D) DD<)c\|Dcgc]}t|d}}tdg|d|iScc}w)aReturns the first non-NULL expression among its arguments, or NULL if all its arguments are NULL. Example:: >>> df = session.create_dataframe([[1, 2, 3], [None, 2, 3], [None, None, 3], [None, None, None]], schema=['a', 'b', 'c']) >>> df.select(df.a, df.b, df.c, coalesce(df.a, df.b, df.c).as_("COALESCE")).show() ----------------------------------- |"A" |"B" |"C" |"COALESCE" | ----------------------------------- |1 |2 |3 |1 | |NULL |2 |3 |2 | |NULL |NULL |3 |3 | |NULL |NULL |NULL |NULL | ----------------------------------- coalescerQr)rQrexrs rVr1r1s8&344BJ '4A4 * >q >I >> 5r/cr|r td|gnd}t|d}|jd}||_|S)aN Return true if the value in the column is not a number (NaN). Example:: >>> import math >>> df = session.create_dataframe([1.1, math.nan, 2.3], schema=["a"]) >>> df.select(equal_nan(df["a"]).alias("equal_nan")).collect() [Row(EQUAL_NAN=False), Row(EQUAL_NAN=True), Row(EQUAL_NAN=False)] equal_nanNFr})r%r9r4rzrrQrnrrs rVr4r4s?4= kA3 /$Cq+&A +++ &CCH JrYcr|r td|gnd}t|d}|jd}||_|S)aU Return true if the value in the column is null. Example:: >>> from snowflake.snowpark.functions import is_null >>> df = session.create_dataframe([1.2, float("nan"), None, 1.0], schema=["a"]) >>> df.select(is_null("a").as_("a")).collect() [Row(A=False), Row(A=False), Row(A=True), Row(A=False)] is_nullNFr})r%r9r7rzr5s rVr7r7s?2; i! -Cq)$A ))e) $CCH JrYcT|r td|gnd}t|d}| }||_|S)a^Returns the negation of the value in the column (equivalent to a unary minus). Example:: >>> df = session.create_dataframe([[1]], schema=["a"]) >>> df.select(negate(col("a").alias("result"))).show() ------------ |"RESULT" | ------------ |-1 | ------------ negateNr%r9rzr5s rVr9r9/s6 1: h ,tCq(#A "CCH JrYcT|r td|gnd}t|d}|}||_|S)a=Returns the inverse of a boolean expression. Example:: >>> df = session.create_dataframe([[True]], schema=["a"]) >>> df.select(not_(col("a").alias("result"))).show() ------------ |"RESULT" | ------------ |False | ------------ not_Nr:r5s rVr<r<Gs6 /8 fqc *TCq&!A "CCH JrYseedc||rtd|gn|gnd}||n tdd}tdt|||S)zEach call returns a pseudo-random 64-bit integer. Example:: >>> df = session.sql("select 1") >>> df = df.select(random(123).alias("result")) randomNllry)r%rrr)r=rQrnss rVr?r?_sM  HDLbtfE   gh &BA (GAJSI NNrYmin_max_genc |rtd|||gnd}d}||}||}t|ttfr t |dn t |d}t d|||d||S)a+ Returns a uniformly random number. Example:: >>> import datetime >>> df = session.create_dataframe( ... [[1]], ... schema=["a"], ... ) >>> df.select(uniform(1, 100, col("a")).alias("UNIFORM")).collect() [Row(UNIFORM=62)] uniformNct|tr t|dSt|tr&t|dj t dSt |dS)NFr}rE)rintrjfloatcastr?r9)limits rVconvert_limit_to_colz%uniform..convert_limit_to_colsO eS !u. . u %u.33IK53Q QeY//rYFr}Tis_data_generatorrzrQr%rrGrHrjr9r) rArBrCrQrnrKmin_colmax_colgen_cols rVrErEss&@I i$c): ;dC0#4(G"4(G cC< ( C5! C +   rYsigncV|r td|gnd}tdt|d||S)auReturns a sequence of monotonically increasing integers, with wrap-around which happens after largest representable integer of integer width 1 byte. Args: sign: When 0, the sequence continues at 0 after wrap-around. When 1, the sequence continues at smallest representable 1 byte integer. Defaults to 0. See Also: - :meth:`Session.generator`, which can be used to generate in tandem with `seq1` to generate sequences. Example:: >>> df = session.generator(seq1(0), rowcount=3) >>> df.collect() [Row(SEQ1(0)=0), Row(SEQ1(0)=1), Row(SEQ1(0)=2)] seq1NTrLr%rrrRrQrns rVrTrT3$2; ftf -C  C9 rYcV|r td|gnd}tdt|d||S)auReturns a sequence of monotonically increasing integers, with wrap-around which happens after largest representable integer of integer width 2 byte. Args: sign: When 0, the sequence continues at 0 after wrap-around. When 1, the sequence continues at smallest representable 2 byte integer. Defaults to 0. See Also: - :meth:`Session.generator`, which can be used to generate in tandem with `seq2` to generate sequences. Example:: >>> df = session.generator(seq2(0), rowcount=3) >>> df.collect() [Row(SEQ2(0)=0), Row(SEQ2(0)=1), Row(SEQ2(0)=2)] seq2NTrLrUrVs rVrYrYrWrYcV|r td|gnd}tdt|d||S)auReturns a sequence of monotonically increasing integers, with wrap-around which happens after largest representable integer of integer width 4 byte. Args: sign: When 0, the sequence continues at 0 after wrap-around. When 1, the sequence continues at smallest representable 4 byte integer. Defaults to 0. See Also: - :meth:`Session.generator`, which can be used to generate in tandem with `seq4` to generate sequences. Example:: >>> df = session.generator(seq4(0), rowcount=3) >>> df.collect() [Row(SEQ4(0)=0), Row(SEQ4(0)=1), Row(SEQ4(0)=2)] seq4NTrLrUrVs rVr[r[rWrYcV|r td|gnd}tdt|d||S)auReturns a sequence of monotonically increasing integers, with wrap-around which happens after largest representable integer of integer width 8 byte. Args: sign: When 0, the sequence continues at 0 after wrap-around. When 1, the sequence continues at smallest representable 8 byte integer. Defaults to 0. See Also: - :meth:`Session.generator`, which can be used to generate in tandem with `seq8` to generate sequences. Example:: >>> df = session.generator(seq8(0), rowcount=3) >>> df.collect() [Row(SEQ8(0)=0), Row(SEQ8(0)=1), Row(SEQ8(0)=2)] seq8NTrLrUrVs rVr]r]rWrYc6t|d}td||S)zConverts an input expression to a boolean. Example:: >>> df = session.create_dataframe(['yes', 'no'], schema=['a']) >>> df.select(to_boolean(col('a')).as_('ans')).collect() [Row(ANS=True), Row(ANS=False)] to_booleanr}rrs rVr_r_ q,'A ,Y ??rY precisionc |rtd|||gnd}t|d}td|t|dt|d||S)aConverts an input expression to a decimal. Example:: >>> df = session.create_dataframe(['12', '11.3', '-90.12345'], schema=['a']) >>> df.select(to_decimal(col('a'), 38, 0).as_('ans')).collect() [Row(ANS=12), Row(ANS=11), Row(ANS=-90)] >>> df.select(to_decimal(col('a'), 38, 2).as_('ans')).collect() [Row(ANS=Decimal('12.00')), Row(ANS=Decimal('11.30')), Row(ANS=Decimal('-90.12'))] to_decimalNFr}ryr%r9rrj)rrarrQrnrs rVrcrcs] ENL1i*?@SW q,'A   I' EU#   rYfmtc|rtd||gn||gnd}t|d}| t|dnd}|td|||Std||||S)aConverts an input expression to a decimal. Example:: >>> df = session.create_dataframe(['12', '11.3', '-90.12345'], schema=['a']) >>> df.select(to_double(col('a')).as_('ans')).collect() [Row(ANS=12.0), Row(ANS=11.3), Row(ANS=-90.12345)] Example:: >>> df = session.create_dataframe(['12+', '11.3+', '90.12-'], schema=['a']) >>> df.select(to_double(col('a'), "999.99MI").as_('ans')).collect() [Row(ANS=12.0), Row(ANS=11.3), Row(ANS=-90.12)] to_doubleNryr%r9r7r)rrerQrnrfmt_cols rVrgrg+sz$  K !!SJ  q+&A25/nS+.tG ? {AC9EKG# SrYdividenddivisorc|rtd||gnd}t|ttfr t |dn t |d}t|ttfr t |dn t |d}t d||||S)a Performs division like the division operator (/), but returns 0 when the divisor is 0 (rather than reporting an error). Example:: >>> df = session.create_dataframe([1], schema=["a"]) >>> df.select(div0(df["a"], 1).alias("divided_by_one"), div0(df["a"], 0).alias("divided_by_zero")).collect() [Row(DIVIDED_BY_ONE=Decimal('1.000000'), DIVIDED_BY_ZERO=Decimal('0.000000'))] div0NFr}ryrN)rjrkrQrn dividend_col divisor_cols rVrmrmIs"?H fx&9 :TC he - H& Hf - gU| , Gu% GV ,  ky rYct|ttfr t|dn t |d}t|ttfr t|dn t |d}|t |dz }|rt d||g|_|Sd|_|S)aPerforms division like the division operator (/), but returns NULL when the divisor is 0 (rather then reporting error). Example:: >>> df = session.create_dataframe([1], schema=["a"]) >>> df.select(divnull(df["a"], 1).alias("divided_by_one"), divnull(df["a"], 0).alias("divided_by_zero")).collect() [Row(DIVIDED_BY_ONE=Decimal('1.000000'), DIVIDED_BY_ZERO=None)] Fr}divnullN)rrGrHrjr9 nullifzeror%rz)rjrkrQrnrors rVrqrqjs$ he - H& Hi 0 gU| , Gu% GY / K5A AC?HI'':;H JOSH JrYc6t|d}td||S)aReturns NULL if the argument evaluates to 0; otherwise, returns the argument. Example:: >>> df = session.create_dataframe([0, 1], schema=["a"]) >>> df.select(nullifzero(df["a"]).alias("result")).collect() [Row(RESULT=None), Row(RESULT=1)] rrr}rrs rVrrrrr`rYc6t|d}td||S)a!Returns the square-root of a non-negative numeric expression. Example:: >>> df = session.create_dataframe( ... [4, 9], ... schema=["N"], ... ).select(sqrt(col("N"))) >>> df.collect() [Row(SQRT("N")=2.0), Row(SQRT("N")=3.0)] sqrtr}rrs rVrururrYc6t|d}td||S)a@Returns the absolute value of a numeric expression. Example:: >>> df = session.create_dataframe([[-1]], schema=["a"]) >>> df.select(abs(col("a")).alias("result")).show() ------------ |"RESULT" | ------------ |1 | ------------ absr}rrs rVrwrwrrYc6t|d}td||S)aComputes the inverse cosine (arc cosine) of its input; the result is a number in the interval [-pi, pi]. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([[0.5]], schema=["deg"]) >>> df.select(acos(col("deg")).cast(DecimalType(scale=3)).alias("result")).show() ------------ |"RESULT" | ------------ |1.047 | ------------ acosr}rrs rVryry q&!A &!y 99rYc6t|d}td||S)aComputes the inverse sine (arc sine) of its input; the result is a number in the interval [-pi, pi]. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([[1]], schema=["deg"]) >>> df.select(asin(col("deg")).cast(DecimalType(scale=3)).alias("result")).show() ------------ |"RESULT" | ------------ |1.571 | ------------ asinr}rrs rVr|r|rzrYc6t|d}td||S)aComputes the inverse tangent (arc tangent) of its input; the result is a number in the interval [-pi, pi]. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([[1]], schema=["deg"]) >>> df.select(atan(col("deg")).cast(DecimalType(scale=3)).alias("result")).show() ------------ |"RESULT" | ------------ |0.785 | ------------ atanr}rrs rVr~r~rzrYyxcPt|d}t|d}td|||S)aComputes the inverse tangent (arc tangent) of its input; the result is a number in the interval [-pi, pi]. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([[1, 2]], schema=["x", "y"]) >>> df.select(atan2(df.x, df.y).cast(DecimalType(scale=3)).alias("result")).show() ------------ |"RESULT" | ------------ |0.464 | ------------ atan2r}rrrrQy_colx_cols rVrrs- 1g &E 1g &E '5%9 EErYc6t|d}td||S)a'Returns values from the specified column rounded to the nearest equal or larger integer. Example:: >>> df = session.create_dataframe([135.135, -975.975], schema=["a"]) >>> df.select(ceil(df["a"]).alias("ceil")).collect() [Row(CEIL=136.0), Row(CEIL=-975.0)] ceilr}rrs rVrr  q&!A &!y 99rYc6t|d}td||S)aComputes the cosine of its argument; the argument should be expressed in radians. Example: >>> from math import pi >>> df = session.create_dataframe([[pi]], schema=["deg"]) >>> df.select(cos(col("deg")).alias("result")).show() ------------ |"RESULT" | ------------ |-1.0 | ------------ cosr}rrs rVrr rrYc6t|d}td||S)a|Computes the hyperbolic cosine of its argument. Example: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([[0]], schema=["deg"]) >>> df.select(cosh(col("deg")).alias("result")).show() ------------ |"RESULT" | ------------ |1.0 | ------------ coshr}rrs rVrr-  q&!A &!y 99rYc6t|d}td||S)ah Computes Euler's number e raised to a floating-point value. Example:: >>> import math >>> from snowflake.snowpark.types import IntegerType >>> df = session.create_dataframe([0.0, math.log(10)], schema=["a"]) >>> df.select(exp(df["a"]).cast(IntegerType()).alias("exp")).collect() [Row(EXP=1), Row(EXP=10)] expr}rrs rVrr@ s q% A %i 88rYc6t|d}td||S)as Computes the factorial of its input. The input argument must be an integer expression in the range of 0 to 33. Example:: >>> df = session.create_dataframe([0, 1, 5, 10], schema=["a"]) >>> df.select(factorial(df["a"]).alias("factorial")).collect() [Row(FACTORIAL=1), Row(FACTORIAL=1), Row(FACTORIAL=120), Row(FACTORIAL=3628800)] factorialr}rrs rVrrQ  q+&A +qI >>rYc6t|d}td||S)a2 Returns values from the specified column rounded to the nearest equal or smaller integer. Examples:: >>> df = session.create_dataframe([135.135, -975.975], schema=["a"]) >>> df.select(floor(df["a"]).alias("floor")).collect() [Row(FLOOR=135.0), Row(FLOOR=-976.0)] floorr}rrs rVrra s q'"A '1 ::rYdct|d}t||djtd}|rt d||g|_|Sd|_|S)aFormat numbers to a specific number of decimal places with HALF_TO_EVEN rounding. Note: 1. The data type of the expression must be one of the `data types for a fixed-point number `_. 2. Data types for floating point numbers (e.g. FLOAT) are not supported with this argument. 3. If the expression data type is not supported, the expression must be explicitly cast to decimal before calling. Example:: >>> import decimal >>> from snowflake.snowpark.functions import format_number >>> data = [(1, decimal.Decimal(3.14159)), (2, decimal.Decimal(2.71828)), (3, decimal.Decimal(1.41421))] >>> df = session.createDataFrame(data, ["id", "value"]) >>> df.select("id",format_number("value",2).alias("value")).show() ------------------ |"ID" |"VALUE" | ------------------ |1 |3.14 | |2 |2.72 | |3 |1.41 | ------------------ format_numberFr}N)r9rrIrAr%rz)rWrrQrs rVrrq sZ6 o .CsA',,Z\U,KA?H 3( ;AF HOSAF HrYc6t|d}td||S)aComputes the sine of its argument; the argument should be expressed in radians. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.generator(seq1(0), rowcount=3).select(sin(seq1(0)).cast(DecimalType(scale=4))) >>> df.collect() [Row(CAST (SIN(SEQ1(0)) AS NUMBER(38, 4))=Decimal('0.0000')), Row(CAST (SIN(SEQ1(0)) AS NUMBER(38, 4))=Decimal('0.8415')), Row(CAST (SIN(SEQ1(0)) AS NUMBER(38, 4))=Decimal('0.9093'))] sinr}rrs rVrr s q% A %i 88rYc6t|d}td||S)aComputes the hyperbolic sine of its argument. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.generator(seq1(0), rowcount=3).select(sinh(seq1(0)).cast(DecimalType(scale=4))) >>> df.collect() [Row(CAST (SINH(SEQ1(0)) AS NUMBER(38, 4))=Decimal('0.0000')), Row(CAST (SINH(SEQ1(0)) AS NUMBER(38, 4))=Decimal('1.1752')), Row(CAST (SINH(SEQ1(0)) AS NUMBER(38, 4))=Decimal('3.6269'))] sinhr}rrs rVrr s q&!A &!y 99rYc6t|d}td||S)aComputes the tangent of its argument; the argument should be expressed in radians. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([0, 1], schema=["N"]).select( ... tan(col("N")).cast(DecimalType(scale=4)) ... ) >>> df.collect() [Row(CAST (TAN("N") AS NUMBER(38, 4))=Decimal('0.0000')), Row(CAST (TAN("N") AS NUMBER(38, 4))=Decimal('1.5574'))] tanr}rrs rVrr rrYc6t|d}td||S)aComputes the hyperbolic tangent of its argument. Example:: >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([0, 1], schema=["N"]).select( ... tanh(col("N").cast(DecimalType(scale=4))) ... ) >>> df.collect() [Row(TANH( CAST ("N" AS NUMBER(38, 4)))=0.0), Row(TANH( CAST ("N" AS NUMBER(38, 4)))=0.7615941559557649)] tanhr}rrs rVrr rrYc6t|d}td||S)a Converts radians to degrees. Example:: >>> import math >>> from snowflake.snowpark.types import StructType, StructField, DoubleType, IntegerType >>> df = session.create_dataframe( ... [math.pi / 3, math.pi, 3 * math.pi], ... schema=StructType([StructField("a", DoubleType())]), ... ) >>> df.select(degrees(col("a")).cast(IntegerType()).alias("DEGREES")).collect() [Row(DEGREES=60), Row(DEGREES=180), Row(DEGREES=540)] degreesr}rrs rVrr s q)$A )Q) <>> df = session.create_dataframe([[1.111], [2.222], [3.333]], schema=["a"]) >>> df.select(radians(col("a")).cast("number(38, 5)").alias("result")).show() ------------ |"RESULT" | ------------ |0.01939 | |0.03878 | |0.05817 | ------------ radiansr}rrs rVrr s" q)$A )Q) <>> df = session.create_dataframe(["a", "b"], schema=["col"]).select(md5("col")) >>> df.collect() [Row(MD5("COL")='0cc175b9c0f1b6a831c399e269772661'), Row(MD5("COL")='92eb5ffee6ae2fec3ad71c777531578f')] md5r}rrs rVrr s q% A %i 88rYc6t|d}td||S)a`Returns a 40-character hex-encoded string containing the 160-bit SHA-1 message digest. Example:: >>> df = session.create_dataframe(["a", "b"], schema=["col"]).select(sha1("col")) >>> df.collect() [Row(SHA1("COL")='86f7e437faa5a7fce15d1ddcb9eaeaea377667b8'), Row(SHA1("COL")='e9d71f5ee7c92d6dc9e92ffdad17b8bd49418f98')] sha1r}rrs rVrr s q&!A &!y 99rYnum_bitscjgd}||vrtd|d|t|d}td|||S)aReturns a hex-encoded string containing the N-bit SHA-2 message digest, where N is the specified output digest size. Example:: >>> df = session.create_dataframe(["a", "b"], schema=["col"]).select(sha2("col", 256)) >>> df.collect() [Row(SHA2("COL", 256)='ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb'), Row(SHA2("COL", 256)='3e23e8160039594a33894f6564e1b1348bbd7a0088d42c4acb73eeaed59c009d')] )riiz num_bits z is not in the permitted values sha2r}) ValueErrorr9r)rrrQpermitted_valuesrs rVrr sR/''z!ABRAS T   q&!A &!X CCrYc\|Dcgc]}t|d}}tdg|d|iScc}w)a Returns a signed 64-bit hash value. Note that HASH never returns NULL, even for NULL inputs. Examples:: >>> import decimal >>> df = session.create_dataframe([[10, "10", decimal.Decimal(10), 10.0]], schema=["a", "b", "c", "d"]) >>> df.select(hash("a").alias("hash_a"), hash("b").alias("hash_b"), hash("c").alias("hash_c"), hash("d").alias("hash_d")).collect() [Row(HASH_A=1599627706822963068, HASH_B=3622494980440108984, HASH_C=1599627706822963068, HASH_D=1599627706822963068)] >>> df.select(hash(lit(None)).alias("one"), hash(lit(None), lit(None)).alias("two"), hash(lit(None), lit(None), lit(None)).alias("three")).collect() [Row(ONE=8817975702393619368, TWO=953963258351104160, THREE=2941948363845684412)] hashrQrr-s rVrr& s8377Q~a(7G7 & @7 @i @@8r/c6t|d}td||S)aReturns the ASCII code for the first character of a string. If the string is empty, a value of 0 is returned. Example:: >>> df = session.create_dataframe(['!', 'A', 'a', '', 'bcd', None], schema=['a']) >>> df.select(df.a, ascii(df.a).as_('ascii')).collect() [Row(A='!', ASCII=33), Row(A='A', ASCII=65), Row(A='a', ASCII=97), Row(A='', ASCII=0), Row(A='bcd', ASCII=98), Row(A=None, ASCII=None)] asciir}rrs rVrr8  q'"A '1 ::rY delimiterscpt|d}|td||St|d}td|||S)u Returns the input string with the first letter of each word in uppercase and the subsequent letters in lowercase. ``delimiters`` is an optional argument specifying a string of one or more characters that ``initcap`` uses as separators for words in the input expression. If ``delimiters`` is not specified, any of the following characters in the input expressions are treated as word separators: `` ! ? @ " ^ # $ & ~ _ , . : ; + - * % / | \ [ ] ( ) { } < >`` Examples:: >>> df = session.create_dataframe(["the sky is blue", "WE CAN HANDLE THIS", "ÄäÖößÜü", None], schema=["a"]) >>> df.select(initcap(df["a"]).alias("initcap")).collect() [Row(INITCAP='The Sky Is Blue'), Row(INITCAP='We Can Handle This'), Row(INITCAP='Ääöößüü'), Row(INITCAP=None)] >>> df.select(initcap(df["a"], lit('')).alias("initcap")).collect() [Row(INITCAP='The sky is blue'), Row(INITCAP='We can handle this'), Row(INITCAP='Ääöößüü'), Row(INITCAP=None)] initcapr}r)rrrQr delimiter_cols rVrrG sB0 q)$Aii@@":y9M )Q  KKrYc6t|d}td||S)u Returns the length of an input string or binary value. For strings, the length is the number of characters, and UTF-8 characters are counted as a single character. For binary, the length is the number of bytes. Example:: >>> df = session.create_dataframe(["the sky is blue", "WE CAN HANDLE THIS", "ÄäÖößÜü", None], schema=["a"]) >>> df.select(length(df["a"]).alias("length")).collect() [Row(LENGTH=15), Row(LENGTH=18), Row(LENGTH=7), Row(LENGTH=None)] lengthr}rrs rVrrg  q(#A (A ;;rYc6t|d}td||S)u Returns the input string with all characters converted to lowercase. Example:: >>> df = session.create_dataframe(['abc', 'Abc', 'aBC', 'Anführungszeichen', '14.95 €'], schema=["a"]) >>> df.select(lower(col("a"))).collect() [Row(LOWER("A")='abc'), Row(LOWER("A")='abc'), Row(LOWER("A")='abc'), Row(LOWER("A")='anführungszeichen'), Row(LOWER("A")='14.95 €')] lowerr}rrs rVrrx rrYrpadct|d}t|d}|rtd|||gnd}td|t|tr|n t |d|||S)a Left-pads a string with characters from another string, or left-pads a binary value with bytes from another binary value. Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.create_dataframe([["a"], ["b"], ["c"]], schema=["a"]) >>> df.select(lpad(col("a"), 3, lit("k")).alias("result")).show() ------------ |"RESULT" | ------------ |kka | |kkb | |kkc | ------------ lpadNFr}ryr9r%rrr6rjrrrrQrprns rVrr d, q&!AsF#A6? fq#qk 2TC  #v&Cu,E   rY trim_stringcxt|d}| t|dnd}|td|||Std||S)a Removes leading characters, including whitespace, from a string. Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.create_dataframe([["asss"], ["bsss"], ["csss"]], schema=["a"]) >>> df.select(rtrim(col("a"), trim_string=lit("sss")).alias("result")).show() ------------ |"RESULT" | ------------ |a | |b | |c | ------------ ltrimNr}rrrrQrts rVrr sR* q'"A0;0G{G,TA = w1 :GQ) <rYct|d}t|d}|rtd|||gnd}td|t|tr|n t |d|||S)a^Right-pads a string with characters from another string, or right-pads a binary value with bytes from another binary value. When called, `e` is padded to length `len` with characters/bytes from `pad`. Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.create_dataframe([["a"], ["b"], ["c"]], schema=["a"]) >>> df.select(rpad(col("a"), 3, lit("k")).alias("result")).show() ------------ |"RESULT" | ------------ |akk | |bkk | |ckk | ------------ rpadNFr}ryrrs rVrr rrYcxt|d}| t|dnd}|td|||Std||S)aRemoves trailing characters, including whitespace, from a string. Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.create_dataframe([["asss"], ["bsss"], ["csss"]], schema=["a"]) >>> df.select(rtrim(col("a"), trim_string=lit("sss")).alias("result")).show() ------------ |"RESULT" | ------------ |a | |b | |c | ------------ rtrimNr}rrs rVrr sR( q'"A0;0G{G,TA = w1 :GQ) <rYr@ct|d}|rtd||gnd}td|t|tr|n t |d||S)aBuilds a string by repeating the input for the specified number of times. Example:: >>> df = session.create_dataframe([["a"], ["b"], ["c"]], schema=["a"]) >>> df.select(repeat(col("a"), 3).alias("result")).show() ------------ |"RESULT" | ------------ |aaa | |bbb | |ccc | ------------ repeatNFr}ryr)r@rrQrrns rVrr sS" q(#A3< hA /$C  6 "A(?   rYc6t|d}td||S)aReverses the order of characters in a string, or of bytes in a binary value. Example:: >>> df = session.create_dataframe([["Hello"], ["abc"]], schema=["col1"]) >>> df.select(reverse(col("col1"))).show() ----------------------- |"REVERSE(""COL1"")" | ----------------------- |olleH | |cba | ----------------------- reverser}rrWrQs rVrr' s i (C )SI >>rYc6t|d}td||S)aReturns a string that contains a phonetic representation of the input string. Example:: >>> df = session.create_dataframe(["Marsha", "Marcia"], schema=["V"]).select(soundex(col("V"))) >>> df.collect() [Row(SOUNDEX("V")='M620'), Row(SOUNDEX("V")='M620')] soundexr}rrs rVrr; s q)$A )Q) <>> df = session.create_dataframe(['hello', ' world', ' ! '], schema=["a"]) >>> df.collect() [Row(A='hello'), Row(A=' world'), Row(A=' ! ')] >>> df.select(trim(col("a"))).collect() [Row(TRIM("A")='hello'), Row(TRIM("A")='world'), Row(TRIM("A")='!')] Example:: >>> df = session.create_dataframe(['EUR 12.96', '7.89USD', '5.99E'], schema=["a"]) >>> df.select(trim(col("a"), lit("EURUSD ")).as_("ans")).collect() [Row(ANS='12.96'), Row(ANS='7.89'), Row(ANS='5.99')] Example:: >>> df = session.create_dataframe(['abc12 45a 79bc!'], schema=["a"]) >>> df.select(trim(col("a"), lit("abc!")).as_("ans")).collect() [Row(ANS='12 45a 79')] trimNr}rrs rVrrH sR6 q&!A/:/F{F+DA = vq!y9FA ;rYc6t|d}td||S)uReturns the input string with all characters converted to uppercase. Unicode characters are supported. Example:: >>> df = session.create_dataframe(['abc', 'Abc', 'aBC', 'Anführungszeichen', '14.95 €'], schema=["a"]) >>> df.select(upper(col("a"))).collect() [Row(UPPER("A")='ABC'), Row(UPPER("A")='ABC'), Row(UPPER("A")='ABC'), Row(UPPER("A")='ANFÜHRUNGSZEICHEN'), Row(UPPER("A")='14.95 €')] upperr}rrs rVrrl rrYtext delimitercxt|d}| t|dnd}|td|||Std||S)aS Tokenizes the given string using the given set of delimiters and returns the tokens as an array. If either parameter is a NULL, a NULL is returned. An empty array is returned if tokenization produces no tokens. Example:: >>> df = session.create_dataframe( ... [["a.b.c", "."], ["1,2.3", ","]], ... schema=["text", "delimiter"], ... ) >>> df.select(strtok_to_array("text", "delimiter").alias("TIME_FROM_PARTS")).collect() [Row(TIME_FROM_PARTS='[\n "a",\n "b",\n "c"\n]'), Row(TIME_FROM_PARTS='[\n "1",\n "2.3"\n]')] strtok_to_arrayNr}r)rrrQrrs rVrr{ s`" t./A  ! y"34   ! (!Q)D-qI FrYc|r td|nd}fdg}|D] }t|tr|jt |dnb|j j }|jdr|ddn|}|jdr|ddn|}|jt |dt|d}t|trNt|j tr4|jt|j jd d|j|t|d di}||_|S) a Returns an OBJECT constructed with the given columns. Example:: >>> from snowflake.snowpark.functions import struct >>> df = session.createDataFrame([("Bob", 80), ("Alice", None)], ["name", "age"]) >>> res = df.select(struct("age", "name").alias("struct")).show() --------------------- |"STRUCT" | --------------------- |{ | | "age": 80, | | "name": "Bob" | |} | |{ | | "age": null, | | "name": "Alice" | |} | --------------------- structNct|tst|tr|gSt|drg}|D] }||z}|Sy)N__iter__)rstrr6hasattr)objaccinnerObjflatten_col_lists rVrz struct..flatten_col_list sU c3 :c6#:5L S* %C 7,X66 7J &rYFr}"rrrQ)r%rrappendrjrname startswithendswithr9r6rchildrenrrz)rQrrnnew_colsrrrrs @rVrr s02; h -CH d # a  OOCU3 4==%%D#s348D $ c 249D OOC6 7 1h ' a Z u%E OOF1==#9#9!#<N O OOA  %h @% @CCH JrYbasec|rtd||gnd}t|ttfr t |dn t |d}t|ttfr t |dn t |d}t d||||S)a: Returns the logarithm of a numeric expression. Example:: >>> from snowflake.snowpark.types import IntegerType >>> df = session.create_dataframe([1, 10], schema=["a"]) >>> df.select(log(10, df["a"]).cast(IntegerType()).alias("log")).collect() [Row(LOG=0), Row(LOG=1)] logNFr}ryrN)rrrQrnbargs rVrr s"4= edAY /$C dS%L ) DE" D% ( a#u & A Au % %CcY GGrYc|r td|gnd}t|ttfr t |dn t |d}t |dt ddz}t |d}||_|S)z Returns the natural logarithm of (1 + x). Example:: >>> df = session.create_dataframe([0, 1], schema=["a"]) >>> df.select(log1p(df["a"]).alias("log1p")).collect() [Row(LOG1P=0.0), Row(LOG1P=0.6931471805599453)] log1pNFr}rr)r%rrGrHrjr9lnrz)rrQrn one_plus_xrs rVrr st09 gs +dC a#u & A Au %  7+c!u.EEJ Z5 )CCH JrYcVt|}|rtd|g|_|Sd|_|S)z Returns the base-10 logarithm of x. Example:: >>> df = session.create_dataframe([1, 10], schema=["a"]) >>> df.select(log10(df["a"]).alias("log10")).collect() [Row(LOG10=0.0), Row(LOG10=1.0)] log10N)_log10r%rzrrQrs rVrr s5 )C4="7QC0CH JDHCH JrYcVt|}|rtd|g|_|Sd|_|S)z Returns the base-2 logarithm of x. Example:: >>> df = session.create_dataframe([1, 2, 8], schema=["a"]) >>> df.select(log2(df["a"]).alias("log2")).collect() [Row(LOG2=0.0), Row(LOG2=1.0), Row(LOG2=3.0)] log2N)_log2r%rzrs rVrr s5 (C3<"6A3/CH JCGCH JrYctd|dS)NFr}rrs rVrr2 s q!u %%rYctd|dS)N Fr}rrs rVrr8 s r1 &&rYleftrightc|rtd||gnd}t|ttfr t |dn t |d}t|ttfr t |dn t |d}t d||||S)ayReturns a number (left) raised to the specified power (right). Example:: >>> df = session.create_dataframe([[2, 3], [3, 4]], schema=["x", "y"]) >>> df.select(pow(col("x"), col("y")).alias("result")).show() ------------ |"RESULT" | ------------ |8.0 | |81.0 | ------------ powNFr}ryrN)rrrQrnnumberpowers rVrr> s(8A edE] 3dC dS%L ) DE" D% (  ec5\ * EU# E5 ) %SI NNrYc|rtd||gnd}t|d}t|ttfr t |dn t|d}t d||||S)a}Returns rounded values from the specified column. Example:: >>> df = session.create_dataframe([[1.11], [2.22], [3.33]], schema=["a"]) >>> df.select(round(col("a")).alias("result")).show() ------------ |"RESULT" | ------------ |1.0 | |2.0 | |3.0 | ------------ roundNFr}ryr%r9rrGrHrjrrrrQrnr scale_cols rVr r ` sf(7@ g5z 2TCq'"A ec5\ * EU# E7 + '1icY OOrYc6t|d}td||S)av Returns the sign of its argument: - -1 if the argument is negative. - 1 if it is positive. - 0 if it is 0. Args: col: The column to evaluate its sign Example:: >>> df = session.create_dataframe([(-2, 2, 0)], ["a", "b", "c"]) >>> df.select(sign("a").alias("a_sign"), sign("b").alias("b_sign"), sign("c").alias("c_sign")).show() ---------------------------------- |"A_SIGN" |"B_SIGN" |"C_SIGN" | ---------------------------------- |-1 |1 |0 | ---------------------------------- rRr}rrs rVrRrR s, sF#A &!y 99rYrpatterncPt|d}t|d}td|||S)aSplits a given string with a given separator and returns the result in an array of strings. To specify a string separator, use the :func:`lit()` function. Example 1:: >>> df = session.create_dataframe( ... [["many-many-words", "-"], ["hello--hello", "--"]], ... schema=["V", "D"], ... ).select(split(col("V"), col("D"))) >>> df.show() ------------------------- |"SPLIT(""V"", ""D"")" | ------------------------- |[ | | "many", | | "many", | | "words" | |] | |[ | | "hello", | | "hello" | |] | ------------------------- Example 2:: >>> df = session.create_dataframe([["many-many-words"],["hello-hi-hello"]],schema=["V"],) >>> df.select(split(col("V"), lit("-"))).show() ----------------------- |"SPLIT(""V"", '-')" | ----------------------- |[ | | "many", | | "many", | | "words" | |] | |[ | | "hello", | | "hi", | | "hello" | |] | ----------------------- splitr}r)rrrQr@rs rVrr s.^ sG$Aw(A '1a9 ==rYposct|d}|rtd|||gn|||gnd}t|tr|n t |d}|t d||||St|tr|n t |d}t d|||||S)aReturns the portion of the string or binary value str, starting from the character/byte specified by pos, with limited length. The length should be greater than or equal to zero. If the length is a negative number, the function returns an empty string. Note: For ``pos``, 1 is the first character of the string in Snowflake database. :func:`substr` is an alias of :func:`substring`. Example 1:: >>> df = session.create_dataframe( ... ["abc", "def"], ... schema=["S"], ... ) >>> df.select(substring(col("S"), 1, 1)).collect() [Row(SUBSTRING("S", 1, 1)='a'), Row(SUBSTRING("S", 1, 1)='d')] Example 2:: >>> df = session.create_dataframe( ... ["abc", "def"], ... schema=["S"], ... ) >>> df.select(substring(col("S"), 2)).collect() [Row(SUBSTRING("S", 2)='bc'), Row(SUBSTRING("S", 2)='ef')] substringNFr}ryr9r%rr6rjr)rrrrQr@rnrrs rVrr sB sK(A  KS[!Sq#smT  #v&Cu,EA {k1acYOOsF+SSE1JF +q!V# SSrYdelimrc |rtd|||gnd}t|d}td||d}tdtd||dk\rdntd |d|z|dk\r|n td |dd||| S) aD Returns the substring from string ``text`` before ``count`` occurrences of the delimiter ``delim``. If ``count`` is positive, everything to the left of the final delimiter (counting from left) is returned. If ``count`` is negative, everything to the right of the final delimiter (counting from the right) is returned. If ``count`` is zero, returns empty string. Example 1:: >>> df = session.create_dataframe( ... ["a.b.c.d"], ... schema=["S"], ... ).select(substring_index(col("S"), ".", 2).alias("result")) >>> df.show() ------------ |"RESULT" | ------------ |a.b | ------------ Example 2:: >>> df = session.create_dataframe( ... [["a.b.c.d", "."]], ... schema=["S", "delimiter"], ... ).select(substring_index(col("S"), col("delimiter"), 2).alias("result")) >>> df.show() ------------ |"RESULT" | ------------ |a.b | ------------ substring_indexNrFr}array_to_string array_slicer array_sizeryr)rrrrQrnr@ strtok_arrays rVrr sP  -eU/CD  t./A!"3QOL   z  leLuTz  leL    rYsubjectposition parametersc(d}t||}|rt||||g|nd}t|tr|n t |d}t|tr|n t |d} |D cgc]} t | d} } t |||| g| ||dScc} w)aReturns the number of times that a pattern occurs in the subject. Example:: >>> df = session.sql("select * from values('apple'),('banana'),('peach') as T(a)") >>> df.select(regexp_count(col("a"), "a").alias("result")).show() ------------ |"RESULT" | ------------ |1 | |3 | |1 | ------------ regexp_countNFr}ryr) rrrrQr  sql_func_namesubrnpatrrparamss rVr"r"> s.#M - 0C  MC(+PZ+PQ   0'c'U6SC 62(HPU8VC/9 :!c!u% :F : sC '- 479 ;s&Bvalueregexpidxc  |rtd|||gnd}t|d}t|d}t|d}tt d||t dt dt d|dt ddd}||_|S) a> Extract a specific group matched by a regex, from the specified string column. If the regex did not match, or the specified group did not match, an empty string is returned. Example:: >>> from snowflake.snowpark.functions import regexp_extract >>> df = session.createDataFrame([["id_20_30", 10], ["id_40_50", 30]], ["id", "age"]) >>> df.select(regexp_extract("id", r"(\d+)", 1).alias("RES")).show() --------- |"RES" | --------- |20 | |40 | --------- regexp_extractN regexp_substrrrFr})r%r9r7r1rrjrz)r'r(r)rQrnrs rVr+r+h s:  ,ufc.BC  5"2 3E F$4 5F . /C    F F H   B%  AAF HrY replacement occurrencesc|rtd|||||g|nd}d}t||} t|tr|n t |d} t|tr|n t |d} t|tr|n t |d} t|tr|n t |d} |Dcgc]!}t|tr|n t |d#}}t || | | | | g|||dScc}w)aReturns the subject with the specified pattern (or all occurrences of the pattern) either removed or replaced by a replacement string. If no matches are found, returns the original subject. Example:: >>> df = session.create_dataframe( ... [["It was the best of times, it was the worst of times"]], schema=["a"] ... ) >>> df.select(regexp_replace(col("a"), lit("( ){1,}"), lit("")).alias("result")).show() -------------------------------------------- |"RESULT" | -------------------------------------------- |Itwasthebestoftimes,itwastheworstoftimes | -------------------------------------------- regexp_replaceNFr}ryr%r9rr6rjr)rrr.rr/rQr rnr#r$r%reproccrr&s rVr1r1 s@    g{Hk OJ O  %M - 0C0'c'U6SC k6 *   . !62(HPU8VC k6 *   .JTDEZ6 "A(??F sCc3 17 >AY s&&C#c|rtd|||gnd}d}t||}t|tr|n t |d}t|tr|n t |d}t ||||||S)a Removes all occurrences of a specified subject and optionally replaces them with replacement. Example:: >>> df = session.create_dataframe([["apple"], ["apple pie"], ["apple juice"]], schema=["a"]) >>> df.select(replace(col("a"), "apple", "orange").alias("result")).show() ---------------- |"RESULT" | ---------------- |orange | |orange pie | |orange juice | ---------------- replaceNFr}ryr2) rrr.rQrnr#r$r%r3s rVr6r6 s4  I+'FG  M - 0C0'c'U6SC k6 *   . -c3SI VVrY target_expr source_exprc |rtd|||gn|||gnd}t|d}t|d}|.td||t|tr|n t |d||Std||||S)aSearches for ``target_expr`` in ``source_expr`` and, if successful, returns the position (1-based) of the ``target_expr`` in ``source_expr``. Args: target_expr: A string or binary expression representing the value to look for. source_expr: A string or binary expression representing the value to search. position: A number indication the position (1-based) from where to start the search. Defaults to None. Examples:: >>> df = session.create_dataframe(["banana"], schema=['a']) >>> df.select(charindex(lit("an"), df.a, 1).as_("result")).show() ------------ |"RESULT" | ------------ |2 | ------------ >>> df.select(charindex(lit("an"), df.a, 3).as_("result")).show() ------------ |"RESULT" | ------------ |4 | ------------ charindexNFr}ryr%r9rrr6rj)r7r8rrQrnrr@s rVr:r:sR   + &{H5   {K0A{K0A     (F+ X/  KAC9 M rYcollation_specc8t|d}td|||S)u_Returns a copy of the original :class:`Column` with the specified ``collation_spec`` property, rather than the original collation specification property. For details, see the Snowflake documentation on `collation specifications `_. Example:: >>> df = session.create_dataframe(['ñ'], schema=['v']) >>> df.select(df.v == lit('Ñ'), collate(df.v, 'sp-upper') == lit('Ñ')).show() ---------------------------------------------------------- |"(""V"" = 'Ñ')" |"(COLLATE(""V"", 'SP-UPPER') = 'Ñ')" | ---------------------------------------------------------- |False |True | ---------------------------------------------------------- collater}r)rr<rQrs rVr>r>Bs!$ q)$A )Q) LLrYc6t|d}td||S)uReturns the collation specification of expr. Example:: >>> df = session.create_dataframe(['ñ'], schema=['v']) >>> df.select(collation(collate(df.v, 'sp-upper'))).show() ------------------------------------------- |"COLLATION(COLLATE(""V"", 'SP-UPPER'))" | ------------------------------------------- |sp-upper | ------------------------------------------- collationr}rrs rVr@r@X q+&A +qI >>rYc\|Dcgc]}t|d}}tdg|d|iScc}w)aConcatenates one or more strings, or concatenates one or more binary values. If any of the values is null, the result is also null. Example:: >>> df = session.create_dataframe([['Hello', 'World']], schema=['a', 'b']) >>> df.select(concat(df.a, df.b)).show() -------------------------- |"CONCAT(""A"", ""B"")" | -------------------------- |HelloWorld | -------------------------- concatrQrr-s rVrCrCjs8599q~a*9G9 ( BW B BB:r/c\|Dcgc]}t|d}}tdg|d|iScc}w)adConcatenates two or more strings, or concatenates two or more binary values. If any of the values is null, the result is also null. The CONCAT_WS operator requires at least two arguments, and uses the first argument to separate all following arguments. Examples:: >>> from snowflake.snowpark.functions import lit >>> df = session.create_dataframe([['Hello', 'World']], schema=['a', 'b']) >>> df.select(concat_ws(lit(','), df.a, df.b)).show() ---------------------------------- |"CONCAT_WS(',', ""A"", ""B"")" | ---------------------------------- |Hello,World | ---------------------------------- >>> df = session.create_dataframe([['Hello', 'World', ',']], schema=['a', 'b', 'sep']) >>> df.select(concat_ws('sep', df.a, df.b)).show() -------------------------------------- |"CONCAT_WS(""SEP"", ""A"", ""B"")" | -------------------------------------- |Hello,World | -------------------------------------- concat_wsrQrr-s rVrErE|s828<>> df = session.create_dataframe([ ... ['Hello', 'World', None], ... [None, None, None], ... ['Hello', None, None], ... ], schema=['a', 'b', 'c']) >>> df.select(_concat_ws_ignore_nulls(',', df.a, df.b, df.c)).show() ---------------------------------------------------- |"CONCAT_WS_IGNORE_NULLS(',', ""A"",""B"",""C"")" | ---------------------------------------------------- |Hello,World | | | |Hello | ---------------------------------------------------- >>> df.select(_concat_ws_ignore_nulls('--', df.a, df.b, df.c)).show() ----------------------------------------------------- |"CONCAT_WS_IGNORE_NULLS('--', ""A"",""B"",""C"")" | ----------------------------------------------------- |Hello--World | | | |Hello | ----------------------------------------------------- >>> df = session.create_dataframe([ ... (['Hello', 'World', None], None, '!'), ... (['Hi', 'World', "."], "I'm Dad", '.'), ... ], schema=['a', 'b', 'c']) >>> df.select(_concat_ws_ignore_nulls(", ", "a", "b", "c")).show() ----------------------------------------------------- |"CONCAT_WS_IGNORE_NULLS(', ', ""A"",""B"",""C"")" | ----------------------------------------------------- |Hello, World, ! | |Hi, World, ., I'm Dad, . | ----------------------------------------------------- _concat_ws_ignore_nullsN,COLrWrRc6td|tdddS)z9Expects an array and returns an array with nulls removed.filterzx -> NOT IS_NULL_VALUE(x)Fr})rrmrWs rVarray_remove_nullsz3_concat_ws_ignore_nulls..array_remove_nullss#   0E B   rYFr}rQ)r% separatorrQzCONCAT_WS_IGNORE_NULLS('z', ))r%r9join enumerateget_namer6r array_flattenarray_construct_compactrIr=rj_aliasrz) rFrQrrnrr.inamesrNress rVrHrHs%d  5|d|D  FJJ~a!:;JGJ HHIg>> df = session.create_dataframe(["abcdef", "abba"], schema=["a"]) >>> df.select(translate(col("a"), lit("abc"), lit("ABC")).as_("ans")).collect() [Row(ANS='ABCdef'), Row(ANS='ABBA')] >>> df = session.create_dataframe(["file with spaces.txt", "\ttest"], schema=["a"]) >>> df.select(translate(col("a"), lit(" \t"), lit("_")).as_("ans")).collect() [Row(ANS='file_with_spaces.txt'), Row(ANS='test')] translater}r)rZr[r\rQsources rVr^r^s@.C -F$_kBO$_kBO V_o rYstringcPt|d}t|d}td|||S)aReturns if `col` contains `string` for each row. See `CONTAINS ` Example: >>> df = session.create_dataframe([[1,2], [3,4], [5,5] ], schema=["a","b"]) >>> df.select(contains(col("a"), col("b")).alias("result")).show() ------------ |"RESULT" | ------------ |False | |False | |True | ------------ containsr}r)rWr`rQrr@s rVrbrbs- sJ'Avz*A *ai @@rYcPt|d}t|d}td|||S)aLReturns true if col starts with str. Example:: >>> df = session.create_dataframe( ... [["abc", "a"], ["abc", "s"]], ... schema=["S", "P"], ... ).select(startswith(col("S"), col("P"))) >>> df.collect() [Row(STARTSWITH("S", "P")=True), Row(STARTSWITH("S", "P")=False)] rr}rrWrrQrr@s rVrr,s- sL)AsL)A ,1 BBrYcPt|d}t|d}td|||S)a* Returns true if col ends with str. Example:: >>> df = session.create_dataframe(["apple", "banana", "peach"], schema=["a"]) >>> df.select(endswith(df["a"], lit("ana")).alias("endswith")).collect() [Row(ENDSWITH=False), Row(ENDSWITH=True), Row(ENDSWITH=False)] rr}rrds rVrr=s- sJ'AsJ'A *ai @@rY base_exprr insert_exprc |rtd||||gnd}t|d}t|d}td|t|tr|n t |dt|tr|n t |d|||S)a@ Replaces a substring of the specified length, starting at the specified position, with a new string or binary value. Examples:: >>> df = session.create_dataframe(["abc"], schema=["a"]) >>> df.select(insert(df["a"], 1, 2, lit("Z")).alias("insert")).collect() [Row(INSERT='Zc')] insertNFr}ryr;)rfrrrgrQrnrrWs rVririMs*  Hy(FK&PQ  y(+A{H-A  x0c(e6TVV,#f2N  rYstr_exprc|rtd||gnd}t|d}td|t|tr|n t |d||S)aaReturns a left most substring of ``str_expr``. Example:: >>> df = session.create_dataframe([["abc"], ["def"]], schema=["a"]) >>> df.select(left(col("a"), 2).alias("result")).show() ------------ |"RESULT" | ------------ |ab | |de | ------------ rNFr}ryr;rjrrQrnr@s rVrrrsU&>G fx&8 9DCx(A  VV,#f2N   rYc|rtd||gnd}t|d}td|t|tr|n t |d||S)acReturns a right most substring of ``str_expr``. Example:: >>> df = session.create_dataframe([["abc"], ["def"]], schema=["a"]) >>> df.select(right(col("a"), 2).alias("result")).show() ------------ |"RESULT" | ------------ |bc | |ef | ------------ rNFr}ryr;rls rVrrsU&?H g&'9 :TCx)A  VV,#f2N   rYc6t|d}td||S)uConverts a Unicode code point (including 7-bit ASCII) into the character that matches the input Unicode. Example:: >>> df = session.create_dataframe([83, 33, 169, 8364, None], schema=['a']) >>> df.select(df.a, char(df.a).as_('char')).sort(df.a).show() ----------------- |"A" |"CHAR" | ----------------- |NULL |NULL | |33 |! | |83 |S | |169 |© | |8364 |€ | ----------------- charr}rrs rVroros( sF#A &!y 99rYrformatc|rtd||gn||gnd}t|d}|-td|t|tr|n t |d||Std|||S)aConverts a Unicode code point (including 7-bit ASCII) into the character that matches the input Unicode. Example:: >>> df = session.create_dataframe([1, 2, 3, 4], schema=['a']) >>> df.select(to_char(col('a')).as_('ans')).collect() [Row(ANS='1'), Row(ANS='2'), Row(ANS='3'), Row(ANS='4')] Example:: >>> import datetime >>> df = session.create_dataframe([datetime.datetime(2023, 4, 16), datetime.datetime(2017, 4, 3, 2, 59, 37, 153)], schema=['a']) >>> df.select(to_char(col('a')).as_('ans')).collect() [Row(ANS='2023-04-16 00:00:00.000'), Row(ANS='2017-04-03 02:59:37.000')] to_charNFr}ryr;)rrprQrns rVrrrrs.  Ifns1f+N  q)$A      0Fc&E6R   Iqsi H rYc|rtd||gnd}ttt|dtd|d}||_|S)a'Converts an input expression into the corresponding date in the specified date format. Example:: >>> df = session.create_dataframe([("2023-10-10",), ("2022-05-15",), ("invalid",)], schema=['date']) >>> df.select(date_format('date', 'YYYY/MM/DD').as_('formatted_date')).show() -------------------- |"FORMATTED_DATE" | -------------------- |2023/10/10 | |2022/05/15 | |NULL | -------------------- Example:: >>> df = session.create_dataframe([("2023-10-10 15:30:00",), ("2022-05-15 10:45:00",)], schema=['timestamp']) >>> df.select(date_format('timestamp', 'YYYY/MM/DD HH:mi:ss').as_('formatted_ts')).show() ----------------------- |"FORMATTED_TS" | ----------------------- |2023/10/10 15:30:00 | |2022/05/15 10:45:00 | ----------------------- Example:: >>> df = session.sql("select '2023-10-10'::DATE as date_col, '2023-10-10 15:30:00'::TIMESTAMP as timestamp_col") >>> df.select( ... date_format('date_col', 'YYYY/MM/DD').as_('formatted_dt'), ... date_format('timestamp_col', 'YYYY/MM/DD HH:mi:ss').as_('formatted_ts') ... ).show() ---------------------------------------- |"FORMATTED_DT" |"FORMATTED_TS" | ---------------------------------------- |2023/10/10 |2023/10/10 15:30:00 | ---------------------------------------- date_formatNFr})r%rrtry_castrDrz)rrerQrnrs rVrtrtsNX;D maX 6C e,moO  C CH JrYcXt|d}|td|||Std||S)aConverts an input expression into the corresponding time. Example:: >>> df = session.create_dataframe(['04:15:29.999'], schema=['a']) >>> df.select(to_time(col("a"))).collect() [Row(TO_TIME("A")=datetime.time(4, 15, 29, 999000))] to_timer}rrrerQrs rVrwrw%s? q)$A ? y!SI>IqI >rYr6cXt|d}|td|||Std||S)a Converts an input expression into the corresponding timestamp. Per default fmt is set to auto, which makes Snowflake detect the format automatically. With `to_timestamp` strings can be converted to timestamps. The format has to be specified according to the rules set forth in Example:: >>> df = session.create_dataframe(['2019-01-31 01:02:03.004'], schema=['a']) >>> df.select(to_timestamp(col("a")).as_("ans")).collect() [Row(ANS=datetime.datetime(2019, 1, 31, 1, 2, 3, 4000))] >>> df = session.create_dataframe(["2020-05-01 13:11:20.000"], schema=['a']) >>> df.select(to_timestamp(col("a"), lit("YYYY-MM-DD HH24:MI:SS.FF3")).as_("ans")).collect() [Row(ANS=datetime.datetime(2020, 5, 1, 13, 11, 20))] Another option is to convert dates into timestamps Example:: >>> import datetime >>> df = session.createDataFrame([datetime.datetime(2022, 12, 25, 13, 59, 38, 467)], schema=["a"]) >>> df.select(to_timestamp(col("a"))).collect() [Row(TO_TIMESTAMP("A")=datetime.datetime(2022, 12, 25, 13, 59, 38, 467))] >>> df = session.createDataFrame([datetime.date(2023, 3, 1)], schema=["a"]) >>> df.select(to_timestamp(col("a"))).collect() [Row(TO_TIMESTAMP("A")=datetime.datetime(2023, 3, 1, 0, 0))] Integers can be converted into a timestamp as well, by providing optionally a scale as an integer as lined out in . Currently Snowpark does support integers in the range of an 8-byte signed integer only. Example:: >>> df = session.createDataFrame([20, 31536000000], schema=['a']) >>> df.select(to_timestamp(col("a"))).collect() [Row(TO_TIMESTAMP("A")=datetime.datetime(1970, 1, 1, 0, 0, 20)), Row(TO_TIMESTAMP("A")=datetime.datetime(2969, 5, 3, 0, 0))] >>> df.select(to_timestamp(col("a"), lit(9))).collect() [Row(TO_TIMESTAMP("A", 9)=datetime.datetime(1970, 1, 1, 0, 0)), Row(TO_TIMESTAMP("A", 9)=datetime.datetime(1970, 1, 1, 0, 0, 31, 536000))] Larger numbers stored in a string can be also converted via this approach Example:: >>> df = session.createDataFrame(['20', '31536000000', '31536000000000', '31536000000000000'], schema=['a']) >>> df.select(to_timestamp(col("a")).as_("ans")).collect() [Row(ANS=datetime.datetime(1970, 1, 1, 0, 0, 20)), Row(ANS=datetime.datetime(1971, 1, 1, 0, 0)), Row(ANS=datetime.datetime(1971, 1, 1, 0, 0)), Row(ANS=datetime.datetime(1971, 1, 1, 0, 0))] to_timestampr}rrxs rVrzrz9s@^ q.)A ? ~q#CNA CrYc|rtd||gn||gnd}t|d}|td|t|d||Std|||S)aConverts an input expression into the corresponding timestamp without a timezone. Per default fmt is set to auto, which makes Snowflake detect the format automatically. With `to_timestamp` strings can be converted to timestamps. The format has to be specified according to the rules set forth in Example:: >>> import datetime >>> df = session.createDataFrame([datetime.datetime(2022, 12, 25, 13, 59, 38, 467)], schema=["a"]) >>> df.select(to_timestamp_ntz(col("a"))).collect() [Row(TO_TIMESTAMP_NTZ("A")=datetime.datetime(2022, 12, 25, 13, 59, 38, 467))] >>> df = session.createDataFrame([datetime.date(2023, 3, 1)], schema=["a"]) >>> df.select(to_timestamp_ntz(col("a"))).collect() [Row(TO_TIMESTAMP_NTZ("A")=datetime.datetime(2023, 3, 1, 0, 0))] to_timestamp_ntzNryr%r9rr7rrerQrnrs rVr|r|psz.  .s{CQ  q,-A ?   3 2 3   .y Q rYc|rtd||gn||gnd}t|d}|td|t|d||Std|||S)aConverts an input expression into the corresponding timestamp using the local timezone. Per default fmt is set to auto, which makes Snowflake detect the format automatically. With `to_timestamp` strings can be converted to timestamps. The format has to be specified according to the rules set forth in to_timestamp_ltzNryr}r~s rVrrsz  .s{CQ  q,-A ?   3 2 3   .y Q rYc|rtd||gn||gnd}t|d}|td|t|d||Std|||S)aConverts an input expression into the corresponding timestamp with the timezone represented in each row. Per default fmt is set to auto, which makes Snowflake detect the format automatically. With `to_timestamp` strings can be converted to timestamps. The format has to be specified according to the rules set forth in to_timestamp_tzNryr}r~s rVrrsz  -cks3xP  q+,A ?   3 1 2   -qsi P rYtzcx|rtd||gnd}t|d}t|d}tdd||||S)aInterprets an input expression as a UTC timestamp and converts it to the given time zone. Note: Time zone names are case-sensitive. Snowflake does not support the majority of timezone abbreviations (e.g. PDT, EST, etc.). Instead you can specify a time zone name or a link name from release 2021a of the IANA Time Zone Database (e.g. America/Los_Angeles, Europe/London, UTC, Etc/GMT, etc.). See the following for more information: Example:: >>> df = session.create_dataframe(['2019-01-31 01:02:03.004'], schema=['t']) >>> df.select(from_utc_timestamp(col("t"), "America/Los_Angeles").alias("ans")).collect() [Row(ANS=datetime.datetime(2019, 1, 30, 17, 2, 3, 4000))] Example:: >>> df = session.create_dataframe([('2019-01-31 01:02:03.004', "America/Los_Angeles")], schema=['t', 'tz']) >>> df.select(from_utc_timestamp(col("t"), col("tz")).alias("ans")).collect() [Row(ANS=datetime.datetime(2019, 1, 30, 17, 2, 3, 4000))] from_utc_timestampNrUTCryrhrrrQrnrtz_cs rVrrsP4AJ 2QG Example:: >>> df = session.create_dataframe(['2019-01-31 01:02:03.004'], schema=['t']) >>> df.select(to_utc_timestamp(col("t"), "America/Los_Angeles").alias("ans")).collect() [Row(ANS=datetime.datetime(2019, 1, 31, 9, 2, 3, 4000))] Example:: >>> df = session.create_dataframe([('2019-01-31 01:02:03.004', "America/Los_Angeles")], schema=['t', 'tz']) >>> df.select(to_utc_timestamp(col("t"), col("tz")).alias("ans")).collect() [Row(ANS=datetime.datetime(2019, 1, 31, 9, 2, 3, 4000))] to_utc_timestampNrrryrhrs rVrrsO4?H 01b' :TCq,-A "0 1D D%  rYc|rtd||gn||gnd}t|d}|td|||Std|tj|||S)aConverts an input expression into a date. Example:: >>> df = session.create_dataframe(['2013-05-17', '2013-05-17'], schema=['a']) >>> df.select(to_date(col('a')).as_('ans')).collect() [Row(ANS=datetime.date(2013, 5, 17)), Row(ANS=datetime.date(2013, 5, 17))] >>> df = session.create_dataframe(['2013-05-17', '2013-05-17'], schema=['a']) >>> df.select(to_date(col('a'), 'YYYY-MM-DD').as_('ans')).collect() [Row(ANS=datetime.date(2013, 5, 17)), Row(ANS=datetime.date(2013, 5, 17))] >>> df = session.create_dataframe(['2013-05-17', '2013-05-17'], schema=['a']) >>> df.select(to_date(col('a'), 'YYYY-MM-DD').as_('ans')).collect() [Row(ANS=datetime.date(2013, 5, 17)), Row(ANS=datetime.date(2013, 5, 17))] >>> df = session.create_dataframe(['31536000000000', '71536004000000'], schema=['a']) >>> df.select(to_date(col('a')).as_('ans')).collect() [Row(ANS=datetime.date(1971, 1, 1)), Row(ANS=datetime.date(1972, 4, 7))] to_dateNryr%r9rr6_to_exprr~s rVrrst8  Icks3xH  q)$A ; y!#C q&//#.SI rYctd|S)aReturns the current timestamp for the system. Example: >>> import datetime >>> result = session.create_dataframe([1]).select(current_timestamp()).collect() >>> assert isinstance(result[0]["CURRENT_TIMESTAMP()"], datetime.datetime) current_timestampr}r~r}s rVrrJs - CCrYctd|S)zReturns the current date for the system. Example: >>> import datetime >>> result = session.create_dataframe([1]).select(current_date()).collect() >>> assert isinstance(result[0]["CURRENT_DATE()"], datetime.date) current_dater}r~r}s rVrrVrrYctd|S)zReturns the current time for the system. Example: >>> import datetime >>> result = session.create_dataframe([1]).select(current_time()).collect() >>> assert isinstance(result[0]["CURRENT_TIME()"], datetime.time) current_timer}r~r}s rVrrbrrYc6t|d}td||S)a Extracts the hour from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(hour("a")).collect() [Row(HOUR("A")=13), Row(HOUR("A")=1)] hourr}rrs rVrrnrrYc6t|d}td||S)a Extracts the day from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(day("a")).collect() [Row(DAY("A")=1), Row(DAY("A")=21)] dayr}rrs rVrrrrYrpartc|rtd||gn||gnd}t|d}|td|||St|d}td||||S)a Returns the last day of the specified date part for a date or timestamp. Commonly used to return the last day of the month for a date or timestamp. Args: expr: The array column part: The date part used to compute the last day of the given array column, default is "MONTH". Valid values are "YEAR", "MONTH", "QUARTER", "WEEK" or any of their supported variations. Example:: >>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(last_day("a")).collect() [Row(LAST_DAY("A")=datetime.date(2020, 5, 31)), Row(LAST_DAY("A")=datetime.date(2020, 8, 31))] >>> df.select(last_day("a", "YEAR")).collect() [Row(LAST_DAY("A", "YEAR")=datetime.date(2020, 12, 31)), Row(LAST_DAY("A", "YEAR")=datetime.date(2020, 12, 31))] last_dayNryr)rrrQrnexpr_colpart_cols rVrrsj6  J$,T4LQ  dJ/H |j( RRdJ/H *hsi XXrYc6t|d}td||S)a Extracts the minute from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(minute("a")).collect() [Row(MINUTE("A")=11), Row(MINUTE("A")=30)] minuter}rrs rVrr q(#A (A ;;rYdate day_of_weekc|rtd||gnd}t|d}td|tj|||S)a Returns the date of the first specified DOW (day of week) that occurs after the input date. Example:: >>> import datetime >>> df = session.create_dataframe([ ... (datetime.date.fromisoformat("2020-08-01"), "mo"), ... (datetime.date.fromisoformat("2020-12-01"), "we"), ... ], schema=["a", "b"]) >>> df.select(next_day("a", col("b"))).collect() [Row(NEXT_DAY("A", "B")=datetime.date(2020, 8, 3)), Row(NEXT_DAY("A", "B")=datetime.date(2020, 12, 2))] >>> df.select(next_day("a", "fr")).collect() [Row(NEXT_DAY("A", 'FR')=datetime.date(2020, 8, 7)), Row(NEXT_DAY("A", 'FR')=datetime.date(2020, 12, 4))] next_dayNryrrrrQrnrs rVrrsJ*CL j4*= >QUCtZ(A Av{3# rYc|rtd||gnd}t|d}td|tj|||S)a Returns the date of the first specified DOW (day of week) that occurs before the input date. Example:: >>> import datetime >>> df = session.create_dataframe([ ... (datetime.date.fromisoformat("2020-08-01"), "mo"), ... (datetime.date.fromisoformat("2020-12-01"), "we"), ... ], schema=["a", "b"]) >>> df.select(previous_day("a", col("b"))).collect() [Row(PREVIOUS_DAY("A", "B")=datetime.date(2020, 7, 27)), Row(PREVIOUS_DAY("A", "B")=datetime.date(2020, 11, 25))] >>> df.select(previous_day("a", "fr")).collect() [Row(PREVIOUS_DAY("A", 'FR')=datetime.date(2020, 7, 31)), Row(PREVIOUS_DAY("A", 'FR')=datetime.date(2020, 11, 27))] previous_dayNryrrs rVrrsO,ENNT;,?@SW t^,A 6??;7cY rYc6t|d}td||S)a Extracts the second from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(second("a")).collect() [Row(SECOND("A")=20), Row(SECOND("A")=5)] secondr}rrs rVrr rrYc6t|d}td||S)a Extracts the month from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(month("a")).collect() [Row(MONTH("A")=5), Row(MONTH("A")=8)] monthr}rrs rVrrs q'"A '1 ::rYc6t|d}td||S)a Extracts the three-letter month name from the specified date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(monthname("a")).collect() [Row(MONTHNAME("A")='May'), Row(MONTHNAME("A")='Aug')] monthnamer}rrs rVrr/s q+&A +qI >>rYc6t|d}td||S)a Extracts the quarter from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(quarter("a")).collect() [Row(QUARTER("A")=2), Row(QUARTER("A")=3)] quarterr}rrs rVrrBs q)$A )Q) <>> import datetime >>> df = session.create_dataframe([ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ], schema=["a"]) >>> df.select(year("a")).collect() [Row(YEAR("A")=2020), Row(YEAR("A")=2020)] yearr}rrs rVrrUrrY num_bucketsc|rtd||gnd}t|tr t|dn t |d}t |d}t d||||S)a Performs an Iceberg partition bucket transform. This function should only be used in the iceberg_config['partition_by'] parameter when creating Iceberg tables. Example:: >>> iceberg_config = { ... "external_volume": "example_volume", ... "partition_by": [bucket(10, "a")] ... } >>> df.write.save_as_table("my_table", iceberg_config=iceberg_config) # doctest: +SKIP bucketNFr}ryr%rrGrjr9r)rrWrQrns rVrrhsd @I hc(: ;dC k3 ' K5) K 2 h 'C (K3) TTrYwidthc|rtd||gnd}t|tr t|dn t |d}t |d}t d||||S)a Performs an Iceberg partition truncate transform. This function should only be used in the iceberg_config['partition_by'] parameter when creating Iceberg tables. Example:: >>> iceberg_config = { ... "external_volume": "example_volume", ... "partition_by": [truncate(3, "a")] ... } >>> df.write.save_as_table("my_table", iceberg_config=iceberg_config) # doctest: +SKIP truncateNFr}ryr)rrWrQrns rVrrsb >> df = session.create_dataframe([1], schema=["a"]) >>> df.select(sysdate()).collect() is not None True sysdater}r~r}s rVrrs )y 99rYdate1date2cPt|d}t|d}td|||S)a Returns the number of months between two DATE or TIMESTAMP values. Example:: >>> import datetime >>> df = session.create_dataframe([[ ... datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f"), ... datetime.datetime.strptime("2020-08-21 01:30:05.000", "%Y-%m-%d %H:%M:%S.%f") ... ]], schema=["a", "b"]) >>> df.select(months_between("a", "b")).collect() [Row(MONTHS_BETWEEN("A", "B")=Decimal('-3.629452'))] months_betweenr}r)rrrQrrs rVrrs0" / 0B / 0B *Bi HHrYc6t|d}td||S)aParses an input and returns a value of type GEOGRAPHY. Supported inputs are strings in - WKT (well-known text). - WKB (well-known binary) in hexadecimal format (without a leading 0x). - EWKT (extended well-known text). - EWKB (extended well-known binary) in hexadecimal format (without a leading 0x). - GeoJSON. format. Example:: >>> df = session.create_dataframe(['POINT(-122.35 37.55)', 'POINT(20.92 43.33)'], schema=['a']) >>> df.select(to_geography(col("a"))).collect() [Row(TO_GEOGRAPHY("A")='{\n "coordinates": [\n -122.35,\n 37.55\n ],\n "type": "Point"\n}'), Row(TO_GEOGRAPHY("A")='{\n "coordinates": [\n 20.92,\n 43.33\n ],\n "type": "Point"\n}')] Besides strings, binary representation in WKB and EWKB format can be parsed, or objects adhering to GeoJSON format. For all supported formats confer https://docs.snowflake.com/en/sql-reference/data-types-geospatial#supported-geospatial-object-types. to_geographyr}rrs rVrrs( q.)A .!y AArYc6t|d}td||S)aParses an input and returns a value of type GEOMETRY. Supported inputs are strings in - WKT (well-known text). - WKB (well-known binary) in hexadecimal format (without a leading 0x). - EWKT (extended well-known text). - EWKB (extended well-known binary) in hexadecimal format (without a leading 0x). - GeoJSON. format. Example:: >>> df = session.create_dataframe(['POINT(-122.35 37.55)', 'POINT(20.92 43.33)'], schema=['a']) >>> df.select(to_geometry(col("a"))).collect(statement_params={"GEOMETRY_OUTPUT_FORMAT": "WKT"}) [Row(TO_GEOMETRY("A")='POINT(-122.35 37.55)'), Row(TO_GEOMETRY("A")='POINT(20.92 43.33)')] Besides strings, binary representation in WKB and EWKB format can be parsed, or objects adhering to GeoJSON format. For all supported formats confer https://docs.snowflake.com/en/sql-reference/data-types-geospatial#supported-geospatial-object-types. to_geometryr}rrs rVrrs( q-(A -i @@rYarray1array2cPt|d}t|d}td|||S)azCompares whether two ARRAYs have at least one element in common. Returns TRUE if there is at least one element in common; otherwise returns FALSE. The function is NULL-safe, meaning it treats NULLs as known values for comparing equality. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row([1, 2], [1, 3]), Row([1, 2], [3, 4])], schema=["a", "b"]) >>> df.select(arrays_overlap("a", "b").alias("result")).show() ------------ |"RESULT" | ------------ |True | |False | ------------ arrays_overlapr}rrrrQa1a2s rVrrs0(  0 1B  0 1B *Bi HHrYc6t|d}td||S)aThe function excludes any duplicate elements that are present in the input ARRAY. The function is not guaranteed to return the elements in the ARRAY in a specific order. The function is NULL safe, which means that it treats NULLs as known values when identifying duplicate elements. Args: col: The array column Returns: Returns a new ARRAY that contains only the distinct elements from the input ARRAY. Example:: >>> from snowflake.snowpark.functions import array_construct,array_distinct,lit >>> df = session.createDataFrame([["1"]], ["A"]) >>> df = df.withColumn("array", array_construct(lit(1), lit(1), lit(1), lit(2), lit(3), lit(2), lit(2))) >>> df.withColumn("array_d", array_distinct("ARRAY")).show() ----------------------------- |"A" |"ARRAY" |"ARRAY_D" | ----------------------------- |1 |[ |[ | | | 1, | 1, | | | 1, | 2, | | | 1, | 3 | | | 2, |] | | | 3, | | | | 2, | | | | 2 | | | |] | | ----------------------------- array_distinctr}rrs rVrr s"B . /C *C9 EErYcPt|d}t|d}td|||S)aReturns an array that contains the matching elements in the two input arrays. The function is NULL-safe, meaning it treats NULLs as known values for comparing equality. Args: array1: An ARRAY that contains elements to be compared. array2: An ARRAY that contains elements to be compared. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row([1, 2], [1, 3])], schema=["a", "b"]) >>> df.select(array_intersection("a", "b").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 1 | |] | ------------ array_intersectionr}rrs rVrr2s02  4 5B  4 5B .B) LLrY source_arrayarray_of_elements_to_excludeallow_duplicatesc |rtd|||gnd}t|d}t|d}|rtd||||Stdtd|dtd|d||S)aCReturns a new ARRAY that contains the elements from one input ARRAY that are not in another input ARRAY. The function is NULL-safe, meaning it treats NULLs as known values for comparing equality. When allow_duplicates is set to True (default), this function is the same as the Snowflake ARRAY_EXCEPT semantic: This function compares arrays by using multi-set semantics (sometimes called "bag semantics"). If source_array includes multiple copies of a value, the function only removes the number of copies of that value that are specified in array_of_elements_to_exclude. For example, if source_array contains 5 elements with the value 'A' and array_of_elements_to_exclude contains 2 elements with the value 'A', the returned array contains 3 elements with the value 'A'. When allow_duplicates is set to False: This function compares arrays by using set semantics. Specifically, it will first do an element deduplication for both arrays, and then compute the array_except result. For example, if source_array contains 5 elements with the value 'A' and array_of_elements_to_exclude contains 2 elements with the value 'A', the returned array is empty. Args: source_array: An array that contains elements to be included in the new ARRAY. array_of_elements_to_exclude: An array that contains elements to be excluded from the new ARRAY. allow_duplicates: If True, we use multi-set semantic. Otherwise use set semantic. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(["A", "B"], ["B", "C"])], schema=["source_array", "array_of_elements_to_exclude"]) >>> df.select(array_except("source_array", "array_of_elements_to_exclude").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | "A" | |] | ------------ >>> df = session.create_dataframe([Row(["A", "B", "B", "B", "C"], ["B"])], schema=["source_array", "array_of_elements_to_exclude"]) >>> df.select(array_except("source_array", "array_of_elements_to_exclude").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | "A", | | "B", | | "B", | | "C" | |] | ------------ >>> df = session.create_dataframe([Row(["A", None, None], ["B", None])], schema=["source_array", "array_of_elements_to_exclude"]) >>> df.select(array_except("source_array", "array_of_elements_to_exclude").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | "A", | | null | |] | ------------ >>> df = session.create_dataframe([Row([{'a': 1, 'b': 2}, 1], [{'a': 1, 'b': 2}, 3])], schema=["source_array", "array_of_elements_to_exclude"]) >>> df.select(array_except("source_array", "array_of_elements_to_exclude").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 1 | |] | ------------ >>> df = session.create_dataframe([Row(["A", "B"], None)], schema=["source_array", "array_of_elements_to_exclude"]) >>> df.select(array_except("source_array", "array_of_elements_to_exclude").alias("result")).show() ------------ |"RESULT" | ------------ |NULL | ------------ >>> df = session.create_dataframe([Row(["A", "B"], ["B", "C"])], schema=["source_array", "array_of_elements_to_exclude"]) >>> df.select(array_except("source_array", "array_of_elements_to_exclude", False).alias("result")).show() ------------ |"RESULT" | ------------ |[ | | "A" | |] | ------------ >>> df = session.create_dataframe([Row(["A", "B", "B", "B", "C"], ["B"])], schema=["source_array", "array_of_elements_to_exclude"]) >>> df.select(array_except("source_array", "array_of_elements_to_exclude", False).alias("result")).show() ------------ |"RESULT" | ------------ |[ | | "A", | | "C" | |] | ------------ >>> df = session.create_dataframe([Row(["A", None, None], ["B", None])], schema=["source_array", "array_of_elements_to_exclude"]) >>> df.select(array_except("source_array", "array_of_elements_to_exclude", False).alias("result")).show() ------------ |"RESULT" | ------------ |[ | | "A" | |] | ------------ array_exceptNryrFr}r)rrrrQrnrrs rVrrPsz    79I J  L. 9F 8. IF  ~vvC9U   +Vu E +Vu E   rYr%c6t|d}td||S)aReturns smallest defined non-NULL element in the input array. If the input array is empty, or there is no defined element in the input array, then the function returns NULL. Args: array: the input array Returns: a VARIANT containing the smallest defined element in the array, or NULL Examples:: Behavior with SQL nulls: >>> df = session.sql("select array_construct(20, 0, null, 10) as A") >>> df.select(array_min(df.a).as_("min_a")).collect() [Row(MIN_A='0')] >>> df = session.sql("select array_construct() as A") >>> df.select(array_min(df.a).as_("min_a")).collect() [Row(MIN_A=None)] >>> df = session.sql("select array_construct(null, null, null) as A") >>> df.select(array_min(df.a).as_("min_a")).collect() [Row(MIN_A=None)] Behavior with JSON nulls: >>> df = session.create_dataframe([[[None, None, None]]], schema=["A"]) >>> df.select(array_min(df.a).as_("min_a")).collect() [Row(MIN_A='null')] array_minr}rr%rQs rVrr: 5+ .E +u BBrYc6t|d}td||S)aOReturns largest defined non-NULL element in the input array. If the input array is empty, or there is no defined element in the input array, then the function returns NULL. Args: array: the input array Returns: a VARIANT containing the largest defined element in the array, or NULL Examples:: Behavior with SQL nulls: >>> df = session.sql("select array_construct(20, 0, null, 10) as A") >>> df.select(array_max(df.a).as_("max_a")).collect() [Row(MAX_A='20')] >>> df = session.sql("select array_construct() as A") >>> df.select(array_max(df.a).as_("max_a")).collect() [Row(MAX_A=None)] >>> df = session.sql("select array_construct(null, null, null) as A") >>> df.select(array_max(df.a).as_("max_a")).collect() [Row(MAX_A=None)] Behavior with JSON nulls: >>> df = session.create_dataframe([[[None, None, None]]], schema=["A"]) >>> df.select(array_max(df.a).as_("max_a")).collect() [Row(MAX_A='null')] array_maxr}rrs rVrrrrYc6t|d}td||S)aReturns a single array from an array or arrays. If the array is nested more than two levels deep, then only a single level of nesting is removed. Must enable parameter `ENABLE_ARRAY_FLATTEN_FUNCTION` in your session. Args: array: the input array rTr}rrs rVrTrT"s 5/ 2E /5I FFrYc6t|d}td||S)aoReturns an array with the elements of the input array in reverse order. Args: col: The source array. Example:: >>> df = session.sql("select [1, 2, 3, 4] :: ARRAY(INT) as A") >>> df.select(array_reverse("A")).show() -------------------------- |"ARRAY_REVERSE(""A"")" | -------------------------- |[ | | 4, | | 3, | | 2, | | 1 | |] | -------------------------- array_reverser}r)rWrQr%s rVrr0s, 3 0E /5I FFrYsort_ascending nulls_firstc |rtd|||gnd}t|d}td|t|dt|d||S)aP Returns rows of array column in sorted order. Users can choose the sort order and decide where to keep null elements. Args: array: name of the column or column element which describes the column sort_ascending: Boolean that decides if array elements are sorted in ascending order. Defaults to True. nulls_first: Boolean that decides if SQL null elements will be placed in the beginning of the array. Note that this does not affect JSON null. Defaults to False. Examples:: Behavior with SQL nulls: >>> df = session.sql("select array_construct(20, 0, null, 10) as A") >>> df.select(array_sort(df.a).as_("sorted_a")).show() --------------- |"SORTED_A" | --------------- |[ | | 0, | | 10, | | 20, | | undefined | |] | --------------- >>> df.select(array_sort(df.a, False).as_("sorted_a")).show() --------------- |"SORTED_A" | --------------- |[ | | 20, | | 10, | | 0, | | undefined | |] | --------------- >>> df.select(array_sort(df.a, False, True).as_("sorted_a")).show() ---------------- |"SORTED_A" | ---------------- |[ | | undefined, | | 20, | | 10, | | 0 | |] | ---------------- Behavior with JSON nulls: >>> df = session.create_dataframe([[[20, 0, None, 10]]], schema=["a"]) >>> df.select(array_sort(df.a, False, False).as_("sorted_a")).show() -------------- |"SORTED_A" | -------------- |[ | | null, | | 20, | | 10, | | 0 | |] | -------------- >>> df.select(array_sort(df.a, False, True).as_("sorted_a")).show() -------------- |"SORTED_A" | -------------- |[ | | null, | | 20, | | 10, | | 0 | |] | -------------- See Also: - https://docs.snowflake.com/en/user-guide/semistructured-considerations#null-values - :func:`~snowflake.snowpark.functions.sort_array` which is an alias of :meth:`~snowflake.snowpark.functions.array_sort`. array_sortNFr}ryrd)r%rrrQrns rVrrJs^t  L5.+*NO  5, /E   Ne, K5)   rYkeysvaluescPt|d}t|d}td|||S)aReturns an object constructed from 2 arrays. Args: keys: The column containing keys of the object. values: The column containing values of the object. Examples:: >>> df = session.sql("select array_construct('10', '20', '30') as A, array_construct(10, 20, 30) as B") >>> df.select(arrays_to_object(df.a, df.b).as_("object")).show() --------------- |"OBJECT" | --------------- |{ | | "10": 10, | | "20": 20, | | "30": 30 | |} | --------------- >>> df = session.create_dataframe([[["a"], [1]], [["b", "c"],[2, 3]]], schema=["k", "v"]) >>> df.select(arrays_to_object(df.k, df.v).as_("objects")).show() ------------- |"OBJECTS" | ------------- |{ | | "a": 1 | |} | |{ | | "b": 2, | | "c": 3 | |} | ------------- See Also: - https://docs.snowflake.com/en/sql-reference/data-types-semistructured#label-data-type-object for information on Objects arrays_to_objectr}r)rrrQkeys_cvalues_cs rVrrs1PD"4 5Ff&89H ,fh) TTrYc\|Dcgc]}t|d}}tdg|d|iScc}w)aLReturns an array of structured objects, where the N-th object contains the N-th elements of the input arrays. Args: cols: The columns to zip together. Returns: A new array of structured objects. Examples:: >>> df = session.sql("select array_construct('10', '20', '30') as A, array_construct(10, 20, 30) as B") >>> df.select(arrays_zip(df.a, df.b).as_("zipped")).show(statement_params={"enable_arrays_zip_function": "TRUE"}) ------------------- |"ZIPPED" | ------------------- |[ | | { | | "$1": "10", | | "$2": 10 | | }, | | { | | "$1": "20", | | "$2": 20 | | }, | | { | | "$1": "30", | | "$2": 30 | | } | |] | ------------------- >>> df = session.sql("select array_construct('10', '20', '30') as A, array_construct(1, 2) as B, array_construct(1.1) as C") >>> df.select(arrays_zip(df.a, df.b, df.c).as_("zipped")).show(statement_params={"enable_arrays_zip_function": "TRUE"}) ------------------- |"ZIPPED" | ------------------- |[ | | { | | "$1": "10", | | "$2": 1, | | "$3": 1.1 | | }, | | { | | "$1": "20", | | "$2": 2, | | "$3": null | | }, | | { | | "$1": "30", | | "$2": null, | | "$3": null | | } | |] | ------------------- arrays_ziprQr)rQrrs rVrrs9r6: :N1l + :D : , C C CC ;r/startstopstepct|d}t|d}|td|||St|d}td||||S)aGenerate a range of integers from `start` to `stop`, incrementing by `step`. If `step` is not set, incrementing by 1. Args: start: the column that contains the integer to start with (inclusive). stop: the column that contains the integer to stop (exclusive). step: the column that contains the integer to increment. Example:: >>> from snowflake.snowpark import Row >>> df1 = session.create_dataframe([(-2, 2)], ["a", "b"]) >>> df1.select(array_generate_range("a", "b").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | -2, | | -1, | | 0, | | 1 | |] | ------------ >>> df2 = session.create_dataframe([(4, -4, -2)], ["a", "b", "c"]) >>> df2.select(array_generate_range("a", "b", "c").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 4, | | 2, | | 0, | | -2 | |] | ------------ array_generate_ranger}r)rrrrQ start_colstop_colstep_cols rVrrsaXu&<=Id$:;H | "Ix9  d$:;H  8X rYcN|rtd|||gn|||gnd}t|d}t|d}|5ttd||z ddkDddd}td |||z||| St|d}ttd|ddkDddd}td |||z||| S) aGenerate a sequence of integers from `start` to `stop`, incrementing by `step`. If `step` is not set, incrementing by 1 if start is less than or equal to stop, otherwise -1. Args: start: the column that contains the integer to start with (inclusive). stop: the column that contains the integer to stop (inclusive). step: the column that contains the integer to increment. Example:: >>> from snowflake.snowpark import Row >>> df1 = session.create_dataframe([(-2, 2)], ["a", "b"]) >>> df1.select(sequence("a", "b").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | -2, | | -1, | | 0, | | 1, | | 2 | |] | ------------ >>> df2 = session.create_dataframe([(4, -4, -2)], ["a", "b", "c"]) >>> df2.select(sequence("a", "b", "c").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 4, | | 2, | | 0, | | -2, | | -4 | |] | ------------ sequenceNrRFr}rrrrry)r%r9rr) rrrrQrnrrr step_signs rVrrTsh    E4;N  uj1IdJ/H | 68i#75 IA M     "  tO    dJ/Hvx59A=q"PUI 9   rY num_of_daysc|rtd||gnd}t|d}t|tr t |dn t|d}t d||d}||_|S)a. Adds a number of days to a date column. Args: col: The column to add to. num_of_days: The number of days to add. Example:: >>> from snowflake.snowpark.functions import date_add, to_date >>> df = session.createDataFrame([("1976-01-06")], ["date"]) >>> df = df.withColumn("date", to_date("date")) >>> res = df.withColumn("date", date_add("date", 4)).show() -------------- |"DATE" | -------------- |1976-01-10 | -------------- date_addNFr}rr%r9rrGrjdateaddrzrWrrQrnrs rVrrsp2BK j3 *< =PTC j )C k3 ' K5) K 4 %cU ;CCH JrYc|rtd||gnd}t|d}t|tr t |dn t|d}t dd|z|d}||_|S)a; Subtracts a number of days from a date column. Args: col: The column to subtract from. num_of_days: The number of days to subtract. Example:: >>> from snowflake.snowpark.functions import date_sub, to_date >>> df = session.createDataFrame([("1976-01-06")], ["date"]) >>> df = df.withColumn("date", to_date("date")) >>> df.withColumn("date", date_sub("date", 2)).show() -------------- |"DATE" | -------------- |1976-01-04 | -------------- date_subNFr}rrrrs rVrrsu2BK j3 *< =PTC j )C k3 ' K5) K 4 %k)3% @CCH JrYrrct|ts tdt|d}t|d}t d||||S)aCalculates the difference between two date, time, or timestamp columns based on the date or time part requested, and returns result of ``col2 - col1`` based on the requested date or time part. `Supported date and time parts `_ Example:: >>> # year difference between two date columns >>> import datetime >>> date_df = session.create_dataframe([[datetime.date(2020, 1, 1), datetime.date(2021, 1, 1)]], schema=["date_col1", "date_col2"]) >>> date_df.select(datediff("year", col("date_col1"), col("date_col2")).alias("year_diff")).show() --------------- |"YEAR_DIFF" | --------------- |1 | --------------- Args: part: The time part to use for calculating the difference col1: The first timestamp column or subtrahend in the datediff col2: The second timestamp column or the minuend in the datediff See Also: - `Snowflake Datediff `_ part must be a stringdatediffr}rrrr9rrrrrQrrs rVrrsE< dC 011 j )B j )B *dBi HHrYc|rtd||gnd}t|d}t|d}tdtdd||||S)aCalculates the difference between two dates, or timestamp columns based in days. The result will reflect the difference between ``col1 - col2`` Example:: >>> from snowflake.snowpark.functions import daydiff, to_date >>> df = session.createDataFrame([("2015-04-08", "2015-05-10")], ["d1", "d2"]) >>> res = df.select(daydiff(to_date(df.d2), to_date(df.d1)).alias("diff")).show() ---------- |"DIFF" | ---------- |32 | ---------- daydiffNrrFr}ryrd)rrrQrns rVrr!sX";D i$ 6C $ *D $ *D  EU#    rYc|rtd||gnd}t|d}t|ttfr t |dn t|d}t d||||S)aRounds the input expression down to the nearest (or equal) integer closer to zero, or to the nearest equal or smaller value with the specified number of places after the decimal point. Example:: >>> df = session.createDataFrame([-1.0, -0.9, -.5, -.2, 0.0, 0.2, 0.5, 0.9, 1.1, 3.14159], schema=["a"]) >>> df.select(trunc(col("a"))).collect() [Row(TRUNC("A", 0)=-1.0), Row(TRUNC("A", 0)=0.0), Row(TRUNC("A", 0)=0.0), Row(TRUNC("A", 0)=0.0), Row(TRUNC("A", 0)=0.0), Row(TRUNC("A", 0)=0.0), Row(TRUNC("A", 0)=0.0), Row(TRUNC("A", 0)=0.0), Row(TRUNC("A", 0)=1.0), Row(TRUNC("A", 0)=3.0)] >>> df = session.createDataFrame([-1.323, 4.567, 0.0123], schema=["a"]) >>> df.select(trunc(col("a"), lit(0))).collect() [Row(TRUNC("A", 0)=-1.0), Row(TRUNC("A", 0)=4.0), Row(TRUNC("A", 0)=0.0)] >>> df.select(trunc(col("a"), lit(1))).collect() [Row(TRUNC("A", 1)=-1.3), Row(TRUNC("A", 1)=4.5), Row(TRUNC("A", 1)=0.0)] >>> df.select(trunc(col("a"), lit(2))).collect() [Row(TRUNC("A", 2)=-1.32), Row(TRUNC("A", 2)=4.56), Row(TRUNC("A", 2)=0.01)] Note that the function ``trunc`` is overloaded with ``date_trunc`` for datetime types. It allows to round datetime objects. Example:: >>> import datetime >>> df = session.createDataFrame([datetime.date(2022, 12, 25), datetime.date(2022, 1, 10), datetime.date(2022, 7, 7)], schema=["a"]) >>> df.select(trunc(col("a"), lit("QUARTER"))).collect() [Row(TRUNC("A", 'QUARTER')=datetime.date(2022, 10, 1)), Row(TRUNC("A", 'QUARTER')=datetime.date(2022, 1, 1)), Row(TRUNC("A", 'QUARTER')=datetime.date(2022, 7, 1))] >>> df = session.createDataFrame([datetime.datetime(2022, 12, 25, 13, 59, 38, 467)], schema=["a"]) >>> df.collect() [Row(A=datetime.datetime(2022, 12, 25, 13, 59, 38, 467))] >>> df.select(trunc(col("a"), lit("MINUTE"))).collect() [Row(TRUNC("A", 'MINUTE')=datetime.datetime(2022, 12, 25, 13, 59))] truncNFr}ryr r s rVrr@sgP7@ g5z 2TCq'"A ec5\ * EU# E7 + '1icY OOrYct|ts tdt|d}t|d}t d||||S)a2Adds the specified value for the specified date or time part to date or time expr. `Supported date and time parts `_ Example:: >>> # add one year on dates >>> import datetime >>> date_df = session.create_dataframe([[datetime.date(2020, 1, 1)]], schema=["date_col"]) >>> date_df.select(dateadd("year", lit(1), col("date_col")).alias("year_added")).show() ---------------- |"YEAR_ADDED" | ---------------- |2021-01-01 | ---------------- >>> date_df.select(dateadd("month", lit(1), col("date_col")).alias("month_added")).show() ----------------- |"MONTH_ADDED" | ----------------- |2020-02-01 | ----------------- >>> date_df.select(dateadd("day", lit(1), col("date_col")).alias("day_added")).show() --------------- |"DAY_ADDED" | --------------- |2020-01-02 | --------------- Args: part: The time part to use for the addition col1: The first timestamp column or addend in the dateadd col2: The second timestamp column or the addend in the dateadd rrr}rrs rVrrssFP dC 011 i (B i (B )T2rY GGrYcnt|ts tdt|d}t d|||S)a& Extracts the specified date or time part from a date, time, or timestamp. See `DATE_PART `_ for details. Args: part: The time part to use for the addition. e: The column expression of a date, time, or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe([[datetime.datetime(2023, 1, 1, 1, 1, 1)]], schema=["ts_col"]) >>> df.select(date_part("year", col("ts_col")).alias("year"), date_part("epoch_second", col("ts_col")).alias("epoch_second")).show() --------------------------- |"YEAR" |"EPOCH_SECOND" | --------------------------- |2023 |1672534861 | --------------------------- r date_partr}r)rrrQrs rVrrs7, dC 011q+&A +tQ) DDrYmc|rtd|||gnd}t|d}t|d}t|d}td|||||S)a  Creates a date from individual numeric components that represent the year, month, and day of the month. Example:: >>> df = session.create_dataframe([[2022, 4, 1]], schema=["year", "month", "day"]) >>> df.select(date_from_parts("year", "month", "day")).collect() [Row(DATE_FROM_PARTS("YEAR", "MONTH", "DAY")=datetime.date(2022, 4, 1))] >>> session.table("dual").select(date_from_parts(2022, 4, 1)).collect() [Row(DATE_FROM_PARTS(2022, 4, 1)=datetime.date(2022, 4, 1))] date_from_partsNry)r%r:r)rrrrQrnrm_cold_cols rVr r s_$@I /!Q ;dC !!%6 7E !!%6 7E !!%6 7E 5%SI rYcnt|ts tdt|d}t d|||S)a Truncates a DATE, TIME, or TIMESTAMP to the specified precision. Note that truncation is not the same as extraction. For example: - Truncating a timestamp down to the quarter returns the timestamp corresponding to midnight of the first day of the quarter for the input timestamp. - Extracting the quarter date part from a timestamp returns the quarter number of the year in the timestamp. Example:: >>> import datetime >>> df = session.create_dataframe( ... [[datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f")]], ... schema=["a"], ... ) >>> df.select(date_trunc("YEAR", "a"), date_trunc("MONTH", "a"), date_trunc("DAY", "a")).collect() [Row(DATE_TRUNC('YEAR', "A")=datetime.datetime(2020, 1, 1, 0, 0), DATE_TRUNC('MONTH', "A")=datetime.datetime(2020, 5, 1, 0, 0), DATE_TRUNC('DAY', "A")=datetime.datetime(2020, 5, 1, 0, 0))] >>> df.select(date_trunc("HOUR", "a"), date_trunc("MINUTE", "a"), date_trunc("SECOND", "a")).collect() [Row(DATE_TRUNC('HOUR', "A")=datetime.datetime(2020, 5, 1, 13, 0), DATE_TRUNC('MINUTE', "A")=datetime.datetime(2020, 5, 1, 13, 11), DATE_TRUNC('SECOND', "A")=datetime.datetime(2020, 5, 1, 13, 11, 20))] >>> df.select(date_trunc("QUARTER", "a")).collect() [Row(DATE_TRUNC('QUARTER', "A")=datetime.datetime(2020, 4, 1, 0, 0))] r date_truncr}r)rrrQrs rVr r s7. dC 011dL1H ,h) LLrYc6t|d}td||S)a Extracts the three-letter day-of-week name from the specified date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe( ... [[datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f")]], ... schema=["a"], ... ) >>> df.select(dayname("a")).collect() [Row(DAYNAME("A")='Fri')] daynamer}rrs rVrrs q)$A )Q) <>> import datetime >>> df = session.create_dataframe( ... [[datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f")]], ... schema=["a"], ... ) >>> df.select(dayofmonth("a")).collect() [Row(DAYOFMONTH("A")=1)] dayofmonthr}rrs rVrr s q,'A ,Y ??rYc6t|d}td||S)a Extracts the corresponding day (number) of the week from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe( ... [[datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f")]], ... schema=["a"], ... ) >>> df.select(dayofweek("a")).collect() [Row(DAYOFWEEK("A")=5)] dayofweekr}rrs rVrrrArYc6t|d}td||S)a Extracts the corresponding day (number) of the year from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe( ... [[datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f")]], ... schema=["a"], ... ) >>> df.select(dayofyear("a")).collect() [Row(DAYOFYEAR("A")=122)] dayofyearr}rrs rVrr-rArY time_columnwindow_durationslide_duration start_timec j|r td|rtd||g|gn|gz|gn|gznd}tddjt t j d}t|d}t|\}}t|d}|d}|} |r%t|\} } | td i| d| id diz } tt|| |d|z d} t|| |z| d} ttd d| td dt||| ddjd}||_|S) aI Converts a time column into a window object with start and end times. Window start times are inclusive while end times are exclusive. For example 9:30 is in the window [9:30, 10:00), but not [9:00, 9:30). Args: time_column: The column to apply the window transformation to. window_duration: An interval string that determines the length of each window. slide_duration: An interval string representing the amount of time in-between the start of each window. Note that this parameter is not supported yet. Specifying it will raise a NotImplementedError exception. start_time: An interval string representing the amount of time the start of each window is offset. eg. a five minute window with start_time of '2 minutes' will be from [9:02, 9:07) instead of [9:00, 9:05) Note: Interval strings are of the form 'quantity unit' where quantity is an integer and unitis is a supported time unit. This function supports the same time units as dateadd. see `supported time units `_ for more information. Example:: >>> import datetime >>> from snowflake.snowpark.functions import window >>> df = session.createDataFrame( ... [(datetime.datetime.strptime("2024-10-31 09:05:00.000", "%Y-%m-%d %H:%M:%S.%f"),)], ... schema=["time"] ... ) >>> df.select(window(df.time, "5 minutes")).show() ---------------------------------------- |"WINDOW" | ---------------------------------------- |{ | | "end": "2024-10-31 09:10:00.000", | | "start": "2024-10-31 09:05:00.000" | |} | ---------------------------------------- >>> df.select(window(df.time, "5 minutes", start_time="2 minutes")).show() ---------------------------------------- |"WINDOW" | ---------------------------------------- |{ | | "end": "2024-10-31 09:07:00.000", | | "start": "2024-10-31 09:02:00.000" | |} | ---------------------------------------- Example:: >>> import datetime >>> from snowflake.snowpark.functions import sum, window >>> df = session.createDataFrame([ ... (datetime.datetime(2024, 10, 31, 1, 0, 0), 1), ... (datetime.datetime(2024, 10, 31, 2, 0, 0), 1), ... (datetime.datetime(2024, 10, 31, 3, 0, 0), 1), ... (datetime.datetime(2024, 10, 31, 4, 0, 0), 1), ... (datetime.datetime(2024, 10, 31, 5, 0, 0), 1), ... ], schema=["time", "value"] ... ) >>> df.group_by(window(df.time, "2 hours")).agg(sum(df.value)).sort("window").show() ------------------------------------------------------- |"WINDOW" |"SUM(VALUE)" | ------------------------------------------------------- |{ |1 | | "end": "2024-10-31 02:00:00.000", | | | "start": "2024-10-31 00:00:00.000" | | |} | | |{ |2 | | "end": "2024-10-31 04:00:00.000", | | | "start": "2024-10-31 02:00:00.000" | | |} | | |{ |2 | | "end": "2024-10-31 06:00:00.000", | | | "start": "2024-10-31 04:00:00.000" | | |} | | ------------------------------------------------------- zRsnowflake.snowpark.functions.window does not support slide_duration parameter yet.windowNz1970-01-01 00:00:00Fr})timezoner@rQrendrT)NotImplementedErrorr%rjrIrDrCNTZr9r- make_intervalrrrrrVrz)rrrrrQrnepochtime window_unitrstart_duration start_unitr window_startrs rVrr?sr" `      / *#+r.1A C'rj\ ;  % 7 < <0445 = E +x 0D#8#I O[/U;O M#K D%::%F"  TJ BTeTT dDE:_LF;(@$RWXL $ Gu% EU# _leL    fX CH JrYc6t|d}td||S)aS Returns true if the specified VARIANT column contains an ARRAY value. Examples:: >>> df = session.create_dataframe([[["element"], True]], schema=["a", "b"]) >>> df.select(is_array(df["a"]).alias("is_array_a"), is_array(df["b"]).alias("is_array_b")).collect() [Row(IS_ARRAY_A=True, IS_ARRAY_B=False)] is_arrayr}rrs rVr(r(s sJ'A *a9 ==rYc6t|d}td||S)a Returns true if the specified VARIANT column contains a boolean value. Examples:: >>> from snowflake.snowpark.types import StructField, VariantType >>> df = session.create_dataframe([[True, 'X']], schema=["a", "b"]) >>> df.select(is_boolean(to_variant(df["a"])).alias("boolean"), is_boolean(to_variant(df["b"])).alias("varchar")).collect() [Row(BOOLEAN=True, VARCHAR=False)] is_booleanr}rrs rVr*r* sL)A ,Y ??rYc6t|d}td||S)a Returns true if the specified VARIANT column contains a binary value. Examples:: >>> from snowflake.snowpark.types import StructField, VariantType >>> df = session.create_dataframe([[b"snow", "snow"]], schema=["a", "b"]) >>> df.select(is_binary(to_variant(df["a"])).alias("binary"), is_binary(to_variant(df["b"])).alias("varchar")).collect() [Row(BINARY=True, VARCHAR=False)] is_binaryr}rrs rVr-r- sK(A +qI >>rYc6t|d}td||S)a Returns true if the specified VARIANT column contains a string. Examples:: >>> from snowflake.snowpark.types import StructField, VariantType >>> df = session.create_dataframe([["abc", 123]], schema=["a", "b"]) >>> df.select(is_char(to_variant(df["a"])).alias("varchar"), is_char(to_variant(df["b"])).alias("int")).collect() [Row(VARCHAR=True, INT=False)] is_charr}rrs rVr0r0 sI&A )Q) <>> import datetime >>> from snowflake.snowpark.types import StructField, VariantType >>> df = session.create_dataframe([[datetime.date(2023, 3, 2), 123]], schema=["a", "b"]) >>> df.select(is_date(to_variant(df["a"])).alias("date"), is_date(to_variant(df["b"])).alias("int")).collect() [Row(DATE=True, INT=False)] is_dater}rrs rVr3r3  sI&A )Q) <>> import decimal >>> from snowflake.snowpark.types import StructField, VariantType >>> df = session.create_dataframe([[decimal.Decimal(1), "X"]], schema=["a", "b"]) >>> df.select(is_decimal(to_variant(df["a"])).alias("decimal"), is_decimal(to_variant(df["b"])).alias("varchar")).collect() [Row(DECIMAL=True, VARCHAR=False)] is_decimalr}rrs rVr6r6s sL)A ,Y ??rYc6t|d}td||S)a Returns true if the specified VARIANT column contains a floating-point value, fixed-point decimal, or integer. Examples:: >>> from snowflake.snowpark.types import StructField, VariantType >>> df = session.create_dataframe([[1.2, "X"]], schema=["a", "b"]) >>> df.select(is_double(to_variant(df["a"])).alias("double"), is_double(to_variant(df["b"])).alias("varchar")).collect() [Row(DOUBLE=True, VARCHAR=False)] is_doubler}rrs rVr8r8/r.rYc6t|d}td||S)a Returns true if the specified VARIANT column contains a floating-point value, fixed-point decimal, or integer. Example:: >>> from snowflake.snowpark.functions import to_variant, is_real >>> df = session.create_dataframe([[1.2, "X"]], schema=["a", "b"]) >>> df.select(is_real(to_variant("a")).as_("a"), is_real(to_variant("b")).as_("b")).collect() [Row(A=True, B=False)] is_realr}rrs rVr:r:?r1rYc6t|d}td||S)a Returns true if the specified VARIANT column contains a integer value. Examples:: >>> from snowflake.snowpark.types import StructField, VariantType >>> df = session.create_dataframe([[1, "X"]], schema=["a", "b"]) >>> df.select(is_integer(to_variant(df["a"])).alias("int"), is_integer(to_variant(df["b"])).alias("varchar")).collect() [Row(INT=True, VARCHAR=False)] is_integerr}rrs rVr<r<Or+rYc6t|d}td||S)a Returns true if the specified VARIANT column contains a JSON null value. Example:: >>> from snowflake.snowpark.functions import to_variant, is_null_value >>> df = session.create_dataframe([[{"a": "foo"}], [{"a": None}], [None]], schema=["a"]) >>> df.select(is_null_value(to_variant("a")["a"]).as_("a")).collect() [Row(A=False), Row(A=True), Row(A=None)] is_null_valuer}rrs rVr>r>_s sO,A /1 BBrYc6t|d}td||S)a Returns true if the specified VARIANT column contains an OBJECT value. Example:: >>> from snowflake.snowpark.functions import to_variant, is_object >>> df = session.create_dataframe([[[1, 2], {"a": "snow"}]], schema=["a", "b"]) >>> df.select(is_object(to_variant("a")).as_("a"), is_object(to_variant("b")).as_("b")).collect() [Row(A=False, B=True)] is_objectr}rrs rVr@r@or.rYc6t|d}td||S)a Returns true if the specified VARIANT column contains a TIME value. Example:: >>> import datetime >>> from snowflake.snowpark.functions import to_variant, is_time >>> df = session.create_dataframe([[datetime.time(10, 10), "X"]], schema=["a", "b"]) >>> df.select(is_time(to_variant("a")).as_("a"), is_time(to_variant("b")).as_("b")).collect() [Row(A=True, B=False)] is_timer}rrs rVrBrBr4rYc6t|d}td||S)a5 Returns true if the specified VARIANT column contains a TIMESTAMP_LTZ value to be interpreted using the local time zone. Example:: >>> from snowflake.snowpark.functions import to_variant, is_timestamp_ltz >>> df = session.sql("select to_timestamp_ntz('2017-02-24 12:00:00.456') as timestamp_ntz1, " ... "to_timestamp_ltz('2017-02-24 13:00:00.123 +01:00') as timestamp_ltz1, " ... "to_timestamp_tz('2017-02-24 13:00:00.123 +01:00') as timestamp_tz1") >>> df.select(is_timestamp_ltz(to_variant("timestamp_ntz1")).as_("a"), ... is_timestamp_ltz(to_variant("timestamp_ltz1")).as_("b"), ... is_timestamp_ltz(to_variant("timestamp_tz1")).as_("c")).collect() [Row(A=False, B=True, C=False)] is_timestamp_ltzr}rrs rVrDrDs!" s./A ,a9 EErYc6t|d}td||S)a Returns true if the specified VARIANT column contains a TIMESTAMP_NTZ value with no time zone. Example:: >>> from snowflake.snowpark.functions import to_variant, is_timestamp_ntz >>> df = session.sql("select to_timestamp_ntz('2017-02-24 12:00:00.456') as timestamp_ntz1, " ... "to_timestamp_ltz('2017-02-24 13:00:00.123 +01:00') as timestamp_ltz1, " ... "to_timestamp_tz('2017-02-24 13:00:00.123 +01:00') as timestamp_tz1") >>> df.select(is_timestamp_ntz(to_variant("timestamp_ntz1")).as_("a"), ... is_timestamp_ntz(to_variant("timestamp_ltz1")).as_("b"), ... is_timestamp_ntz(to_variant("timestamp_tz1")).as_("c")).collect() [Row(A=True, B=False, C=False)] is_timestamp_ntzr}rrs rVrFrFs! s./A ,a9 EErYc6t|d}td||S)a Returns true if the specified VARIANT column contains a TIMESTAMP_TZ value with a time zone. Example:: >>> from snowflake.snowpark.functions import to_variant, is_timestamp_tz >>> df = session.sql("select to_timestamp_ntz('2017-02-24 12:00:00.456') as timestamp_ntz1, " ... "to_timestamp_ltz('2017-02-24 13:00:00.123 +01:00') as timestamp_ltz1, " ... "to_timestamp_tz('2017-02-24 13:00:00.123 +01:00') as timestamp_tz1") >>> df.select(is_timestamp_tz(to_variant("timestamp_ntz1")).as_("a"), ... is_timestamp_tz(to_variant("timestamp_ltz1")).as_("b"), ... is_timestamp_tz(to_variant("timestamp_tz1")).as_("c")).collect() [Row(A=False, B=False, C=True)] is_timestamp_tzr}rrs rVrHrHs! s-.A +Q) DDrY func_nameargs.cft|dvrtdtfd|D}|S)N)rKz#Incorrect number of args passed to c36K|]}t|ywN)r:).0rrIs rV z0_columns_from_timestamp_parts..sG3&sI6Gs)rrr)rIrJs` rV_columns_from_timestamp_partsrQs9 4y>ykJKK G$G GD KrYkwargsc t|}|dk(r"t|d|}t|d|}||fSd|cxkrdkrnnt|g|dd\}}}} } } |dk\r|dn|jd} |dk(r|dn|jd} | |d k7rt |d | dn t | |}| dn t | |}| | |||| | | ||fS| |||| | | |fS||||| | | tdd |fS|||| | | fSt |d |)NrrrrL nanosecondsrtimestamp_from_partsz( does not accept timezone as an argumentFr}z0 expected 2, 6, 7 or 8 required arguments, got )rr9rQgetrr:r8rj)rIrJrRnum_args date_expr time_exprrrrhrAr@ns_argtz_argnsrs rV_timestamp_from_parts_internalr`su4yH1}"47I6 "47I6 )## h ! ;IQRaQ1aD!$Mavzz-/H$Mavzz*/E  )/E"E {*RST T^T)>vy)Q^T)bnaAtQB. . ^aAtQ* * ^aAtQA(?C CaAtQ& &kI( T  rYrrrrVc |rtd|||g|gn|gznd}td|||\}}}|rtd|||t|d||Std|||||S)a9 Creates a time from individual numeric components. TIME_FROM_PARTS is typically used to handle values in "normal" ranges (e.g. hours 0-23, minutes 0-59), but it also handles values from outside these ranges. This allows, for example, choosing the N-th minute in a day, which can be used to simplify some computations. Example:: >>> df = session.create_dataframe( ... [[11, 11, 0, 987654321], [10, 10, 0, 987654321]], ... schema=["hour", "minute", "second", "nanoseconds"], ... ) >>> df.select(time_from_parts( ... "hour", "minute", "second", nanoseconds="nanoseconds" ... ).alias("TIME_FROM_PARTS")).collect() [Row(TIME_FROM_PARTS=datetime.time(11, 11, 0, 987654)), Row(TIME_FROM_PARTS=datetime.time(10, 10, 0, 987654))] time_from_partsNry)r%rQrr:) rrrrVrQrnr\rr@s rVrbrbsB    66 "K,?bk] S  ,,=tVVTGAq!    !+/@ A  -q!QSI V rYrZr[cyrNrTrZr[rQs rVrWrW/ rYrrr nanosecondrc yrNrT) rrrrrrrfrrQs rVrWrW7srYc\|r td|nd}tdgtdg|i|||dS)a Creates a timestamp from individual numeric components. If no time zone is in effect, the function can be used to create a timestamp from a date expression and a time expression. Example 1:: >>> df = session.create_dataframe( ... [[2022, 4, 1, 11, 11, 0], [2022, 3, 31, 11, 11, 0]], ... schema=["year", "month", "day", "hour", "minute", "second"], ... ) >>> df.select(timestamp_from_parts( ... "year", "month", "day", "hour", "minute", "second" ... ).alias("TIMESTAMP_FROM_PARTS")).collect() [Row(TIMESTAMP_FROM_PARTS=datetime.datetime(2022, 4, 1, 11, 11)), Row(TIMESTAMP_FROM_PARTS=datetime.datetime(2022, 3, 31, 11, 11))] Example 2:: >>> df = session.create_dataframe( ... [['2022-04-01', '11:11:00'], ['2022-03-31', '11:11:00']], ... schema=["date", "time"] ... ) >>> df.select( ... timestamp_from_parts(to_date("date"), to_time("time") ... ).alias("TIMESTAMP_FROM_PARTS")).collect() [Row(TIMESTAMP_FROM_PARTS=datetime.datetime(2022, 4, 1, 11, 11)), Row(TIMESTAMP_FROM_PARTS=datetime.datetime(2022, 3, 31, 11, 11))] rWNryr%rr`rQrJrRrns rVrWrWGsM:@I 4d ;dC   '(> P P P   rYc |rtd||||||g|gn|gznd}d} t| ||||||\} } } } }}|dn t|| }|t| | | | | |||| St| | | | | ||||| S)a Creates a timestamp from individual numeric components. Example:: >>> import datetime >>> df = session.create_dataframe( ... [[2022, 4, 1, 11, 11, 0], [2022, 3, 31, 11, 11, 0]], ... schema=["year", "month", "day", "hour", "minute", "second"], ... ) >>> df.select(timestamp_ltz_from_parts( ... "year", "month", "day", "hour", "minute", "second" ... ).alias("TIMESTAMP_LTZ_FROM_PARTS")).collect() [Row(TIMESTAMP_LTZ_FROM_PARTS=datetime.datetime(2022, 4, 1, 11, 11, tzinfo=)), Row(TIMESTAMP_LTZ_FROM_PARTS=datetime.datetime(2022, 3, 31, 11, 11, tzinfo=))] timestamp_ltz_from_partsNry)r%rQr:r)rrrrrrrVrQrnrIrrrr\rAr@r_s rVrlrlmsB   & 5#tVV 4 (r{m = +I74T66Aq!Qa$*? Y*WB : y!Q1dAC9U q!Q4BSI rYcyrNrTrds rVtimestamp_ntz_from_partsrnrerYcyrNrT)rrrrrrrfrQs rVrnrnsrYc\|r td|nd}tdgtdg|i|||dS)a Creates a timestamp from individual numeric components. The function can be used to create a timestamp from a date expression and a time expression. Example 1:: >>> df = session.create_dataframe( ... [[2022, 4, 1, 11, 11, 0], [2022, 3, 31, 11, 11, 0]], ... schema=["year", "month", "day", "hour", "minute", "second"], ... ) >>> df.select(timestamp_ntz_from_parts( ... "year", "month", "day", "hour", "minute", "second" ... ).alias("TIMESTAMP_NTZ_FROM_PARTS")).collect() [Row(TIMESTAMP_NTZ_FROM_PARTS=datetime.datetime(2022, 4, 1, 11, 11)), Row(TIMESTAMP_NTZ_FROM_PARTS=datetime.datetime(2022, 3, 31, 11, 11))] Example 2:: >>> df = session.create_dataframe( ... [['2022-04-01', '11:11:00'], ['2022-03-31', '11:11:00']], ... schema=["date", "time"] ... ) >>> df.select( ... timestamp_ntz_from_parts(to_date("date"), to_time("time") ... ).alias("TIMESTAMP_NTZ_FROM_PARTS")).collect() [Row(TIMESTAMP_NTZ_FROM_PARTS=datetime.datetime(2022, 4, 1, 11, 11)), Row(TIMESTAMP_NTZ_FROM_PARTS=datetime.datetime(2022, 3, 31, 11, 11))] rnNryrirjs rVrnrnsX8DM 8$ ?RVC "  ' &      rYc |r"td||||||g|gn|gz|gn|gznd} d} t| ||||||\} } } }}}|dn t|| }|dn t|| }||t | | | | |||||| | S|t | | | | ||||| | S|!t | | | | |||t dd|| | St | | | | |||| | S)a Creates a timestamp from individual numeric components and a string timezone. Example:: >>> df = session.create_dataframe( ... [[2022, 4, 1, 11, 11, 0, 'America/Los_Angeles'], [2022, 3, 31, 11, 11, 0, 'America/Los_Angeles']], ... schema=["year", "month", "day", "hour", "minute", "second", "timezone"], ... ) >>> df.select(timestamp_tz_from_parts( ... "year", "month", "day", "hour", "minute", "second", timezone="timezone" ... ).alias("TIMESTAMP_TZ_FROM_PARTS")).collect() [Row(TIMESTAMP_TZ_FROM_PARTS=datetime.datetime(2022, 4, 1, 11, 11, tzinfo=pytz.FixedOffset(-420))), Row(TIMESTAMP_TZ_FROM_PARTS=datetime.datetime(2022, 3, 31, 11, 11, tzinfo=pytz.FixedOffset(-420)))] timestamp_tz_from_partsNryrFr})r%rQr:r8rrj)rrrrrrrVrrQrnrIrrrr\rAr@r_rs rVrrrrs[D   % 5#tVV 4 (r{m =%rH: 7 *I74T66Aq!Qa$*? Y*WB!':8Y'OB8#7 q!Q4B      q!Q4BSI       U #    )Q1aqsi XXrYc6t|d}td||S)a Extracts the corresponding week (number) of the year from a date or timestamp. Example:: >>> import datetime >>> df = session.create_dataframe( ... [[datetime.datetime.strptime("2020-05-01 13:11:20.000", "%Y-%m-%d %H:%M:%S.%f")]], ... schema=["a"], ... ) >>> df.select(weekofyear("a")).collect() [Row(WEEKOFYEAR("A")=18)] weekofyearr}rrs rVrtrt(s q,'A ,Y ??rYc6t|d}td||S)aiReports the type of a value stored in a VARIANT column. The type is returned as a string. For columns where all rows share the same type, the result of `typeof` is the underlying Snowflake column type. Example:: >>> df = session.create_dataframe([1, 2, 3], schema=["A"]) >>> df.select(typeof(col("A")).as_("ans")).collect() [Row(ANS='INTEGER'), Row(ANS='INTEGER'), Row(ANS='INTEGER')] For columns of VARIANT type, the underlying stored type is returned. Example:: >>> from snowflake.snowpark.types import VariantType, StructType, StructField >>> schema = StructType([StructField("A", VariantType())]) >>> df = session.create_dataframe([1, 3.1, 'test'], schema=schema) >>> df.select(typeof(col("A")).as_("ans")).collect() [Row(ANS='INTEGER'), Row(ANS='DECIMAL'), Row(ANS='VARCHAR')] typeofr}rrs rVrvrv;s. sH%A (A ;;rYc6t|d}td||S)aChecks the validity of a JSON document. If the input string is a valid JSON document or a NULL (i.e. no error would occur when parsing the input string), the function returns NULL. In case of a JSON parsing error, the function returns a string that contains the error message. Example:: >>> df = session.create_dataframe(["{'ValidKey1': 'ValidValue1'}", "{'Malformed -- missing val':}", None], schema=['a']) >>> df.select(check_json(df.a)).show() ----------------------- |"CHECK_JSON(""A"")" | ----------------------- |NULL | |misplaced }, pos 29 | |NULL | ----------------------- check_jsonr}rrs rVrxrxVs* sL)A ,Y ??rYc6t|d}td||S)aChecks the validity of an XML document. If the input string is a valid XML document or a NULL (i.e. no error would occur when parsing the input string), the function returns NULL. In case of an XML parsing error, the output string contains the error message. Example:: >>> df = session.create_dataframe([" Valid ", " Invalid ", None], schema=['a']) >>> df.select(check_xml(df.a)).show() --------------------------------------------------- |"CHECK_XML(""A"")" | --------------------------------------------------- |NULL | |no opening tag for , pos 35 | |NULL | --------------------------------------------------- check_xmlr}rrs rVrzrzos( sK(A +qI >>rYcPt|d}t|d}td|||S)a  Parses a JSON string and returns the value of an element at a specified path in the resulting JSON document. Example:: >>> from snowflake.snowpark.functions import json_extract_path_text, to_variant >>> df = session.create_dataframe([[{"a": "foo"}, "a"], [{"a": None}, "a"], [{"a": "foo"}, "b"], [None, "a"]], schema=["k", "v"]) >>> df.select(json_extract_path_text(to_variant("k"), "v").as_("res")).collect() [Row(RES='foo'), Row(RES=None), Row(RES=None), Row(RES=None)] json_extract_path_textr}r)rWr!rQrrs rVr|r|s0 s45At56A 2AqI NNrYc6t|d}td||S)aParse the value of the specified column as a JSON string and returns the resulting JSON document. Example:: >>> df = session.create_dataframe([['{"key": "1"}']], schema=["a"]) >>> df.select(parse_json(df["a"]).alias("result")).show() ---------------- |"RESULT" | ---------------- |{ | | "key": "1" | |} | ---------------- parse_jsonr}rrs rVr~r~s$ q,'A ,Y ??rYc6t|d}td||S)a3Parse the value of the specified column as a JSON string and returns the resulting JSON document. Returns NULL if an error occurs during parsing. Example:: >>> df = session.create_dataframe([['{"key": "1"}'], ['{"Open": "parenthesis"']], schema=["a"]) >>> df.select(try_parse_json(df["a"]).alias("result")).show() ---------------- |"RESULT" | ---------------- |{ | | "key": "1" | |} | |NULL | ---------------- try_parse_jsonr}rrs rVrrs!$ q*+A *A CCrYschemac|rtd||gnd}t|d}t|tr t |}t |dj |djd|jd}||_ |S)a\Parses a column contains a JSON string value into a column of the type specified by schema. Schema can be defined as a DataType object or as a compatible type string. Example:: >>> from snowflake.snowpark.types import MapType, StringType >>> df = session.create_dataframe([('{"key": "value"}',),], schema=["a"]) >>> df.select(from_json(df.a, MapType(StringType(), StringType()))).show() ---------------------- |"from_json(""A"")" | ---------------------- |{ | | "key": "value" | |} | ---------------------- Example:: >>> df = session.create_dataframe([('[1, 2, 3]',),], schema=["b"]) >>> df.select(from_json(df.b, "array")).show() ---------------------- |"from_json(""B"")" | ---------------------- |[ | | 1, | | 2, | | 3 | |] | ---------------------- from_jsonNFr}z from_json(rP) r%r9rrr+r~rIrVrSrz)rrrQrnrrs rVrrsH>> df = session.sql( ... "select (column1) as v from values ('foobar'), " ... "('')" ... ) >>> df.select(parse_xml("v").alias("result")).show() ------------------ |"RESULT" | ------------------ | | | foo | | bar | | | | | | | ------------------ parse_xmlr}rrs rVrrs0 q+&A +qI >>rYc6t|d}td||S)aConverts a JSON "null" value in the specified column to a SQL NULL value. All other VARIANT values in the column are returned unchanged. Example:: >>> df = session.create_dataframe( ... ["null", "1"], ... schema=["S"], ... ).select(strip_null_value(parse_json(col("S"))).as_("B")).where( ... sql_expr("B is null") ... ) >>> df.collect() [Row(B=None)] strip_null_valuer}rrs rVrrs! s./A ,a9 EErYrc^|rtd||gnd}t|d}td||||S)aReturns the input values, pivoted into an ARRAY. If the input is empty, an empty ARRAY is returned. Example:: >>> df = session.create_dataframe([[1], [2], [3], [1]], schema=["a"]) >>> df.select(array_agg("a", True).within_group("a").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 1, | | 2, | | 3 | |] | ------------ array_aggNrr)rWrrQrnrs rVrr'sA*CL kC+= >QUCsK(A QKcY rYelementcPt|d}t|d}td|||S)acReturns an ARRAY containing all elements from the source ARRAY as well as the new element. The new element is located at end of the ARRAY. Args: array: The column containing the source ARRAY. element: The column containing the element to be appended. The element may be of almost any data type. The data type does not need to match the data type(s) of the existing elements in the ARRAY. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(a=[1, 2, 3])]) >>> df.select(array_append("a", lit(4)).alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 1, | | 2, | | 3, | | 4 | |] | ------------ array_appendr}rr%rrQars rVrrCs-: un-Aw/A .!Q) DDrYc|rtd||gnd}t|d}t|trt |dj ddn|}t d||||S)aGiven a source ARRAY, returns an ARRAY with elements of the specified value removed. Args: array: name of column containing array. element: element to be removed from the array. If the element is a VARCHAR, it needs to be casted into VARIANT data type. Examples:: >>> from snowflake.snowpark.types import VariantType >>> df = session.create_dataframe([([1, '2', 3.1, 1, 1],)], ['data']) >>> df.select(array_remove(df.data, 1).alias("objects")).show() ------------- |"OBJECTS" | ------------- |[ | | "2", | | 3.1 | |] | ------------- >>> df.select(array_remove(df.data, lit('2').cast(VariantType())).alias("objects")).show() ------------- |"OBJECTS" | ------------- |[ | | 1, | | 3.1, | | 1, | | 1 | |] | ------------- >>> df.select(array_remove(df.data, None).alias("objects")).show() ------------- |"OBJECTS" | ------------- |NULL | ------------- >>> df.select(array_remove(array_remove(df.data, 1), "2").alias("objects")).show() ------------- |"OBJECTS" | ------------- |[ | | 3.1 | |] | ------------- See Also: - `ARRAY `_ for more details on semi-structured arrays. array_removeNFr}VARIANTry)r%r9rrrjrIr)r%rrQrnrrs rVrresozDM nug.> ?RVCun-A gs # Gu%**9*F  .!QSI NNrYcPt|d}t|d}td|||S)auReturns the concatenation of two ARRAYs. Args: array1: Column containing the source ARRAY. array2: Column containing the ARRAY to be appended to array1. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(a=[1, 2, 3], b=[4, 5])]) >>> df.select(array_cat("a", "b").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 1, | | 2, | | 3, | | 4, | | 5 | |] | ------------ array_catr}rrs rVrrs-6  ,B  ,B +r2 CCrYc6t|d}td||S)aReturns a compacted ARRAY with missing and null values removed, effectively converting sparse arrays into dense arrays. Args: array: Column containing the source ARRAY to be compacted Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(a=[1, None, 3])]) >>> df.select("a", array_compact("a").alias("compacted")).show() ------------------------- |"A" |"COMPACTED" | ------------------------- |[ |[ | | 1, | 1, | | null, | 3 | | 3 |] | |] | | ------------------------- array_compactr}rr%rQrs rVrrs. uo.A /1 BBrYc\|Dcgc]}t|d}}tdg|d|iScc}w)aReturns an ARRAY constructed from zero, one, or more inputs. Args: cols: Columns containing the values (or expressions that evaluate to values). The values do not all need to be of the same data type. Example:: >>> df = session.create_dataframe([[1, 2], [3, 4]], schema=["a", "b"]) >>> df.select(array_construct("a", "b").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 1, | | 2 | |] | |[ | | 3, | | 4 | |] | ------------ array_constructrQrrQrrrs rVrrs:29= =1.- . =B = + Fb FI FF >r/c\|Dcgc]}t|d}}tdg|d|iScc}w)aReturns an ARRAY constructed from zero, one, or more inputs. The constructed ARRAY omits any NULL input values. Args: cols: Columns containing the values (or expressions that evaluate to values). The values do not all need to be of the same data type. Example:: >>> df = session.create_dataframe([[1, None, 2], [3, None, 4]], schema=["a", "b", "c"]) >>> df.select(array_construct_compact("a", "b", "c").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 1, | | 2 | |] | |[ | | 3, | | 4 | |] | ------------ rUrQrrs rVrUrUs=4AE E1.5 6 EB E 3 Nb NI NN Fr/variantcPt|d}t|d}td|||S)aReturns True if the specified VARIANT is found in the specified ARRAY. Args: variant: Column containing the VARIANT to find. array: Column containing the ARRAY to search. If this is a semi-structured array, you're required to explicitly cast the following SQL types into a VARIANT: - `String & Binary `_ - `Date & Time `_ Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(["apple", "banana"]), Row(["apple", "orange"])], schema=["a"]) >>> df.select(array_contains(lit("banana").cast("variant"), "a").alias("result")).show() ------------ |"RESULT" | ------------ |True | |False | ------------ array_containsr}rrr%rQvrs rVrr#s06 w 01Au./A *AqI FFrYcjt|d}t|d}t|d}td||||S)aReturns an ARRAY containing all elements from the source ARRAY as well as the new element. Args: array: Column containing the source ARRAY. pos: Column containing a (zero-based) position in the source ARRAY. The new element is inserted at this position. The original element from this position (if any) and all subsequent elements (if any) are shifted by one position to the right in the resulting array (i.e. inserting at position 0 has the same effect as using array_prepend). A negative position is interpreted as an index from the back of the array (e.g. -1 results in insertion before the last element in the array). element: Column containing the element to be inserted. The new element is located at position pos. The relative order of the other elements from the source array is preserved. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row([1, 2]), Row([1, 3])], schema=["a"]) >>> df.select(array_insert("a", lit(0), lit(10)).alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 10, | | 1, | | 2 | |] | |[ | | 10, | | 1, | | 3 | |] | ------------ array_insertr}r)r%rrrQrrrs rVrrCs<T un-AsN+Aw/A .!QY GGrYcPt|d}t|d}td|||S)aReturns the index of the first occurrence of an element in an ARRAY. Args: variant: Column containing the VARIANT value that you want to find. The function searches for the first occurrence of this value in the array. array: Column containing the ARRAY to be searched. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row([2, 1]), Row([1, 3])], schema=["a"]) >>> df.select(array_position(lit(1), "a").alias("result")).show() ------------ |"RESULT" | ------------ |1 | |0 | ------------ array_positionr}rrs rVrrss0. w 01Au./A *AqI FFrYcPt|d}t|d}td|||S)aReturns an ARRAY containing the new element as well as all elements from the source ARRAY. The new element is positioned at the beginning of the ARRAY. Args: array Column containing the source ARRAY. element Column containing the element to be prepended. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(a=[1, 2, 3])]) >>> df.select(array_prepend("a", lit(4)).alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 4, | | 1, | | 2, | | 3 | |] | ------------ array_prependr}rrs rVrrs-6 uo.Aw0A /1a9 EErYc6t|d}td||S)aReturns the size of the input ARRAY. If the specified column contains a VARIANT value that contains an ARRAY, the size of the ARRAY is returned; otherwise, NULL is returned if the value is not an ARRAY. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(a=[1, 2, 3])]) >>> df.select(array_size("a").alias("result")).show() ------------ |"RESULT" | ------------ |3 | ------------ rr}rrs rVrrs$ ul+A ,Y ??rYfrom_tocjt|d}t|d}t|d}td||||S)aReturns an ARRAY constructed from a specified subset of elements of the input ARRAY. Args: array: Column containing the source ARRAY. from_: Column containing a position in the source ARRAY. The position of the first element is 0. Elements from positions less than this parameter are not included in the resulting ARRAY. to: Column containing a position in the source ARRAY. Elements from positions equal to or greater than this parameter are not included in the resulting array. Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(a=[1, 2, 3, 4, 5])]) >>> df.select(array_slice("a", lit(1), lit(3)).alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 2, | | 3 | |] | ------------ rr}r)r%rrrQrfrs rVrrs;8 um,Aum,Ar=)A -AqI FFrYrOcPt|d}t|d}td|||S)aReturns an input ARRAY converted to a string by casting all values to strings (using TO_VARCHAR) and concatenating them (using the string from the second argument to separate the elements). Args: array: Column containing the ARRAY of elements to convert to a string. separator: Column containing the string to put between each element (e.g. a space, comma, or other human-readable separator). Example:: >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(a=[1, True, "s"])]) >>> df.select(array_to_string("a", lit(",")).alias("result")).show() ------------ |"RESULT" | ------------ |1,true,s | ------------ rr}r)r%rOrQrr@s rVrrs00 u/0Ay"34A +QY GGrYc6t|d}td||S)a Returns a Column containing the distinct values in the specified column col. The values in the Column are in no particular order, and the order is not deterministic. The function ignores NULL values in col. If col contains only NULL values or col is empty, the function returns an empty Column. Args: col: A :class:`Column` object or column name that determines the values. Example:: >>> df = session.create_dataframe([[5], [2], [1], [2], [1]], schema=["a"]) >>> df.select(array_unique_agg("a").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 5, | | 2, | | 1 | |] | ------------ array_unique_aggr}rrs rVrrs!0 s./A ,a9 EErYct|d}t|d}|rtd||g|nd}d}||g}|D]} |jt| dt||} || _| S)a~Returns the concatenatation of two or more MAPs. Args: col1: The source map col2: The map to be appended to col1 cols: More maps to be appended Example:: >>> df = session.sql("select {'k1': 'v1'} :: MAP(STRING,STRING) as A, {'k2': 'v2'} :: MAP(STRING,STRING) as B") >>> df.select(map_cat("A", "B")).show() # doctest: +SKIP --------------------------- |"MAP_CAT(""A"", ""B"")" | --------------------------- |{ | | "k1": "v1", | | "k2": "v2" | |} | --------------------------- >>> df = session.sql("select {'k1': 'v1'} :: MAP(STRING,STRING) as A, {'k2': 'v2'} :: MAP(STRING,STRING) as B, {'k3': 'v3'} :: MAP(STRING,STRING) as C") >>> df.select(map_cat("A", "B", "C")).show() # doctest: +SKIP ------------------------------------------- |"MAP_CAT(MAP_CAT(""A"", ""B""), ""C"")" | ------------------------------------------- |{ | | "k1": "v1", | | "k2": "v2", | | "k3": "v3" | |} | ------------------------------------------- map_catNc td||dS)NrFr}r~)firstrs rVmap_cat_two_mapsz!map_cat..map_cat_two_mapsHsi%HHrY)r9r%rrrz) rrrQrm1m2rnrcols_to_concatrrs rVrr sH i (B i (BAJ i$) 2CCH JrYc8t|d}td|||S)aDetermines whether the specified MAP contains the specified key. Args: value: The key to find. col: The map to be searched. Example 1:: >>> df = session.sql("select {'k1': 'v1'} :: MAP(STRING,STRING) as M, 'k1' as V") >>> df.select(map_contains_key(col("V"), "M")).show() ------------------------------------ |"MAP_CONTAINS_KEY(""V"", ""M"")" | ------------------------------------ |True | ------------------------------------ Example 2:: >>> df = session.sql("select {'k1': 'v1'} :: MAP(STRING,STRING) as M") >>> df.select(map_contains_key("k1", "M")).show() ----------------------------------- |"MAP_CONTAINS_KEY('K1', ""M"")" | ----------------------------------- |True | ----------------------------------- map_containsmap_contains_keyr}r)r'rWrQrs rVrrTs"8 sN+A ,eQ) LLrYc6t|d}td||S)aReturns the keys in a MAP. Args: col: The input map. Example 1:: >>> df = session.sql("select {'k1': 'v1', 'k2': 'v2'} :: MAP(STRING,STRING) as M") >>> df.select(map_keys("M")).show() --------------------- |"MAP_KEYS(""M"")" | --------------------- |[ | | "k1", | | "k2" | |] | --------------------- map_keysr}r)rWrQrs rVrrts( sJ'A *a9 ==rYc |r td|gnd}t|d}t|d}tt |dt |ddjt |dt t|dddjtddjd|jd}||_ |S)aReturns the size of the input ARRAY, OBJECT or MAP. Returns NULL if the input column does not match any of these types. Args: col: A :class:`Column` object or column name that determines the values. Example:: >>> df = session.create_dataframe([([1,2,3], {'a': 1, 'b': 2}, 3)], ['col1', 'col2', 'col3']) >>> df.select(size(df.col1), size(df.col2), size(df.col3)).show() ---------------------------------------------------------- |"SIZE(""COL1"")" |"SIZE(""COL2"")" |"SIZE(""COL3"")" | ---------------------------------------------------------- |3 |2 |NULL | ---------------------------------------------------------- sizeNFr}zSIZE(rP) r%r9 to_variantwhenr(rr@ object_keys otherwiserjrVrSrz)rWrQrnrrresults rVrrs(1: fse ,tCsF#A1&A Q% ( qE *  a5 ) {16% H  3t9 . % ~Q' ( FK MrYkeycPt|d}t|d}td|||S)a=Returns one OBJECT per group. For each key-value input pair, where key must be a VARCHAR and value must be a VARIANT, the resulting OBJECT contains a key-value field. Example:: >>> from snowflake.snowpark.types import StructType, StructField, VariantType, StringType >>> df = session.create_dataframe( ... [["name", "Joe"], ["zip", "98004"]], ... schema=StructType([StructField("k", StringType()), StructField("v", VariantType())]) ... ) >>> df.select(object_agg(col("k"), col("v")).alias("result")).show() -------------------- |"RESULT" | -------------------- |{ | | "name": "Joe", | | "zip": "98004" | |} | -------------------- object_aggr}r)rr'rQkrs rVrrs-2 sL)Aul+A ,1 BBrY key_valuesc\|Dcgc]}t|d}}tdg|d|iScc}w)a]Returns an OBJECT constructed from the arguments. Example:: >>> from snowflake.snowpark.types import StructType, StructField, VariantType, StringType >>> df = session.create_dataframe( ... [["name", "Joe"], ["zip", "98004"],["age", None], [None, "value"]], ... schema=StructType([StructField("k", StringType()), StructField("v", VariantType())]) ... ) >>> df.select(object_construct(col("k"), col("v")).alias("result")).show() -------------------- |"RESULT" | -------------------- |{ | | "name": "Joe" | |} | |{ | | "zip": "98004" | |} | |{} | |{} | -------------------- object_constructrQrrQrkvkvss rVrrs<4=G Gb>"0 1 GC G , Hs Hi HH Hr/c\|Dcgc]}t|d}}tdg|d|iScc}w)aKReturns an object containing the contents of the input (i.e. source) object with one or more keys removed. Example:: >>> from snowflake.snowpark.types import StructType, StructField, VariantType, StringType >>> df = session.create_dataframe( ... [["key_1", "one"], ["key_2", None]], ... schema=StructType([StructField("k", StringType()), StructField("v", VariantType())]) ... ) >>> df.select(object_construct_keep_null(col("k"), col("v")).alias("result")).show() -------------------- |"RESULT" | -------------------- |{ | | "key_1": "one" | |} | |{ | | "key_2": null | |} | -------------------- rrQrrs rVrrs=6GQ Q>": ; QC Q 6 R R RR Rr/rkey1ct|d}t|d}|Dcgc]}t|d}}td||g|d|iScc}w)aReturns an object consisting of the input object with one or more keys removed. The input key must not exist in the object. Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.sql( ... "select object_construct(a,b,c,d,e,f) as obj from " ... "values('age', 21, 'zip', 21021, 'name', 'Joe')," ... "('age', 26, 'zip', 94021, 'name', 'Jay') as T(a,b,c,d,e,f)" ... ) >>> df.select(object_delete(col("obj"), lit("age")).alias("result")).show() -------------------- |"RESULT" | -------------------- |{ | | "name": "Joe", | | "zip": 21021 | |} | |{ | | "name": "Jay", | | "zip": 94021 | |} | -------------------- object_deleterQrrrrQrok1rkss rVrrsT< sO,A o .B6: ;.O , ;B ; /1b K2 K KK <A update_flagct|d}t|d}t|d}| t|dnd}|td|||||Std||||S)a2Returns an object consisting of the input object with a new key-value pair inserted (or an existing key updated with a new value). Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.sql( ... "select object_construct(a,b,c,d,e,f) as obj, k, v from " ... "values('age', 21, 'zip', 21021, 'name', 'Joe', 'age', 0)," ... "('age', 26, 'zip', 94021, 'name', 'Jay', 'age', 0) as T(a,b,c,d,e,f,k,v)" ... ) >>> df.select(object_insert(col("obj"), lit("key"), lit("v")).alias("result")).show() -------------------- |"RESULT" | -------------------- |{ | | "age": 21, | | "key": "v", | | "name": "Joe", | | "zip": 21021 | |} | |{ | | "age": 26, | | "key": "v", | | "name": "Jay", | | "zip": 94021 | |} | -------------------- object_insertNrr}r) rrr'rrQrrrufs rVrr6sjJ sO,AsO,Auo.A7B7N ] 3TXB ~oq!QiPPoq!Q)LLrYct|d}t|d}|Dcgc]}t|d}}td||g|d|iScc}w)a^Returns a new OBJECT containing some of the key-value pairs from an existing object. To identify the key-value pairs to include in the new object, pass in the keys as arguments, or pass in an array containing the keys. If a specified key is not present in the input object, the key is ignored. Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.sql( ... "select object_construct(a,b,c,d,e,f) as obj, k, v from " ... "values('age', 21, 'zip', 21021, 'name', 'Joe', 'age', 0)," ... "('age', 26, 'zip', 94021, 'name', 'Jay', 'age', 0) as T(a,b,c,d,e,f,k,v)" ... ) >>> df.select(object_pick(col("obj"), col("k"), lit("name")).alias("result")).show() ------------------- |"RESULT" | ------------------- |{ | | "age": 21, | | "name": "Joe" | |} | |{ | | "age": 26, | | "name": "Jay" | |} | ------------------- object_pickrQrrs rVrresUB sM*A m ,B48 9q.M * 9B 9 -B I Iy II :rv1v2cPt|d}t|d}td|||S)aReturns the cosine distance between two vectors of equal dimension and element type. Example:: >>> from snowflake.snowpark.functions import vector_cosine_distance >>> df = session.sql("select [1,2,3]::vector(int,3) as a, [2,3,4]::vector(int,3) as b") >>> df.select(vector_cosine_distance(df.a, df.b).as_("dist")).show() ---------------------- |"DIST" | ---------------------- |0.9925833339709303 | ---------------------- vector_cosine_distancer}rrrrQs rVrrs0" 4 5B 4 5B 2Bi PPrYcPt|d}t|d}td|||S)aReturns the l2 distance between two vectors of equal dimension and element type. Example:: >>> from snowflake.snowpark.functions import vector_l2_distance >>> df = session.sql("select [1,2,3]::vector(int,3) as a, [2,3,4]::vector(int,3) as b") >>> df.select(vector_l2_distance(df.a, df.b).as_("dist")).show() ---------------------- |"DIST" | ---------------------- |1.7320508075688772 | ---------------------- vector_l2_distancer}rrs rVrrs0" 0 1B 0 1B .B) LLrYcPt|d}t|d}td|||S)aReturns the inner product between two vectors of equal dimension and element type. Example:: >>> from snowflake.snowpark.functions import vector_inner_product >>> df = session.sql("select [1,2,3]::vector(int,3) as a, [2,3,4]::vector(int,3) as b") >>> df.select(vector_inner_product(df.a, df.b).as_("dist")).show() ---------- |"DIST" | ---------- |20.0 | ---------- vector_inner_productr}rrs rVrrs0" 2 3B 2 3B 0"bI NNrYc6t|d}td||S)aReturns the natrual logarithm of given column expression. Example:: >>> from snowflake.snowpark.functions import ln >>> from math import e >>> df = session.create_dataframe([[e]], schema=["ln_value"]) >>> df.select(ln(col("ln_value")).alias("result")).show() ------------ |"RESULT" | ------------ |1.0 | ------------ rr}r)rrQs rVrrs q$A $Y 77rYcr|r td|gnd}t|d}|jd}||_|S)aReturns a Column expression with values sorted in ascending order. Example:: >>> df = session.create_dataframe([None, 3, 2, 1, None], schema=["a"]) >>> df.sort(asc(df["a"])).collect() [Row(A=None), Row(A=None), Row(A=1), Row(A=2), Row(A=3)] ascNFr})r%r9rrzrrQrnrs rVrrs?.7 eaS )DCq% A %%%% CCH JrYcr|r td|gnd}t|d}|jd}||_|S)aOReturns a Column expression with values sorted in ascending order (null values sorted before non-null values). Example:: >>> df = session.create_dataframe([None, 3, 2, 1, None], schema=["a"]) >>> df.sort(asc_nulls_first(df["a"])).collect() [Row(A=None), Row(A=None), Row(A=1), Row(A=2), Row(A=3)] asc_nulls_firstNFr})r%r9rrzrs rVrrE:C /! 5Cq+,A  e  ,CCH JrYcr|r td|gnd}t|d}|jd}||_|S)aMReturns a Column expression with values sorted in ascending order (null values sorted after non-null values). Example:: >>> df = session.create_dataframe([None, 3, 2, 1, None], schema=["a"]) >>> df.sort(asc_nulls_last(df["a"])).collect() [Row(A=1), Row(A=2), Row(A=3), Row(A=None), Row(A=None)] asc_nulls_lastNFr})r%r9rrzrs rVrr sE9B . 4tCq*+A  U  +CCH JrYcr|r td|gnd}t|d}|jd}||_|S)a Returns a Column expression with values sorted in descending order. Example:: >>> df = session.create_dataframe([1, 2, 3, None, None], schema=["a"]) >>> df.sort(desc(df["a"])).collect() [Row(A=3), Row(A=2), Row(A=1), Row(A=None), Row(A=None)] descNFr})r%r9rrzrs rVrr!s?/8 fqc *TCq&!A &&5& !CCH JrYcr|r td|gnd}t|d}|jd}||_|S)aV Returns a Column expression with values sorted in descending order (null values sorted before non-null values). Example:: >>> df = session.create_dataframe([1, 2, 3, None, None], schema=["a"]) >>> df.sort(desc_nulls_first(df["a"])).collect() [Row(A=None), Row(A=None), Row(A=3), Row(A=2), Row(A=1)] desc_nulls_firstNFr})r%r9rrzrs rVrr5sE;D 01# 6Cq,-A  u  -CCH JrYcr|r td|gnd}t|d}|jd}||_|S)aS Returns a Column expression with values sorted in descending order (null values sorted after non-null values). Example:: >>> df = session.create_dataframe([1, 2, 3, None, None], schema=["a"]) >>> df.sort(desc_nulls_last(df["a"])).collect() [Row(A=3), Row(A=2), Row(A=1), Row(A=None), Row(A=None)] desc_nulls_lastNFr})r%r9rrzrs rVrrJrrYc6t|d}td||S)ayCasts a VARIANT value to an array. Example:: >>> df = session.sql("select array_construct(1, 2)::variant as a") >>> df.select(as_array("a").alias("result")).show() ------------ |"RESULT" | ------------ |[ | | 1, | | 2 | |] | ------------ as_arrayr}rrrQrs rVrr^s" w +A *a9 ==rYc6t|d}td||S)uCasts a VARIANT value to a binary string. Example:: >>> df = session.sql("select to_binary('F0A5')::variant as a") >>> df.select(as_binary("a").alias("result")).show() -------------------------- |"RESULT" | -------------------------- |bytearray(b'ð¥') | -------------------------- as_binaryr}rrs rVrrs w ,A +qI >>rYc6t|d}td||S)aCasts a VARIANT value to a string. Example:: >>> from snowflake.snowpark.functions import as_char, to_variant >>> df = session.sql("select 'some string' as char") >>> df.char_v = to_variant(df.char) >>> df.select(df.char_v.as_("char")).collect() == df.select(df.char).collect() False >>> df.select(as_char(df.char_v).as_("char")).collect() == df.select(df.char).collect() True as_charr}rrs rVrr w *A )Q) <>> from snowflake.snowpark.functions import as_varchar, to_variant >>> df = session.sql("select 'some string' as char") >>> df.char_v = to_variant(df.char) >>> df.select(df.char_v.as_("char")).collect() == df.select(df.char).collect() False >>> df.select(as_varchar(df.char_v).as_("char")).collect() == df.select(df.char).collect() True as_varcharr}rrs rVrr w -A ,Y ??rYc6t|d}td||S)a:Casts a VARIANT value to a date. Example:: >>> df = session.sql("select date'2020-1-1'::variant as a") >>> df.select(as_date("a").alias("result")).show() -------------- |"RESULT" | -------------- |2020-01-01 | -------------- as_dater}rrs rVrrrrYrccv|rtd||gnd}t|d}|j|d}||_|S)aConverts a value of one data type into another data type. The semantics of CAST are the same as the semantics of the corresponding to datatype conversion functions. If the cast is not possible, a ``SnowparkSQLException`` exception is thrown. Example:: >>> from snowflake.snowpark.types import DecimalType, IntegerType >>> df = session.create_dataframe([[1.5432]], schema=["d"]) >>> df.select(cast(df.d, DecimalType(15, 2)).as_("DECIMAL"), cast(df.d, IntegerType()).as_("INT")).show() --------------------- |"DECIMAL" |"INT" | --------------------- |1.54 |2 | --------------------- rINFr})r%r9rIrzrcrrQrnrrs rVrIrIsD*8A fvrl 3dCvv&A &&u& %CCH JrYcv|rtd||gnd}t|d}|j|d}||_|S)uA special version of CAST for a subset of data type conversions. It performs the same operation (i.e. converts a value of one data type into another data type), but returns a NULL value instead of raising an error when the conversion can not be performed. The ``column`` argument must be a string column in Snowflake. Example:: >>> from snowflake.snowpark.types import IntegerType, FloatType >>> df = session.create_dataframe(['0', '-12', '22', '1001'], schema=["a"]) >>> df.select(try_cast(col("a"), IntegerType()).as_('ans')).collect() [Row(ANS=0), Row(ANS=-12), Row(ANS=22), Row(ANS=1001)] Example:: >>> df = session.create_dataframe(['0.12', 'USD 27.90', '13.97 USD', '€97.0', '17,-'], schema=["a"]) >>> df.select(try_cast(col("a"), FloatType()).as_('ans')).collect() [Row(ANS=0.12), Row(ANS=None), Row(ANS=None), Row(ANS=None), Row(ANS=None)] ruNFr})r%r9rurzrs rVrurusD2>> df = session.sql("select 1.2345::variant as a") >>> df.select(as_decimal("a", 4, 1).alias("result")).show() ------------ |"RESULT" | ------------ |1.2 | ------------ as_decimalNz%Cannot define scale without precisionFr}ry)r%r9rrrj)rrarrQrn cast_typers rVrrs6    I&rYK 9]r 1 Iw *A Y@AAU   U +  '     q#i59y  i JJrYc6t|d}td||S)a:Casts a VARIANT value to a floating-point value. Example:: >>> df = session.sql("select 1.2345::variant as a") >>> df.select(as_double("a").alias("result")).show() ------------ |"RESULT" | ------------ |1.2345 | ------------ as_doubler}rrs rVrr0 rrYc6t|d}td||S)aCasts a VARIANT value to a floating-point value. Example:: >>> from snowflake.snowpark.types import VariantType, StructType, StructField, DoubleType >>> schema=StructType([StructField("radius", DoubleType()), StructField("radius_v", VariantType())]) >>> df = session.create_dataframe(data=[[2.0, None]], schema=schema) >>> df.radius_v = to_variant(df.radius) >>> df.select(df.radius_v.as_("radius_v"), df.radius).collect() [Row(RADIUS_V='2.000000000000000e+00', RADIUS=2.0)] >>> df.select(as_real(df.radius_v).as_("real_radius_v"), df.radius).collect() [Row(REAL_RADIUS_V=2.0, RADIUS=2.0)] as_realr}rrs rVr r B s w *A )Q) <>> df = session.sql("select 1.2345::variant as a") >>> df.select(as_integer("a").alias("result")).show() ------------ |"RESULT" | ------------ |1 | ------------ as_integerr}rrs rVr r U rrYc6t|d}td||S)aCasts a VARIANT value to an object. Example:: >>> df = session.sql("select object_construct('A',1,'B','BBBB')::variant as a") >>> df.select(as_object("a").alias("result")).show() ----------------- |"RESULT" | ----------------- |{ | | "A": 1, | | "B": "BBBB" | |} | ----------------- as_objectr}rrs rVrrg s" w ,A +qI >>rYc6t|d}td||S)aCasts a VARIANT value to a time value. Example:: >>> from snowflake.snowpark.functions import as_time, to_variant >>> df = session.sql("select TO_TIME('12:34:56') as alarm") >>> df.alarm_v = to_variant(df.alarm) >>> df.select(df.alarm_v.as_("alarm")).collect() == df.select(df.alarm).collect() False >>> df.select(as_time(df.alarm_v).as_("alarm")).collect() == df.select(df.alarm).collect() True as_timer}rrs rVrr| rrYc6t|d}td||S)a Casts a VARIANT value to a TIMESTAMP with a local timezone. Example:: >>> from snowflake.snowpark.functions import as_timestamp_ltz, to_variant >>> df = session.sql("select TO_TIMESTAMP_LTZ('2018-10-10 12:34:56') as alarm") >>> df.alarm_v = to_variant(df.alarm) >>> df.select(df.alarm_v.as_("alarm")).collect() == df.select(df.alarm).collect() False >>> df.select(as_timestamp_ltz(df.alarm_v).as_("alarm")).collect() == df.select(df.alarm).collect() True as_timestamp_ltzr}rrs rVrr ! w 23A ,a9 EErYc6t|d}td||S)aCasts a VARIANT value to a TIMESTAMP with no timezone. Example:: >>> from snowflake.snowpark.functions import as_timestamp_ntz, to_variant >>> df = session.sql("select TO_TIMESTAMP_NTZ('2018-10-10 12:34:56') as alarm") >>> df.alarm_v = to_variant(df.alarm) >>> df.select(df.alarm_v.as_("alarm")).collect() == df.select(df.alarm).collect() False >>> df.select(as_timestamp_ntz(df.alarm_v).as_("alarm")).collect() == df.select(df.alarm).collect() True as_timestamp_ntzr}rrs rVrr rrYc6t|d}td||S)aCasts a VARIANT value to a TIMESTAMP with a timezone. Example:: >>> from snowflake.snowpark.functions import as_timestamp_tz, to_variant >>> df = session.sql("select TO_TIMESTAMP_TZ('2018-10-10 12:34:56 +0000') as alarm") >>> df.alarm_v = to_variant(df.alarm) >>> df.select(df.alarm_v.as_("alarm")).collect() == df.select(df.alarm).collect() False >>> df.select(as_timestamp_tz(df.alarm_v).as_("alarm")).collect() == df.select(df.alarm).collect() True as_timestamp_tzr}rrs rVrr s! w 12A +Q) DDrYcXt|d}|rtd|||Std||S)aConverts the input expression to a binary value. For NULL input, the output is NULL. Example:: >>> df = session.create_dataframe(['00', '67', '0312'], schema=['a']) >>> df.select(to_binary(col('a')).as_('ans')).collect() [Row(ANS=bytearray(b'\x00')), Row(ANS=bytearray(b'g')), Row(ANS=bytearray(b'\x03\x12'))] >>> df = session.create_dataframe(['aGVsbG8=', 'd29ybGQ=', 'IQ=='], schema=['a']) >>> df.select(to_binary(col('a'), 'BASE64').as_('ans')).collect() [Row(ANS=bytearray(b'hello')), Row(ANS=bytearray(b'world')), Row(ANS=bytearray(b'!'))] >>> df.select(to_binary(col('a'), 'UTF-8').as_('ans')).collect() [Row(ANS=bytearray(b'aGVsbG8=')), Row(ANS=bytearray(b'd29ybGQ=')), Row(ANS=bytearray(b'IQ=='))] to_binaryr}rrxs rVrr s=& q+&A  {Asi@Ki @rYc6t|d}td||S)a0Converts any value to an ARRAY value or NULL (if input is NULL). Example:: >>> df = session.create_dataframe([1, 2, 3, 4], schema=['a']) >>> df.select(to_array(col('a')).as_('ans')).collect() [Row(ANS='[\n 1\n]'), Row(ANS='[\n 2\n]'), Row(ANS='[\n 3\n]'), Row(ANS='[\n 4\n]')] >>> from snowflake.snowpark import Row >>> df = session.create_dataframe([Row(a=[1, 2, 3]), Row(a=None)]) >>> df.select(to_array(col('a')).as_('ans')).collect() [Row(ANS='[\n 1,\n 2,\n 3\n]'), Row(ANS=None)] to_arrayr}rrs rVrr s q*%A *a9 ==rYc6t|d}td||S)aConverts any VARIANT value to a string containing the JSON representation of the value. If the input is NULL, the result is also NULL. Example:: >>> from snowflake.snowpark.types import VariantType, StructField, StructType >>> from snowflake.snowpark import Row >>> schema = StructType([StructField("a", VariantType())]) >>> df = session.create_dataframe([Row(a=None),Row(a=12),Row(a=3.141),Row(a={'a':10,'b':20}),Row(a=[1,23,456])], schema=schema) >>> df.select(to_json(col("a")).as_('ans')).collect() [Row(ANS=None), Row(ANS='12'), Row(ANS='3.141'), Row(ANS='{"a":10,"b":20}'), Row(ANS='[1,23,456]')] to_jsonr}rrs rVrr s q)$A )Q) <>> from snowflake.snowpark.types import VariantType, StructField, StructType >>> from snowflake.snowpark import Row >>> schema = StructType([StructField("a", VariantType())]) >>> df = session.create_dataframe(["{'a':10,'b':20}", None], schema=schema) >>> df.select(to_object(col("a")).as_('ans')).collect() [Row(ANS='{\n "a": 10,\n "b": 20\n}'), Row(ANS=None)] to_objectr}rrs rVrr!rrYc6t|d}td||S)aConverts any value to a VARIANT value or NULL (if input is NULL). Example:: >>> df = session.create_dataframe([1, 2, 3, 4], schema=['a']) >>> df_conv = df.select(to_variant(col("a")).as_("ans")).sort("ans") >>> df_conv.collect() [Row(ANS='1'), Row(ANS='2'), Row(ANS='3'), Row(ANS='4')] After conversion via to_variant, another variant dataframe can be merged. >>> from snowflake.snowpark.types import VariantType, StructField, StructType >>> from snowflake.snowpark import Row >>> schema = StructType([StructField("a", VariantType())]) >>> df_other = session.create_dataframe([Row(a=10), Row(a='test'), Row(a={'a': 10, 'b': 20}), Row(a=[1, 2, 3])], schema=schema) >>> df_conv.union(df_other).select(typeof(col("ans")).as_("ans")).sort("ans").collect() [Row(ANS='ARRAY'), Row(ANS='INTEGER'), Row(ANS='INTEGER'), Row(ANS='INTEGER'), Row(ANS='INTEGER'), Row(ANS='INTEGER'), Row(ANS='OBJECT'), Row(ANS='VARCHAR')] rr}rrs rVrr!s( q,'A ,Y ??rYc6t|d}td||S)aConverts any VARIANT value to a string containing the XML representation of the value. If the input is NULL, the result is also NULL. Example:: >>> from snowflake.snowpark.types import VariantType, StructField, StructType >>> from snowflake.snowpark import Row >>> schema = StructType([StructField("a", VariantType())]) >>> df = session.create_dataframe([Row(a=10), Row(a='test'), Row(a={'a': 10, 'b': 20}), Row(a=[1, 2, 3])], schema=schema) >>> df.select(to_xml(col("A")).as_("ans")).collect() [Row(ANS='10'), Row(ANS='test'), Row(ANS='1020'), Row(ANS='123')] to_xmlr}rrs rVr"r",!rrYfieldcPt|d}t|d}td|||S)a Extracts a field value from an object. Returns NULL if either of the arguments is NULL. This function is similar to :meth:`get` but applies case-insensitive matching to field names. Examples:: >>> df = session.create_dataframe([{"a": {"aa": 1, "bb": 2, "cc": 3}}]) >>> df.select(get_ignore_case(df["a"], lit("AA")).alias("get_ignore_case")).collect() [Row(GET_IGNORE_CASE='1')] get_ignore_caser}r)rr#rQrrs rVr%r%=!s0 . /B 0 1B +Ry IIrYc6t|d}td||S)a:Returns an array containing the list of keys in the input object. Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.sql( ... "select object_construct(a,b,c,d,e,f) as obj, k, v from " ... "values('age', 21, 'zip', 21021, 'name', 'Joe', 'age', 0)," ... "('age', 26, 'zip', 94021, 'name', 'Jay', 'age', 0) as T(a,b,c,d,e,f,k,v)" ... ) >>> df.select(object_keys(col("obj")).alias("result")).show() ------------- |"RESULT" | ------------- |[ | | "age", | | "name", | | "zip" | |] | |[ | | "age", | | "name", | | "zip" | |] | ------------- rr}r)rrQrs rVrrP!s: sM*A -i @@rYxmltag instance_numct|d}t|d}t|tr|n t|d}td||||S)a+Extracts an XML element object (often referred to as simply a tag) from a content of outer XML element object by the name of the tag and its instance number (counting from 0). The following example returns the first inner level (level2) from the XML object created via `parse_xml`. Example:: >>> df = session.create_dataframe(['123a3b'], schema=["str"]).select(parse_xml("str").as_("obj")) >>> df.collect() [Row(OBJ='\n 1\n \n 2\n 3a\n 3b\n \n')] >>> df.select(xmlget("obj", lit("level2")).as_("ans")).collect() [Row(ANS='\n 2\n 3a\n 3b\n')] When multiple tags exist at a level, instance_num can be used to distinguish which element to return. Example:: >>> df.select(xmlget(xmlget("obj", lit("level2")), lit("level3"), lit(0)).as_("ans")).collect() [Row(ANS='3a')] >>> df.select(xmlget(xmlget("obj", lit("level2")), lit("level3"), lit(1)).as_("ans")).collect() [Row(ANS='3b')] >>> df.select(xmlget("obj", lit("level2"), lit(5)).as_("ans")).collect() [Row(ANS=None)] In order to get the tagname, the value of an attribute or the content within a tag the `get` function can be used. Example:: >>> df.select(get(xmlget("obj", lit("level2")), lit("@")).as_("ans")).collect() [Row(ANS='"level2"')] >>> df.select(get(xmlget("obj", lit("level2")), lit("$")).as_("ans")).collect() [Row(ANS='[\n 2,\n {\n "$": "3a",\n "@": "level3"\n },\n {\n "$": "3b",\n "@": "level3"\n }\n]')] >>> df.select(get(xmlget(xmlget("obj", lit("level2")), lit("level3")), lit("$")).as_("ans")).collect() [Row(ANS='"3a"')] >>> df.select(get(xmlget("obj", lit("level2")), lit("@attr2")).as_("ans")).collect() [Row(ANS='"b"')] xmlgetr})r9rrGr)r'r(r)rQrrc3s rVr+r+q!sRX X &B X &B lC (  L( 3 (BB) DDrYcPt|d}t|d}td|||S)a Extracts a value from semi-structured data using a path name. Examples:: >>> df = session.create_dataframe([{"a": {"aa": {"dd": 4}, "bb": 2, "cc": 3}}]) >>> df.select(get_path(df["a"], lit("aa.dd")).alias("get_path")).collect() [Row(GET_PATH='4')] get_pathr}r)rWr!rQrrs rVr.r.!s- Z (B j )B *b" BBrYcPt|d}t|d}td|||S)aExtracts a value from an object or array; returns NULL if either of the arguments is NULL. Example:: >>> from snowflake.snowpark.functions import lit >>> df = session.createDataFrame([({"a": 1.0, "b": 2.0}, [1, 2, 3],), ({}, [],)], ["map", "list"]) >>> df.select(get(df.list, 1).as_("idx1")).sort(col("idx1")).show() ---------- |"IDX1" | ---------- |NULL | |2 | ---------- >>> df.select(get(df.map, lit("a")).as_("get_a")).sort(col("get_a")).show() ----------- |"GET_A" | ----------- |NULL | |1 | ----------- rXr}r:r)rrrQrrs rVrXrX!s-: tU +B tU +B %R9 ==rY conditionc|d}|rxtj}t|j}t|jj }t |j|t|j|ttt|djtj|fg||S)aWorks like a cascading if-then-else statement. A series of conditions are evaluated in sequence. When a condition evaluates to TRUE, the evaluation stops and the associated result (after THEN) is returned. If none of the conditions evaluate to TRUE, then the result after the optional OTHERWISE is returned, if present; otherwise NULL is returned. Args: condition: A :class:`Column` expression or SQL text representing the specified condition. value: A :class:`Column` expression or a literal value, which will be returned if ``condition`` is true. Example:: >>> df = session.create_dataframe([1, None, 2, 3, None, 5, 6], schema=["a"]) >>> df.collect() [Row(A=1), Row(A=None), Row(A=2), Row(A=3), Row(A=None), Row(A=5), Row(A=6)] >>> df.select(when(col("a") % 2 == 0, lit("even")).as_("ans")).collect() [Row(ANS=None), Row(ANS=None), Row(ANS='even'), Row(ANS=None), Row(ANS=None), Row(ANS=None), Row(ANS='even')] Multiple when statements can be changed and `otherwise`/`else_` used to create expressions similar to ``CASE WHEN ... ELSE ... END`` in SQL. Example:: >>> df.select(when(col("a") % 2 == 0, lit("even")).when(col("a") % 2 == 1, lit("odd")).as_("ans")).collect() [Row(ANS='odd'), Row(ANS=None), Row(ANS='even'), Row(ANS='odd'), Row(ANS=None), Row(ANS='odd'), Row(ANS='even')] >>> df.select(when(col("a") % 2 == 0, lit("even")).when(col("a") % 2 == 1, lit("odd")).otherwise(lit("unknown")).as_("ans")).collect() [Row(ANS='odd'), Row(ANS='unknown'), Row(ANS='even'), Row(ANS='odd'), Row(ANS='unknown'), Row(ANS='odd'), Row(ANS='even')] Nrry)rorpr$column_case_exprcasesaddr#r1r"r'r5rr8rr6r)r1r'rQrnr case_exprs rVrr!sF Cjjl !5!56%djjnn&67 293F3F R5ioouM ( 6:FFOOE*    rYexpr1expr2c^|rtd|||gnd}tdt|d||||S)a Returns one of two specified expressions, depending on a condition. This is equivalent to an ``if-then-else`` expression. Args: condition: A :class:`Column` expression or SQL text representing the specified condition. expr1: A :class:`Column` expression or a literal value, which will be returned if ``condition`` is true. expr2: A :class:`Column` expression or a literal value, which will be returned if ``condition`` is false. Examples:: >>> df = session.create_dataframe([True, False, None], schema=["a"]) >>> df.select(iff(df["a"], lit("true"), lit("false")).alias("iff")).collect() [Row(IFF='true'), Row(IFF='false'), Row(IFF='false')] rNry)r%rr8)r1r7r8rQrns rVrr"sE0DM ei%> ?RVC  Iu-    rYvalszsnowflake.snowpark.DataFramecd}|rtj}t|j}|D](}|jj }t ||*g}|D]s} tj} t| tjjjr| j| n t | | |j| utj}t|d|g|t|}|D cgc]} t!| d} } t#t%| D cgc]} | j&c} dj)|d} || _| Scc} wcc} w)aReturns a conditional expression that you can pass to the filter or where methods to perform the equivalent of a WHERE ... IN query that matches rows containing a sequence of values. The expression evaluates to true if the values in a row matches the values in one of the specified sequences. The following code returns a DataFrame that contains the rows in which the columns `c1` and `c2` contain the values: - `1` and `"a"`, or - `2` and `"b"` This is equivalent to ``SELECT * FROM table WHERE (c1, c2) IN ((1, 'a'), (2, 'b'))``. Example:: >>> df = session.create_dataframe([[1, "a"], [2, "b"], [3, "c"]], schema=["col1", "col2"]) >>> df.filter(in_([col("col1"), col("col2")], [[1, "a"], [2, "b"]])).show() ------------------- |"COL1" |"COL2" | ------------------- |1 |a | |2 |b | ------------------- The following code returns a DataFrame that contains the rows where the values of the columns `c1` and `c2` in `df2` match the values of the columns `a` and `b` in `df1`. This is equivalent to ``SELECT * FROM table2 WHERE (c1, c2) IN (SELECT a, b FROM table1)``. Example:: >>> df1 = session.sql("select 1, 'a'") >>> df.filter(in_([col("col1"), col("col2")], df1)).show() ------------------- |"COL1" |"COL2" | ------------------- |1 |a | ------------------- Args:: cols: A list of the columns to compare for the IN operation. vals: A list containing the values or columns, or a Snowpark DataFrame to compare for the IN operation. Nin_Fr})rorpr$list_valvsr5r"rrr dataframe DataFrame _set_ast_refrr r.r9r6rrr<rz)rrQr:rnlist_arglist_astrWcol_ast values_argsvalval_astrr.rs rVr<r<8"sDv C::<$X%6%67 HCkkoo'G 9'3 G H  (CjjlG#y11;;EEF  )=gsK   w '  (jjlsE8BkB ($ /D156A~a'6G6 7;aAMM;<  c$%c CH J 7;s E &E% ctd|S)a Finds the cumulative distribution of a value with regard to other values within the same window partition. Example: >>> from snowflake.snowpark.window import Window >>> from snowflake.snowpark.types import DecimalType >>> df = session.create_dataframe([[1, 2], [1, 2], [1,3], [4, 5], [2, 3], [3, 4], [4, 7], [3,7], [4,5]], schema=["a", "b"]) >>> df.select(cume_dist().over(Window.order_by("a")).cast(DecimalType(scale=3)).alias("result")).show() ------------ |"RESULT" | ------------ |0.333 | |0.333 | |0.333 | |0.444 | |0.667 | |0.667 | |1.000 | |1.000 | |1.000 | ------------ cume_distr}r~r}s rVrIrI"s6 + ;;rYctd|S)a. Returns the rank of a value within an ordered group of values. The rank value starts at 1 and continues up. Example:: >>> from snowflake.snowpark.window import Window >>> df = session.create_dataframe( ... [ ... [1, 2, 1], ... [1, 2, 3], ... [2, 1, 10], ... [2, 2, 1], ... [2, 2, 3], ... ], ... schema=["x", "y", "z"] ... ) >>> df.select(rank().over(Window.partition_by(col("X")).order_by(col("Y"))).alias("result")).sort("result").show() ------------ |"RESULT" | ------------ |1 | |1 | |1 | |2 | |2 | ------------ rankr}r~r}s rVrKrK"s< &I 66rYctd|S)aA Returns the relative rank of a value within a group of values, specified as a percentage ranging from 0.0 to 1.0. Example:: >>> from snowflake.snowpark.window import Window >>> df = session.create_dataframe( ... [ ... [1, 2, 1], ... [1, 2, 3], ... [2, 1, 10], ... [2, 2, 1], ... [2, 2, 3], ... ], ... schema=["x", "y", "z"] ... ) >>> df.select(percent_rank().over(Window.partition_by("x").order_by(col("y"), col("z"))).alias("result")).sort("result").show() ------------ |"RESULT" | ------------ |0.0 | |0.0 | |0.5 | |1.0 | |1.0 | ------------ percent_rankr}r~r}s rVrMrM"s< .I >>rYctd|S)aZ Returns the rank of a value within a group of values, without gaps in the ranks. The rank value starts at 1 and continues up sequentially. If two values are the same, they will have the same rank. Example:: >>> from snowflake.snowpark.window import Window >>> window = Window.order_by("key") >>> df = session.create_dataframe([(1, "1"), (2, "2"), (1, "3"), (2, "4")], schema=["key", "value"]) >>> df.select(dense_rank().over(window).as_("dense_rank")).collect() [Row(DENSE_RANK=1), Row(DENSE_RANK=1), Row(DENSE_RANK=2), Row(DENSE_RANK=2)] dense_rankr}r~r}s rVrOrO"s ,) <>> from snowflake.snowpark.window import Window >>> df = session.create_dataframe( ... [ ... [1, 2, 1], ... [1, 2, 3], ... [2, 1, 10], ... [2, 2, 1], ... [2, 2, 3], ... ], ... schema=["x", "y", "z"] ... ) >>> df.select(col("X"), row_number().over(Window.partition_by(col("X")).order_by(col("Y"))).alias("result")).sort("X", "result").show() ------------------ |"X" |"RESULT" | ------------------ |1 |1 | |1 |2 | |2 |1 | |2 |2 | |2 |3 | ------------------ row_numberr}r~r}s rVrQrQ#s> ,) <>> from snowflake.snowpark.window import Window >>> df = session.create_dataframe( ... [ ... [1, 2, 1], ... [1, 2, 3], ... [2, 1, 10], ... [2, 2, 1], ... [2, 2, 3], ... ], ... schema=["x", "y", "z"] ... ) >>> df.select(lag("Z").over(Window.partition_by(col("X")).order_by(col("Y"))).alias("result")).sort("result").collect() [Row(RESULT=None), Row(RESULT=None), Row(RESULT=1), Row(RESULT=1), Row(RESULT=10)] lagNFr})r%r9r6rrrrzrrRrSrTrQrnrrs rVrVrV&#sh>  EAv}l#KL  q% A  AMM66??=#A<P CCH JrYc |rtd||||gnd}t|d}tt|j|tj ||d}||_|S)a Accesses data in a subsequent row in the same result set without having to join the table to itself. Example:: >>> from snowflake.snowpark.window import Window >>> df = session.create_dataframe( ... [ ... [1, 2, 1], ... [1, 2, 3], ... [2, 1, 10], ... [2, 2, 1], ... [2, 2, 3], ... ], ... schema=["x", "y", "z"] ... ) >>> df.select(lead("Z").over(Window.partition_by(col("X")).order_by(col("Y"))).alias("result")).sort("result").collect() [Row(RESULT=None), Row(RESULT=None), Row(RESULT=1), Row(RESULT=3), Row(RESULT=3)] leadNFr})r%r9r6rrrrzrWs rVrYrYS#sh>  FQ |$LM  q&!A  Q]]FFOOM$BLQ CCH JrYc|rtd||gnd}t|d}tt|jdd|d}||_|S)az Returns the last value within an ordered group of values. Example:: >>> from snowflake.snowpark.window import Window >>> window = Window.partition_by("column1").order_by("column2") >>> df = session.create_dataframe([[1, 10], [1, 11], [2, 20], [2, 21]], schema=["column1", "column2"]) >>> df.select(df["column1"], df["column2"], last_value(df["column2"]).over(window).as_("column2_last")).collect() [Row(COLUMN1=1, COLUMN2=10, COLUMN2_LAST=11), Row(COLUMN1=1, COLUMN2=11, COLUMN2_LAST=11), Row(COLUMN1=2, COLUMN2=20, COLUMN2_LAST=21), Row(COLUMN1=2, COLUMN2=21, COLUMN2_LAST=21)] last_valueNFr})r%r9r6rrrzrrTrQrnrrs rVr[r[#sP CL lQ ,= >QUCq,'A 1==$lCu UCCH JrYc|rtd||gnd}t|d}tt|jdd|d}||_|S)a Returns the first value within an ordered group of values. Example:: >>> from snowflake.snowpark.window import Window >>> window = Window.partition_by("column1").order_by("column2") >>> df = session.create_dataframe([[1, 10], [1, 11], [2, 20], [2, 21]], schema=["column1", "column2"]) >>> df.select(df["column1"], df["column2"], first_value(df["column2"]).over(window).as_("column2_first")).collect() [Row(COLUMN1=1, COLUMN2=10, COLUMN2_FIRST=10), Row(COLUMN1=1, COLUMN2=11, COLUMN2_FIRST=10), Row(COLUMN1=2, COLUMN2=20, COLUMN2_FIRST=20), Row(COLUMN1=2, COLUMN2=21, COLUMN2_FIRST=20)] first_valueNFr})r%r9r6rrrzr\s rVr^r^#sQ DM ma-> ?RVCq-(A AMM4|DPU VCCH JrYc|rtd|||gnd}t|d}tt|j|d|d}||_|S)av Returns the nth value within an ordered group of values. Example:: >>> from snowflake.snowpark.window import Window >>> window = Window.partition_by("column1").order_by("column2") >>> df = session.create_dataframe([[1, 10], [1, 11], [2, 20], [2, 21]], schema=["column1", "column2"]) >>> df.select(df["column1"], df["column2"], nth_value(df["column2"], 2).over(window).as_("column2_2nd")).collect() [Row(COLUMN1=1, COLUMN2=10, COLUMN2_2ND=11), Row(COLUMN1=1, COLUMN2=11, COLUMN2_2ND=11), Row(COLUMN1=2, COLUMN2=20, COLUMN2_2ND=21), Row(COLUMN1=2, COLUMN2=21, COLUMN2_2ND=21)] nth_valueNFr})r%r9r6rrrz)rrrTrQrnrrs rVr`r`#sR EN kAq,+? @SWCq+&A !--D,?5 QCCH JrYc6t|d}td||S)aj Divides an ordered data set equally into the number of buckets specified by n. Buckets are sequentially numbered 1 through n. Args: e: The desired number of buckets; must be a positive integer value. Example:: >>> from snowflake.snowpark.window import Window >>> df = session.create_dataframe( ... [["C", "SPY", 3], ["C", "AAPL", 10], ["N", "SPY", 5], ["N", "AAPL", 7], ["Q", "MSFT", 3]], ... schema=["exchange", "symbol", "shares"] ... ) >>> df.select(col("exchange"), col("symbol"), ntile(3).over(Window.partition_by("exchange").order_by("shares")).alias("ntile_3")).order_by(["exchange","symbol"]).show() ------------------------------------- |"EXCHANGE" |"SYMBOL" |"NTILE_3" | ------------------------------------- |C |AAPL |2 | |C |SPY |1 | |N |AAPL |2 | |N |SPY |1 | |Q |MSFT |1 | ------------------------------------- ntiler}r0rs rVrbrb#s8 a)A '1 ::rYctd||S)aG Return a percentile value based on a continuous distribution of the input column. If no input row lies exactly at the desired percentile, the result is calculated using linear interpolation of the two nearest input values. NULL values are ignored in the calculation. Args: percentile: the percentile of the value that you want to find. The percentile must be a constant between 0.0 and 1.0. For example, if you want to find the value at the 90th percentile, specify 0.9. Example: >>> df = session.create_dataframe([ ... (0, 0), (0, 10), (0, 20), (0, 30), (0, 40), ... (1, 10), (1, 20), (2, 10), (2, 20), (2, 25), ... (2, 30), (3, 60), (4, None) ... ], schema=["k", "v"]) >>> df.group_by("k").agg(percentile_cont(0.25).within_group("v").as_("percentile")).sort("k").collect() [Row(K=0, PERCENTILE=Decimal('10.000')), Row(K=1, PERCENTILE=Decimal('12.500')), Row(K=2, PERCENTILE=Decimal('17.500')), Row(K=3, PERCENTILE=Decimal('60.000')), Row(K=4, PERCENTILE=None)] percentile_contr}r~)r rQs rVrdrd#s6 +Z9 MMrYr.c\|Dcgc]}t|d}}tdg|d|iScc}w)a Returns the largest value from a list of expressions. If any of the argument values is NULL, the result is NULL. GREATEST supports all data types, including VARIANT. Examples:: >>> df = session.create_dataframe([[1, 2, 3], [2, 4, -1], [3, 6, None]], schema=["a", "b", "c"]) >>> df.select(greatest(df["a"], df["b"], df["c"]).alias("greatest")).collect() [Row(GREATEST=3), Row(GREATEST=4), Row(GREATEST=None)] greatestrQrrQr.r2rs rVrfrf $s83::BJ ':A: * >q >I >> ;r/c\|Dcgc]}t|d}}tdg|d|iScc}w)a Returns the smallest value from a list of expressions. If any of the argument values is NULL, the result is NULL. LEAST supports all data types, including VARIANT. Example:: >>> df = session.create_dataframe([[1, 2, 3], [2, 4, -1], [3, 6, None]], schema=["a", "b", "c"]) >>> df.select(least(df["a"], df["b"], df["c"]).alias("least")).collect() [Row(LEAST=1), Row(LEAST=-1), Row(LEAST=None)] leastrQrrgs rVriri$s8077G $7A7 ' ;A ; ;; 8r/c|rtd|||gnd}t|d}tt|j||d}||_|S)a~ Returns the concatenated input values, separated by `delimiter` string. See `LISTAGG `_ for details. Args: e: A :class:`Column` object or column name that determines the values to be put into the list. delimiter: A string delimiter. is_distinct: Whether the input expression is distinct. Examples:: >>> df = session.create_dataframe([1, 2, 3, 2, 4, 5], schema=["col"]) >>> df.select(listagg("col", ",").within_group(df["col"].asc()).as_("result")).collect() [Row(RESULT='1,2,2,3,4,5')] listaggNFr})r%r9r6rrrz)rrrrQrnrrs rVrkrk+$sU4  I9k'BC  q)$A  ;?5 QCCH JrYz*snowflake.snowpark.table.WhenMatchedClausecXtjjj||S)a Specifies a matched clause for the :meth:`Table.merge ` action. See :class:`~snowflake.snowpark.table.WhenMatchedClause` for details. Convenience function to create a new WhenMatchedClause instance which is required together with an action when merging a Snowpark table with a Snowpark DataFrame (see snowflake.snowpark.Table.merge for more details). Example:: >>> target_df = session.create_dataframe([(10, "old"), (10, "too_old"), (11, "old")], schema=["key", "value"]) >>> target_df.write.save_as_table("my_table", mode="overwrite", table_type="temporary") >>> target = session.table("my_table") >>> source = session.create_dataframe([(10, "new"), (12, "new"), (13, "old")], schema=["key", "value"]) >>> target.merge(source, (target["key"] == source["key"]) & (target["value"] == "too_old"), ... [when_matched().update({"value": source["value"]})]) MergeResult(rows_inserted=0, rows_updated=1, rows_deleted=0) >>> target.collect() [Row(KEY=10, VALUE='old'), Row(KEY=10, VALUE='new'), Row(KEY=11, VALUE='old')] r})rrtableWhenMatchedClauser1rQs rV when_matchedrpP$s&0    # # 5 5i9 5 UUrYz-snowflake.snowpark.table.WhenNotMatchedClausecXtjjj||S)a Specifies a not-matched clause for the :meth:`Table.merge ` action. See :class:`~snowflake.snowpark.table.WhenNotMatchedClause` for details. Convenience function to create a new WhenNotMatchedClause instance which is required together with an action when merging a Snowpark table with a Snowpark DataFrame (see snowflake.snowpark.Table.merge for more details). Example:: >>> from snowflake.snowpark.types import IntegerType, StringType, StructField, StructType >>> schema = StructType([StructField("key", IntegerType()), StructField("value", StringType())]) >>> target_df = session.create_dataframe([(10, "old"), (10, "too_old"), (11, "old")], schema=schema) >>> target_df.write.save_as_table("my_table", mode="overwrite", table_type="temporary") >>> target = session.table("my_table") >>> source = session.create_dataframe([(10, "new"), (12, "new"), (13, "old")], schema=schema) >>> target.merge(source, (target["key"] == source["key"]) & (target["value"] == "too_old"), ... [when_not_matched().insert({"key": source["key"]})]) MergeResult(rows_inserted=2, rows_updated=0, rows_deleted=0) >>> target.sort(col("key"), col("value")).collect() [Row(KEY=10, VALUE='old'), Row(KEY=10, VALUE='too_old'), Row(KEY=11, VALUE='old'), Row(KEY=12, VALUE=None), Row(KEY=13, VALUE=None)] r})rrrmWhenNotMatchedClauseros rVwhen_not_matchedrsk$s&2    # # 8 8i 8 XXrY) return_type input_typesr is_permanentstage_locationimportspackagesr6 if_not_existssessionparallelmax_batch_sizestatement_paramssource_code_displaystrictsecureexternal_access_integrationssecrets immutablecommentartifact_repositoryresource_constraintrQfuncrurvrrwrxryrzr6r{r|z"snowflake.snowpark.session.Sessionr}r~rrrrrrrrrrc 4tdi|tjjj | } | t | j }n| jj }|i|jdXtj|fid|d|d|d|d|d|d |d |d | d | d | d| d|d|d|d|d|d|d|d|d|d||S||fid|d|d|d|d|d|d |d |d | d | d | d| d|d|d|d|d|d|d|d|d|d||S)a(Registers a Python function as a Snowflake Python UDF and returns the UDF. It can be used as either a function call or a decorator. In most cases you work with a single session. This function uses that session to register the UDF. If you have multiple sessions, you need to explicitly specify the ``session`` parameter of this function. If you have a function and would like to register it to multiple databases, use ``session.udf.register`` instead. See examples in :class:`~snowflake.snowpark.udf.UDFRegistration`. Args: func: A Python function used for creating the UDF. return_type: A :class:`~snowflake.snowpark.types.DataType` representing the return data type of the UDF. Optional if type hints are provided. input_types: A list of :class:`~snowflake.snowpark.types.DataType` representing the input data types of the UDF. Optional if type hints are provided. name: A string or list of strings that specify the name or fully-qualified object identifier (database name, schema name, and function name) for the UDF in Snowflake, which allows you to call this UDF in a SQL command or via :func:`call_udf()`. If it is not provided, a name will be automatically generated for the UDF. A name must be specified when ``is_permanent`` is ``True``. is_permanent: Whether to create a permanent UDF. The default is ``False``. If it is ``True``, a valid ``stage_location`` must be provided. stage_location: The stage location where the Python file for the UDF and its dependencies should be uploaded. The stage location must be specified when ``is_permanent`` is ``True``, and it will be ignored when ``is_permanent`` is ``False``. It can be any stage other than temporary stages and external stages. imports: A list of imports that only apply to this UDF. You can use a string to represent a file path (similar to the ``path`` argument in :meth:`~snowflake.snowpark.Session.add_import`) in this list, or a tuple of two strings to represent a file path and an import path (similar to the ``import_path`` argument in :meth:`~snowflake.snowpark.Session.add_import`). These UDF-level imports will override the session-level imports added by :meth:`~snowflake.snowpark.Session.add_import`. Note that an empty list means no import for this UDF, and ``None`` or not specifying this parameter means using session-level imports. packages: A list of packages that only apply to this UDF. These UDF-level packages will override the session-level packages added by :meth:`~snowflake.snowpark.Session.add_packages` and :meth:`~snowflake.snowpark.Session.add_requirements`. Note that an empty list means no package for this UDF, and ``None`` or not specifying this parameter means using session-level packages. To use Python packages that are not available in Snowflake, refer to :meth:`~snowflake.snowpark.Session.custom_package_usage_config`. replace: Whether to replace a UDF that already was registered. The default is ``False``. If it is ``False``, attempting to register a UDF with a name that already exists results in a ``SnowparkSQLException`` exception being thrown. If it is ``True``, an existing UDF with the same name is overwritten. if_not_exists: Whether to skip creation of a UDF when one with the same signature already exists. The default is ``False``. ``if_not_exists`` and ``replace`` are mutually exclusive and a ``ValueError`` is raised when both are set. If it is ``True`` and a UDF with the same signature exists, the UDF creation is skipped. session: Use this session to register the UDF. If it's not specified, the session that you created before calling this function will be used. You need to specify this parameter if you have created multiple sessions before calling this method. parallel: The number of threads to use for uploading UDF files with the `PUT `_ command. The default value is 4 and supported values are from 1 to 99. Increasing the number of threads can improve performance when uploading large UDF files. max_batch_size: The maximum number of rows per input pandas DataFrame or pandas Series inside a vectorized UDF. Because a vectorized UDF will be executed within a time limit, which is `60` seconds, this optional argument can be used to reduce the running time of every batch by setting a smaller batch size. Note that setting a larger value does not guarantee that Snowflake will encode batches with the specified number of rows. It will be ignored when registering a non-vectorized UDF. statement_params: Dictionary of statement level parameters to be set while executing this action. source_code_display: Display the source code of the UDF `func` as comments in the generated script. The source code is dynamically generated therefore it may not be identical to how the `func` is originally defined. The default is ``True``. If it is ``False``, source code will not be generated or displayed. strict: Whether the created UDF is strict. A strict UDF will not invoke the UDF if any input is null. Instead, a null value will always be returned for that row. Note that the UDF might still return null for non-null inputs. secure: Whether the created UDF is secure. For more information about secure functions, see `Secure UDFs `_. external_access_integrations: The names of one or more external access integrations. Each integration you specify allows access to the external network locations and secrets the integration specifies. secrets: The key-value pairs of string types of secrets used to authenticate the external network location. The secrets can be accessed from handler code. The secrets specified as values must also be specified in the external access integration and the keys are strings used to retrieve the secrets using secret API. immutable: Whether the UDF result is deterministic or not for the same input. comment: Adds a comment for the created object. See `COMMENT `_ artifact_repository: The name of an artifact_repository that packages are found in. If unspecified, packages are pulled from Anaconda. resource_constraint: A dictionary containing a resource properties of a warehouse and then constraints needed to run this function. Eg ``{"architecture": "x86"}`` requires an x86 warehouse be used for execution. Returns: A UDF function that can be called with :class:`~snowflake.snowpark.Column` expressions. Note: 1. When type hints are provided and are complete for a function, ``return_type`` and ``input_types`` are optional and will be ignored. See details of supported data types for UDFs in :class:`~snowflake.snowpark.udf.UDFRegistration`. - You can use use :attr:`~snowflake.snowpark.types.Variant` to annotate a variant, and use :attr:`~snowflake.snowpark.types.Geography` or :attr:`~snowflake.snowpark.types.Geometry` to annotate geospatial types when defining a UDF. - You can use use :attr:`~snowflake.snowpark.types.PandasSeries` to annotate a pandas Series, and use :attr:`~snowflake.snowpark.types.PandasDataFrame` to annotate a pandas DataFrame when defining a vectorized UDF. Note that they are generic types so you can specify the element type in a pandas Series and DataFrame. - :class:`typing.Union` is not a valid type annotation for UDFs, but :class:`typing.Optional` can be used to indicate the optional type. - Type hints are not supported on functions decorated with decorators. 2. A temporary UDF (when ``is_permanent`` is ``False``) is scoped to this ``session`` and all UDF related files will be uploaded to a temporary session stage (:func:`session.get_session_stage() `). For a permanent UDF, these files will be uploaded to the stage that you provide. 3. By default, UDF registration fails if a function with the same name is already registered. Invoking :func:`udf` with ``replace`` set to ``True`` will overwrite the previously registered function. 4. When registering a vectorized UDF, ``pandas`` library will be added as a package automatically, with the latest version on the Snowflake server. If you don't want to use this version, you can overwrite it by adding `pandas` with specific version requirement using ``package`` argument or :meth:`~snowflake.snowpark.Session.add_packages`. See Also: :class:`~snowflake.snowpark.udf.UDFRegistration` UDFs can be created as anonymous UDFs Example:: >>> from snowflake.snowpark.types import IntegerType >>> add_one = udf(lambda x: x+1, return_type=IntegerType(), input_types=[IntegerType()]) >>> df = session.create_dataframe([1, 2, 3], schema=["a"]) >>> df.select(add_one(col("a")).as_("ans")).collect() [Row(ANS=2), Row(ANS=3), Row(ANS=4)] or as named UDFs that are accessible in the same session. Instead of calling `udf` as function, it can be also used as a decorator: Example:: >>> @udf(name="minus_one", replace=True) ... def minus_one(x: int) -> int: ... return x - 1 >>> df.select(minus_one(col("a")).as_("ans")).collect() [Row(ANS=0), Row(ANS=1), Row(ANS=2)] >>> session.sql("SELECT minus_one(10)").collect() [Row(MINUS_ONE(10)=9)] r|_registered_object_namerurvrrwrxryrzr6r{r}r~rrrrrrrrrrrQrT) r,rrr|'_get_sandbox_conditional_active_sessionrGregisterudfrX functoolspartial)rrurvrrwrxryrzr6r{r|r}r~rrrrrrrrrrrQrRudf_registration_methods rVrr$sOx"6"  ((PPG"1'"B"K"K")++"6"6 | #<=E  # # $   &  *     (  * . !4  ! "*F# $% & ' () *!4+ ,!4- . 1  6'  # $   &  *     (  * . !4  ! "*F# $% & ' () *!4+ ,!4- . 1  rY)rvrrwrxryrzr6r{r|r}rrrrrrrrrrQhandler output_schemar@c tdi|tjjj | } | t | j }n| jj }|c|jdRtj|fid|d|d|d|d|d|d |d |d | d | d | d| d|d|d|d|d|d|d|d||S||fid|d|d|d|d|d|d |d |d | d | d | d| d|d|d|d|d|d|d|d||S)a&Registers a Python class as a Snowflake Python UDTF and returns the UDTF. It can be used as either a function call or a decorator. In most cases you work with a single session. This function uses that session to register the UDTF. If you have multiple sessions, you need to explicitly specify the ``session`` parameter of this function. If you have a function and would like to register it to multiple databases, use ``session.udtf.register`` instead. See examples in :class:`~snowflake.snowpark.udtf.UDTFRegistration`. Args: handler: A Python class used for creating the UDTF. output_schema: A list of column names, or a :class:`~snowflake.snowpark.types.StructType` instance that represents the table function's columns, or a ``PandasDataFrameType`` instance for vectorized UDTF. If a list of column names is provided, the ``process`` method of the handler class must have return type hints to indicate the output schema data types. input_types: A list of :class:`~snowflake.snowpark.types.DataType` representing the input data types of the UDTF. Optional if type hints are provided. name: A string or list of strings that specify the name or fully-qualified object identifier (database name, schema name, and function name) for the UDTF in Snowflake, which allows you to call this UDTF in a SQL command or via :func:`call_udtf()`. If it is not provided, a name will be automatically generated for the UDTF. A name must be specified when ``is_permanent`` is ``True``. is_permanent: Whether to create a permanent UDTF. The default is ``False``. If it is ``True``, a valid ``stage_location`` must be provided. stage_location: The stage location where the Python file for the UDTF and its dependencies should be uploaded. The stage location must be specified when ``is_permanent`` is ``True``, and it will be ignored when ``is_permanent`` is ``False``. It can be any stage other than temporary stages and external stages. imports: A list of imports that only apply to this UDTF. You can use a string to represent a file path (similar to the ``path`` argument in :meth:`~snowflake.snowpark.Session.add_import`) in this list, or a tuple of two strings to represent a file path and an import path (similar to the ``import_path`` argument in :meth:`~snowflake.snowpark.Session.add_import`). These UDTF-level imports will override the session-level imports added by :meth:`~snowflake.snowpark.Session.add_import`. packages: A list of packages that only apply to this UDTF. These UDTF-level packages will override the session-level packages added by :meth:`~snowflake.snowpark.Session.add_packages` and :meth:`~snowflake.snowpark.Session.add_requirements`. To use Python packages that are not available in Snowflake, refer to :meth:`~snowflake.snowpark.Session.custom_package_usage_config`. replace: Whether to replace a UDTF that already was registered. The default is ``False``. If it is ``False``, attempting to register a UDTF with a name that already exists results in a ``SnowparkSQLException`` exception being thrown. If it is ``True``, an existing UDTF with the same name is overwritten. if_not_exists: Whether to skip creation of a UDTF when one with the same signature already exists. The default is ``False``. ``if_not_exists`` and ``replace`` are mutually exclusive and a ``ValueError`` is raised when both are set. If it is ``True`` and a UDTF with the same signature exists, the UDTF creation is skipped. session: Use this session to register the UDTF. If it's not specified, the session that you created before calling this function will be used. You need to specify this parameter if you have created multiple sessions before calling this method. parallel: The number of threads to use for uploading UDTF files with the `PUT `_ command. The default value is 4 and supported values are from 1 to 99. Increasing the number of threads can improve performance when uploading large UDTF files. statement_params: Dictionary of statement level parameters to be set while executing this action. strict: Whether the created UDTF is strict. A strict UDTF will not invoke the UDTF if any input is null. Instead, a null value will always be returned for that row. Note that the UDTF might still return null for non-null inputs. secure: Whether the created UDTF is secure. For more information about secure functions, see `Secure UDFs `_. external_access_integrations: The names of one or more external access integrations. Each integration you specify allows access to the external network locations and secrets the integration specifies. secrets: The key-value pairs of string types of secrets used to authenticate the external network location. The secrets can be accessed from handler code. The secrets specified as values must also be specified in the external access integration and the keys are strings used to retrieve the secrets using secret API. immutable: Whether the UDTF result is deterministic or not for the same input. comment: Adds a comment for the created object. See `COMMENT `_ artifact_repository: The name of an artifact_repository that packages are found in. If unspecified, packages are pulled from Anaconda. resource_constraint: A dictionary containing a resource properties of a warehouse and then constraints needed to run this function. Eg ``{"architecture": "x86"}`` requires an x86 warehouse be used for execution. Returns: A UDTF function that can be called with :class:`~snowflake.snowpark.Column` expressions. Note: 1. When type hints are provided and are complete for a function, ``return_type`` and ``input_types`` are optional and will be ignored. See details of supported data types for UDTFs in :class:`~snowflake.snowpark.udtf.UDTFRegistration`. - You can use use :attr:`~snowflake.snowpark.types.Variant` to annotate a variant, and use :attr:`~snowflake.snowpark.types.Geography` or :attr:`~snowflake.snowpark.types.Geometry` to annotate geospatial types when defining a UDTF. - :class:`typing.Union` is not a valid type annotation for UDTFs, but :class:`typing.Optional` can be used to indicate the optional type. - Type hints are not supported on functions decorated with decorators. 2. A temporary UDTF (when ``is_permanent`` is ``False``) is scoped to this ``session`` and all UDTF related files will be uploaded to a temporary session stage (:func:`session.get_session_stage() `). For a permanent UDTF, these files will be uploaded to the stage that you specify. 3. By default, UDTF registration fails if a function with the same name is already registered. Invoking :func:`udtf` with ``replace`` set to ``True`` will overwrite the previously registered function. See Also: :class:`~snowflake.snowpark.udtf.UDTFRegistration` Example:: >>> from snowflake.snowpark.types import IntegerType, StructField, StructType >>> class PrimeSieve: ... def process(self, n): ... is_prime = [True] * (n + 1) ... is_prime[0] = False ... is_prime[1] = False ... p = 2 ... while p * p <= n: ... if is_prime[p]: ... # set all multiples of p to False ... for i in range(p * p, n + 1, p): ... is_prime[i] = False ... p += 1 ... # yield all prime numbers ... for p in range(2, n + 1): ... if is_prime[p]: ... yield (p,) >>> prime_udtf = udtf(PrimeSieve, output_schema=StructType([StructField("number", IntegerType())]), input_types=[IntegerType()]) >>> session.table_function(prime_udtf(lit(20))).collect() [Row(NUMBER=2), Row(NUMBER=3), Row(NUMBER=5), Row(NUMBER=7), Row(NUMBER=11), Row(NUMBER=13), Row(NUMBER=17), Row(NUMBER=19)] Instead of calling `udtf` it is also possible to use udtf as a decorator. Example:: >>> @udtf(name="alt_int",replace=True, output_schema=StructType([StructField("number", IntegerType())]), input_types=[IntegerType()]) ... class Alternator: ... def __init__(self): ... self._positive = True ... ... def process(self, n): ... for i in range(n): ... if self._positive: ... yield (1,) ... else: ... yield (-1,) ... self._positive = not self._positive >>> session.table_function("alt_int", lit(3)).collect() [Row(NUMBER=1), Row(NUMBER=-1), Row(NUMBER=1)] >>> session.table_function("alt_int", lit(2)).collect() [Row(NUMBER=1), Row(NUMBER=-1)] >>> session.table_function("alt_int", lit(1)).collect() [Row(NUMBER=1)] rrrrvrrwrxryrzr6r{r}rrrrrrrrrrQrT) r,rrr|rrIrudtfrXrr)rrrvrrwrxryrzr6r{r|r}rrrrrrrrrrQrRudtf_registration_methods rVrr%s'p"6"  ((PPG#3G#D#M#M #*<<#8#8 6::&?@H  $ ' $   &  *     (  .   *F ! " # $% &!4' (!4) * -  2(  ' $   &  *     (  .   *F ! " # $% &!4' (!4) * -  rY)rurvrrwrxryrzr6r{r|r}rrrrrrrrQc tdi|tjjj | } | t | j }n| jj }|]|jdLtj|fid|d|d|d|d|d|d |d |d | d | d | d| d|d|d|d|d|d||S||fid|d|d|d|d|d|d |d |d | d | d | d| d|d|d|d|d|d||S)a$Registers a Python class as a Snowflake Python UDAF and returns the UDAF. It can be used as either a function call or a decorator. In most cases you work with a single session. This function uses that session to register the UDAF. If you have multiple sessions, you need to explicitly specify the ``session`` parameter of this function. If you have a function and would like to register it to multiple databases, use ``session.udaf.register`` instead. See examples in :class:`~snowflake.snowpark.udaf.UDAFRegistration`. Args: handler: A Python class used for creating the UDAF. return_type: A :class:`~snowflake.snowpark.types.DataType` representing the return data type of the UDAF. Optional if type hints are provided. input_types: A list of :class:`~snowflake.snowpark.types.DataType` representing the input data types of the UDAF. Optional if type hints are provided. name: A string or list of strings that specify the name or fully-qualified object identifier (database name, schema name, and function name) for the UDAF in Snowflake, which allows you to call this UDAF in a SQL command or via :func:`DataFrame.agg`. If it is not provided, a name will be automatically generated for the UDAF. A name must be specified when ``is_permanent`` is ``True``. is_permanent: Whether to create a permanent UDAF. The default is ``False``. If it is ``True``, a valid ``stage_location`` must be provided. stage_location: The stage location where the Python file for the UDAF and its dependencies should be uploaded. The stage location must be specified when ``is_permanent`` is ``True``, and it will be ignored when ``is_permanent`` is ``False``. It can be any stage other than temporary stages and external stages. imports: A list of imports that only apply to this UDAF. You can use a string to represent a file path (similar to the ``path`` argument in :meth:`~snowflake.snowpark.Session.add_import`) in this list, or a tuple of two strings to represent a file path and an import path (similar to the ``import_path`` argument in :meth:`~snowflake.snowpark.Session.add_import`). These UDAF-level imports will override the session-level imports added by :meth:`~snowflake.snowpark.Session.add_import`. Note that an empty list means no import for this UDAF, and ``None`` or not specifying this parameter means using session-level imports. packages: A list of packages that only apply to this UDAF. These UDAF-level packages will override the session-level packages added by :meth:`~snowflake.snowpark.Session.add_packages` and :meth:`~snowflake.snowpark.Session.add_requirements`. Note that an empty list means no package for this UDAF, and ``None`` or not specifying this parameter means using session-level packages. To use Python packages that are not available in Snowflake, refer to :meth:`~snowflake.snowpark.Session.custom_package_usage_config`. replace: Whether to replace a UDAF that already was registered. The default is ``False``. If it is ``False``, attempting to register a UDAF with a name that already exists results in a ``SnowparkSQLException`` exception being thrown. If it is ``True``, an existing UDAF with the same name is overwritten. if_not_exists: Whether to skip creation of a UDAF when one with the same signature already exists. The default is ``False``. ``if_not_exists`` and ``replace`` are mutually exclusive and a ``ValueError`` is raised when both are set. If it is ``True`` and a UDAF with the same signature exists, the UDAF creation is skipped. session: Use this session to register the UDAF. If it's not specified, the session that you created before calling this function will be used. You need to specify this parameter if you have created multiple sessions before calling this method. parallel: The number of threads to use for uploading UDAF files with the `PUT `_ command. The default value is 4 and supported values are from 1 to 99. Increasing the number of threads can improve performance when uploading large UDAF files. statement_params: Dictionary of statement level parameters to be set while executing this action. immutable: Whether the UDAF result is deterministic or not for the same input. external_access_integrations: The names of one or more external access integrations. Each integration you specify allows access to the external network locations and secrets the integration specifies. secrets: The key-value pairs of string types of secrets used to authenticate the external network location. The secrets can be accessed from handler code. The secrets specified as values must also be specified in the external access integration and the keys are strings used to retrieve the secrets using secret API. comment: Adds a comment for the created object. See `COMMENT `_ artifact_repository: The name of an artifact_repository that packages are found in. If unspecified, packages are pulled from Anaconda. resource_constraint: A dictionary containing a resource properties of a warehouse and then constraints needed to run this function. Eg ``{"architecture": "x86"}`` requires an x86 warehouse be used for execution. Returns: A UDAF function that can be called with :class:`~snowflake.snowpark.Column` expressions. Note: 1. When type hints are provided and are complete for a function, ``return_type`` and ``input_types`` are optional and will be ignored. See details of supported data types for UDAFs in :class:`~snowflake.snowpark.udaf.UDAFRegistration`. - You can use use :attr:`~snowflake.snowpark.types.Variant` to annotate a variant, and use :attr:`~snowflake.snowpark.types.Geography` to annotate a geography when defining a UDAF. - :class:`typing.Union` is not a valid type annotation for UDAFs, but :class:`typing.Optional` can be used to indicate the optional type. - Type hints are not supported on functions decorated with decorators. 2. A temporary UDAF (when ``is_permanent`` is ``False``) is scoped to this ``session`` and all UDAF related files will be uploaded to a temporary session stage (:func:`session.get_session_stage() `). For a permanent UDAF, these files will be uploaded to the stage that you provide. 3. By default, UDAF registration fails if a function with the same name is already registered. Invoking :func:`udaf` with ``replace`` set to ``True`` will overwrite the previously registered function. See Also: :class:`~snowflake.snowpark.udaf.UDAFRegistration` Example:: >>> from snowflake.snowpark.types import IntegerType >>> class PythonSumUDAF: ... def __init__(self) -> None: ... self._sum = 0 ... ... @property ... def aggregate_state(self): ... return self._sum ... ... def accumulate(self, input_value): ... self._sum += input_value ... ... def merge(self, other_sum): ... self._sum += other_sum ... ... def finish(self): ... return self._sum >>> sum_udaf = udaf( ... PythonSumUDAF, ... name="sum_int", ... replace=True, ... return_type=IntegerType(), ... input_types=[IntegerType()], ... ) >>> df = session.create_dataframe([[1, 3], [1, 4], [2, 5], [2, 6]]).to_df("a", "b") >>> df.agg(sum_udaf("a")).collect() [Row(SUM_INT("A")=6)] Instead of calling `udaf` it is also possible to use udaf as a decorator. Example:: >>> @udaf(name="sum_int", replace=True, return_type=IntegerType(), input_types=[IntegerType()]) ... class PythonSumUDAF: ... def __init__(self) -> None: ... self._sum = 0 ... ... @property ... def aggregate_state(self): ... return self._sum ... ... def accumulate(self, input_value): ... self._sum += input_value ... ... def merge(self, other_sum): ... self._sum += other_sum ... ... def finish(self): ... return self._sum >>> df = session.create_dataframe([[1, 3], [1, 4], [2, 5], [2, 6]]).to_df("a", "b") >>> df.agg(PythonSumUDAF("a")).collect() [Row(SUM_INT("A")=6)] rrrurvrrwrxryrzr6r{r}rrrrrrrrQrT) r,rrr|rrErudafrXrr)rrurvrrwrxryrzr6r{r|r}rrrrrrrrQrRudaf_registration_methods rVrr|&s|"6"  ((PPG#3G#D#M#M #*<<#8#8 6::&?@H  $ # $   &  *     (  .   *F  ! "!4# $!4% & )  .(  # $   &  *     (  .   *F  ! "!4# $!4% & )  rY)rurvrrwrxryrzr6r{r|r}r~rrrrrrrrrQc t|fid|d|d|d|d|d|d|d|d | d | d | d | d | d|d|d|d|d|d|d|ddd||S)a Registers a Python function as a vectorized UDF and returns the UDF. The arguments, return value and usage of this function are exactly the same as :func:`udf`, but this function can only be used for registering vectorized UDFs. See examples in :class:`~snowflake.snowpark.udf.UDFRegistration`. See Also: - :func:`udf` - :meth:`UDFRegistration.register() ` Example:: >>> from snowflake.snowpark.types import PandasSeriesType, PandasDataFrameType, IntegerType >>> add_one_df_pandas_udf = pandas_udf( ... lambda df: df[0] + df[1] + 1, ... return_type=PandasSeriesType(IntegerType()), ... input_types=[PandasDataFrameType([IntegerType(), IntegerType()])] ... ) >>> df = session.create_dataframe([[1, 2], [3, 4]], schema=["a", "b"]) >>> df.select(add_one_df_pandas_udf("a", "b").alias("result")).order_by("result").show() ------------ |"RESULT" | ------------ |4 | |8 | ------------ or as named pandas UDFs that are accesible in the same session. Instead of calling `pandas_udf` as function, it can be also used as a decorator: Example:: >>> from snowflake.snowpark.types import PandasSeriesType, PandasDataFrameType, IntegerType >>> @pandas_udf( ... return_type=PandasSeriesType(IntegerType()), ... input_types=[PandasDataFrameType([IntegerType(), IntegerType()])], ... ) ... def add_one_df_pandas_udf(df): ... return df[0] + df[1] + 1 >>> df = session.create_dataframe([[1, 2], [3, 4]], schema=["a", "b"]) >>> df.select(add_one_df_pandas_udf("a", "b").alias("result")).order_by("result").show() ------------ |"RESULT" | ------------ |4 | |8 | ------------ rurvrrwrxryrzr6r{r|r}r~rrrrrrrr_from_pandas_udf_functionTrQ)r)rrurvrrwrxryrzr6r{r|r}r~rrrrrrrrrQrRs rV pandas_udfrt's^         "   &     $   & * 0  ! "# $&B% &' () *+ ,#'- . 1 rYr)cfd}|S)aMarks a function or UDTF method as vectorized for pandas input. This decorator is a no-op for local invocation. When combined with :func:`udf`, this will make the function behave as a vectorized UDF using :func:`pandas_udf`. Args: input: The type of the input to the function. Must be either ``pandas.Series`` or ``pandas.DataFrame``. max_batch_size: The maximum batch size to use for the function. If not provided, the default batch size will be used. Returns: A decorator that marks the function as vectorized. Example:: >>> import pandas as pd >>> from snowflake.snowpark.functions import udf, vectorized >>> from snowflake.snowpark.types import IntegerType >>> @udf(return_type=IntegerType(), input_types=[IntegerType(), IntegerType()]) ... @vectorized(input=pd.DataFrame) ... def add_one_to_inputs(df): ... return df[0] + df[1] + 1 >>> df = session.create_dataframe([[1, 2], [3, 4]], schema=["a", "b"]) >>> df.select(add_one_to_inputs("a", "b").alias("result")).collect() [Row(RESULT=4), Row(RESULT=8)] See Also: - :func:`udf` - :func:`pandas_udf` cv_t_tjfd}|S)Nc|i|SrNrT)rJrRrs rV_innerz.vectorized.._decorator.._inner(sd%f% %rY)_sf_vectorized_inputrG_sf_max_batch_sizerwraps)rrr)r~s` rV _decoratorzvectorized.._decorator'sB!&  %#&~#6A    &  & rYrT)r)r~rs`` rV vectorizedr's>  rY)rv input_namesrrwrxryrzr6r{r|r}rrrrrrr~rrQrc t|fid|d|d|d|d|d|d|d|d | d | d | d | d | d|d|d|d|d|d|d|d||S)aqRegisters a Python class as a vectorized Python UDTF and returns the UDTF. The arguments, return value and usage of this function are exactly the same as :func:`udtf`, but this function can only be used for registering vectorized UDTFs. See examples in :class:`~snowflake.snowpark.udtf.UDTFRegistration`. See Also: - :func:`udtf` - :meth:`UDTFRegistration.register() ` Compared to the default row-by-row processing pattern of a normal UDTF, which sometimes is inefficient, vectorized Python UDTFs (user-defined table functions) enable seamless partition-by-partition processing by operating on partitions as `pandas DataFrames `_ and returning results as `pandas DataFrames `_ or lists of `pandas arrays `_ or `pandas Series `_. In addition, vectorized Python UDTFs allow for easy integration with libraries that operate on pandas DataFrames or pandas arrays. A vectorized UDTF handler class: - defines an :code:`end_partition` method that takes in a DataFrame argument and returns a :code:`pandas.DataFrame` or a tuple of :code:`pandas.Series` or :code:`pandas.arrays` where each array is a column. - does NOT define a :code:`process` method. - optionally defines a handler class with an :code:`__init__` method which will be invoked before processing each partition. You can use :func:`~snowflake.snowpark.functions.udtf`, :meth:`register` or :func:`~snowflake.snowpark.functions.pandas_udtf` to create a vectorized UDTF by providing appropriate return and input types. If you would like to use :meth:`register_from_file` to create a vectorized UDTF, you need to explicitly mark the handler method as vectorized using either the decorator `@vectorized(input=pandas.DataFrame)` or setting `.end_partition._sf_vectorized_input = pandas.DataFrame` Note: A vectorized UDTF must be called with `~snowflake.snowpark.Window.partition_by` to build the partitions. Example:: >>> from snowflake.snowpark.types import PandasSeriesType, PandasDataFrameType, IntegerType >>> class multiply: ... def __init__(self): ... self.multiplier = 10 ... def end_partition(self, df): ... df.col1 = df.col1*self.multiplier ... df.col2 = df.col2*self.multiplier ... yield df >>> multiply_udtf = pandas_udtf( ... multiply, ... output_schema=PandasDataFrameType([StringType(), IntegerType(), FloatType()], ["id_", "col1_", "col2_"]), ... input_types=[PandasDataFrameType([StringType(), IntegerType(), FloatType()])], ... input_names=['"id"', '"col1"', '"col2"'] ... ) >>> df = session.create_dataframe([['x', 3, 35.9],['x', 9, 20.5]], schema=["id", "col1", "col2"]) >>> df.select(multiply_udtf("id", "col1", "col2").over(partition_by=["id"])).sort("col1_").show() ----------------------------- |"ID_" |"COL1_" |"COL2_" | ----------------------------- |x |30 |359.0 | |x |90 |205.0 | ----------------------------- Example:: >>> @pandas_udtf( ... output_schema=PandasDataFrameType([StringType(), IntegerType(), FloatType()], ["id_", "col1_", "col2_"]), ... input_types=[PandasDataFrameType([StringType(), IntegerType(), FloatType()])], ... input_names=['"id"', '"col1"', '"col2"'] ... ) ... class _multiply: ... def __init__(self): ... self.multiplier = 10 ... def end_partition(self, df): ... df.col1 = df.col1*self.multiplier ... df.col2 = df.col2*self.multiplier ... yield df >>> df.select(multiply_udtf("id", "col1", "col2").over(partition_by=["id"])).sort("col1_").show() ----------------------------- |"ID_" |"COL1_" |"COL2_" | ----------------------------- |x |30 |359.0 | |x |90 |205.0 | ----------------------------- rrvrrrwrxryrzr6r{r|r}rrrrrrr~rrQ)r)rrrvrrrwrxryrzr6r{r|r}rrrrrrr~rrQrRs rV pandas_udtfr(s^  #         "  &    $   *   ! "&B# $% &' (&) *+ , / rYudf_namec`t||rtd|g|nd}t|g|d||dS)a}Calls a user-defined function (UDF) by name. Args: udf_name: The name of UDF in Snowflake. args: Arguments can be in two types: - :class:`~snowflake.snowpark.Column`, or - Basic Python types, which are converted to Snowpark literals. Example:: >>> from snowflake.snowpark.types import IntegerType >>> udf_def = session.udf.register(lambda x, y: x + y, name="add_columns", input_types=[IntegerType(), IntegerType()], return_type=IntegerType(), replace=True) >>> df = session.create_dataframe([[1, 2]], schema=["a", "b"]) >>> df.select(call_udf("add_columns", col("a"), col("b"))).show() ------------------------------- |"ADD_COLUMNS(""A"", ""B"")" | ------------------------------- |3 | ------------------------------- call_udfNzfunctions.call_udf)api_call_sourcerzrQ)r0r%r)rrQrJrns rVrr(sM."@I j8*;d*; >> from snowflake.snowpark.functions import lit >>> session.table_function(call_table_function("split_to_table", lit("split words to table"), lit(" ")).over()).collect() [Row(SEQ=1, INDEX=1, VALUE='split'), Row(SEQ=1, INDEX=2, VALUE='words'), Row(SEQ=1, INDEX=3, VALUE='to'), Row(SEQ=1, INDEX=4, VALUE='table')] Nry)rorpr!rrrr*)rrQrJrRrnrs rVcall_table_functionr(sl, Cjjl']LTLVL""11CC#&)?EI rYcBfd}|r tdgnd}||_|S)a Create a function object to invoke a Snowflake table function. Args: function_name: The name of the table function. Example:: >>> from snowflake.snowpark.functions import lit >>> split_to_table = table_function("split_to_table") >>> session.table_function(split_to_table(lit("split words to table"), lit(" ")).over()).collect() [Row(SEQ=1, INDEX=1, VALUE='split'), Row(SEQ=1, INDEX=2, VALUE='words'), Row(SEQ=1, INDEX=3, VALUE='to'), Row(SEQ=1, INDEX=4, VALUE='table')] c"tg|i|SrN)r)rJrRrs rVz table_function..(s !4"" &"rYrN)r%rz)rrQfnrns` rVrr(s/ B EN . @SWCBG IrYc4tj|g|d|iS)aInvokes a Snowflake `system-defined function `_ (built-in function) with the specified name and arguments. Args: function_name: The name of built-in function in Snowflake args: Arguments can be in two types: - :class:`~snowflake.snowpark.Column`, or - Basic Python types, which are converted to Snowpark literals. Example:: >>> df = session.create_dataframe([1, 2, 3, 4], schema=["a"]) # a single column with 4 rows >>> df.select(call_function("avg", col("a"))).show() ---------------- |"AVG(""A"")" | ---------------- |2.500000 | ---------------- rQ)r call_function)rrQrJs rVrr(s6  * *= U4 U9 UUrYc0tj||S)a Function object to invoke a Snowflake `system-defined function `_ (built-in function). Use this to invoke any built-in functions not explicitly listed in this object. Args: function_name: The name of built-in function in Snowflake. Returns: A :class:`Callable` object for calling a Snowflake system-defined function. Example:: >>> df = session.create_dataframe([1, 2, 3, 4], schema=["a"]) # a single column with 4 rows >>> df.select(call_function("avg", col("a"))).show() ---------------- |"AVG(""A"")" | ---------------- |2.500000 | ---------------- >>> my_avg = function('avg') >>> df.select(my_avg(col("a"))).show() ---------------- |"AVG(""A"")" | ---------------- |2.500000 | ---------------- r})r function)rrQs rVrr)s<  % %my IIrYrrzc |r| t||}tt||jDcic]\}}|tj|c}}|||Scc}}w)N)rry)r%r6ritemsr)rrRrrzrQrrs rV_call_named_arguments_functionr5)seT\"40  /5||~ >tq!Q" " >+   ?s A owner)rurvrrwrxryrzr6r{r|r}r execute_asrrrrrrQrrzsnowflake.snowpark.Sessionr)callerrzrestricted callerc tdi|tjjj | } | t | j }n| jj }|c|jdRtj|fid|d|d|d|d|d|d |d |d | d | d | d| d|d|d|d|d|d|d|d||S||fid|d|d|d|d|d|d |d |d | d | d | d| d|d|d|d|d|d|d|d||S)a&Registers a Python function as a Snowflake Python stored procedure and returns the stored procedure. It can be used as either a function call or a decorator. In most cases you work with a single session. This function uses that session to register the stored procedure. If you have multiple sessions, you need to explicitly specify the ``session`` parameter of this function. If you have a function and would like to register it to multiple databases, use ``session.sproc.register`` instead. See examples in :class:`~snowflake.snowpark.stored_procedure.StoredProcedureRegistration`. Note that the first parameter of your function should be a snowpark Session. Also, you need to add `snowflake-snowpark-python` package (version >= 0.4.0) to your session before trying to create a stored procedure. Args: func: A Python function used for creating the stored procedure. return_type: A :class:`~snowflake.snowpark.types.DataType` representing the return data type of the stored procedure. Optional if type hints are provided. input_types: A list of :class:`~snowflake.snowpark.types.DataType` representing the input data types of the stored procedure. Optional if type hints are provided. name: A string or list of strings that specify the name or fully-qualified object identifier (database name, schema name, and function name) for the stored procedure in Snowflake, which allows you to call this stored procedure in a SQL command or via :func:`session.call()`. If it is not provided, a name will be automatically generated for the stored procedure. A name must be specified when ``is_permanent`` is ``True``. is_permanent: Whether to create a permanent stored procedure. The default is ``False``. If it is ``True``, a valid ``stage_location`` must be provided. stage_location: The stage location where the Python file for the stored procedure and its dependencies should be uploaded. The stage location must be specified when ``is_permanent`` is ``True``, and it will be ignored when ``is_permanent`` is ``False``. It can be any stage other than temporary stages and external stages. imports: A list of imports that only apply to this stored procedure. You can use a string to represent a file path (similar to the ``path`` argument in :meth:`~snowflake.snowpark.Session.add_import`) in this list, or a tuple of two strings to represent a file path and an import path (similar to the ``import_path`` argument in :meth:`~snowflake.snowpark.Session.add_import`). These stored-proc-level imports will override the session-level imports added by :meth:`~snowflake.snowpark.Session.add_import`. packages: A list of packages that only apply to this stored procedure. These stored-proc-level packages will override the session-level packages added by :meth:`~snowflake.snowpark.Session.add_packages` and :meth:`~snowflake.snowpark.Session.add_requirements`. To use Python packages that are not available in Snowflake, refer to :meth:`~snowflake.snowpark.Session.custom_package_usage_config`. replace: Whether to replace a stored procedure that already was registered. The default is ``False``. If it is ``False``, attempting to register a stored procedure with a name that already exists results in a ``SnowparkSQLException`` exception being thrown. If it is ``True``, an existing stored procedure with the same name is overwritten. if_not_exists: Whether to skip creation of a stored procedure the same procedure is already registered. The default is ``False``. ``if_not_exists`` and ``replace`` are mutually exclusive and a ``ValueError`` is raised when both are set. If it is ``True`` and a stored procedure is already registered, the registration is skipped. session: Use this session to register the stored procedure. If it's not specified, the session that you created before calling this function will be used. You need to specify this parameter if you have created multiple sessions before calling this method. parallel: The number of threads to use for uploading stored procedure files with the `PUT `_ command. The default value is 4 and supported values are from 1 to 99. Increasing the number of threads can improve performance when uploading large stored procedure files. execute_as: What permissions should the procedure have while executing. This supports caller, or owner for now. See `owner and caller rights `_ for more information. statement_params: Dictionary of statement level parameters to be set while executing this action. strict: Whether the created stored procedure is strict. A strict stored procedure will not invoke the stored procedure if any input is null. Instead, a null value will always be returned. Note that the stored procedure might still return null for non-null inputs. source_code_display: Display the source code of the stored procedure `func` as comments in the generated script. The source code is dynamically generated therefore it may not be identical to how the `func` is originally defined. The default is ``True``. If it is ``False``, source code will not be generated or displayed. external_access_integrations: The names of one or more external access integrations. Each integration you specify allows access to the external network locations and secrets the integration specifies. secrets: The key-value pairs of string types of secrets used to authenticate the external network location. The secrets can be accessed from handler code. The secrets specified as values must also be specified in the external access integration and the keys are strings used to retrieve the secrets using secret API. comment: Adds a comment for the created object. See `COMMENT `_ artifact_repository: The name of an artifact_repository that packages are found in. If unspecified, packages are pulled from Anaconda. resource_constraint: A dictionary containing a resource properties of a warehouse and then constraints needed to run this function. Eg ``{"architecture": "x86"}`` requires an x86 warehouse be used for execution. Returns: A stored procedure function that can be called with python value. Note: 1. When type hints are provided and are complete for a function, ``return_type`` and ``input_types`` are optional and will be ignored. See details of supported data types for stored procedure in :class:`~snowflake.snowpark.stored_procedure.StoredProcedureRegistration`. - You can use :attr:`~snowflake.snowpark.types.Variant` to annotate a variant, and use :attr:`~snowflake.snowpark.types.Geography` or :attr:`~snowflake.snowpark.types.Geometry` to annotate geospatial types when defining a stored procedure. - :class:`typing.Union` is not a valid type annotation for stored procedures, but :class:`typing.Optional` can be used to indicate the optional type. 2. A temporary stored procedure (when ``is_permanent`` is ``False``) is scoped to this ``session`` and all stored procedure related files will be uploaded to a temporary session stage (:func:`session.get_session_stage() `). For a permanent stored procedure, these files will be uploaded to the stage that you provide. 3. By default, stored procedure registration fails if a function with the same name is already registered. Invoking :func:`sproc` with ``replace`` set to ``True`` will overwrite the previously registered function. 4. To describe the return type for a stored procedure that `returns tabular data `_, use one of the following ways: - (Recommended) Describe the return type using :attr:`~snowflake.snowpark.types.StructType` and :attr:`~snowflake.snowpark.types.StructField`. Set ``return_type = StructType([StructField("a", DataTypeA()), ...])`` to describe the case ``RETURNS TABLE(A DataTypeA, ...)``. - Set ``return_type = StructType()`` to describe the case ``RETURNS TABLE()``. - When using type hints, the return type of function can be set as :class:`~snowflake.snowpark.dataframe.DataFrame`. This registers a table stored procedure with return type defined using ``RETURNS TABLE()``. Check **See also** below for more examples. See Also: :class:`~snowflake.snowpark.stored_procedure.StoredProcedureRegistration` Example:: >>> from snowflake.snowpark.types import IntegerType >>> @sproc(return_type=IntegerType(), input_types=[IntegerType(), IntegerType()], packages=["snowflake-snowpark-python"]) ... def add_sp(session_, x, y): ... return session_.sql(f"SELECT {x} + {y}").collect()[0][0] ... >>> add_sp(1, 1) 2 rrrurvrrwrxryrzr6r{r}rrrrrrrrrrQrT) r,rrr|rr<rsprocrXrr)rrurvrrwrxryrzr6r{r|r}rrrrrrrrQrrrRsproc_registration_methods rVrrK)s-N"6"  ((PPG$?% ( "%,MM$:$:! | #<=E  % # $   &  *     (  . "  !4 *F! "# $% &!4' (!4) * -  2)  # $   &  *     (  . "  !4 *F! "# $% &!4' (!4) * -  rY model_nameversion_or_alias_name method_namec|rtd|||g|}nd}t|}|Dcgc]}tj|}}tt ||||||Scc}w)Nmodelry)r%r.r6rr) rrrrQrJrz args_listr expressionss rV _call_modelr2*s~" j"7LtL -t4I3<=C6??3'=K=   !      >sA service_namec|rtd||g|}nd}t|}|Dcgc]}tj|}}tt |||||Scc}w)Nservicery)r%r.r6rr)rrrQrJrzrrrs rV _call_servicerN*ss "9|[.P4.PQ-t4I3<=C6??3'=K=      >sAcfdS)a Creates a model function that can be used to call a model method. Args: model_name: The name of the model to call. version_or_alias_name: The version or alias name of the model to call. Example:: >>> df = session.table("TESTSCHEMA_SNOWPARK_PYTHON.DIAMONDS_TEST") >>> model_instance = model("TESTSCHEMA_SNOWPARK_PYTHON.DIAMONDS_PRICE_PREDICTION", "v1") >>> result_df = df.select(model_instance("predict")( ... col("CUT_OE"), col("COLOR_OE"), col("CLARITY_OE"), col("CARAT"), ... col("DEPTH"), col("TABLE_PCT"), col("X"), col("Y"), col("Z") ... )["output_feature_0"]) >>> result_df.count() 5412 cfdS)Nc&tg|diSNrQ)r)rJrQrrrs rVrz)model....~*s$[);.9=.IR.rYrT)rrQrrs`rVrzmodel..~*s  rYrT)rrrQs```rVrrf*s 0 rYcfdS)a Creates a service function that can be used to call a service method. Args: service_name: The name of the service to call. Example:: >>> service_instance = service("TESTSCHEMA_SNOWPARK_PYTHON.FORECAST_MODEL_SERVICE") >>> # Prepare a DataFrame with the ten expected features >>> df = session.create_dataframe( ... [ ... (0.038076, 0.050680, 0.061696, 0.021872, -0.044223, -0.034821, -0.043401, -0.002592, 0.019907, -0.017646), ... ], ... schema=["age", "sex", "bmi", "bp", "s1", "s2", "s3", "s4", "s5", "s6"], ... ) >>> # Invoke the model's predict method exposed by the service >>> result_df = df.select( ... service_instance("predict")(col("age"), col("sex"), col("bmi"), col("bp"), col("s1"), col("s2"), col("s3"), col("s4"), col("s5"), col("s6"))["output_feature_0"] ... ) >>> result_df.show() ------------------------------------------------------ |"TESTSCHEMA_SNOWPARK_PYTHON.FORECAST_MODEL_SERV... | ------------------------------------------------------ |220.2223358154297 | ------------------------------------------------------ cfdS)Nc$tg|diSr)r)rJrQrrs rVrz+service....*s!]k.$(.4=.rYrT)rrQrs`rVrzservice..*s  rYrT)rrQs``rVrr*sB rYcv|rtd|||gn|gnd}tdt||dd}||_|S)a Converts a timestamp or a timestamp string to Unix time stamp (in seconds). Example:: >>> import datetime >>> df = session.create_dataframe([["2013-05-08T23:39:20.123-07:00"]], schema=["ts_col"]) >>> df.select(unix_timestamp(col("ts_col")).alias("unix_time")).show() --------------- |"UNIX_TIME" | --------------- |1368056360 | --------------- unix_timestampN epoch_secondFr})r%rrzrz)rrerQrnrs rVrr*sW2   QHaS    Qu= CCH JrY start_posc|rtd|||gnd}t|}t|d}td||t|||S)a Searches for the first occurrence of the first argument in the second argument. If successful, returns the position (1-based) of the first argument in the second argument. Otherwise, return 0. Note:: If the first argument is empty, this function always returns 1. Example:: >>> df = session.create_dataframe([["find a needle in a haystack"],["nothing but hay in a haystack"]], schema=["expr"]) >>> df.select(locate("needle", col("expr")).alias("1-pos")).show() ----------- |"1-pos" | ----------- |8 | |0 | ----------- locateNr:ry)r%rjr9r)r7r8rrQrn_substr_strs rVrr*sW4ENHueY&?@SW%jG % *D WdC N  rYyearsquartersmonthsweeksdayshoursminutesseconds milliseconds microsecondsminssecsc(d}| rTtj}|||||||||| | | | d jDcic] \}}||| }}}t|dfi||xs| }|xs| }t t |||||||||| | d}||_|Scc}}w)ug Creates an interval column with the specified years, quarters, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds. You can find more details in `Interval constants `_. INTERVAL is not a data type (that is, you can’t define a table column to be of data type INTERVAL). Intervals can only be used in date, time, and timestamp arithmetic. For example, ``df.select(make_interval(days=0))`` is not valid. Example:: >>> import datetime >>> from snowflake.snowpark.functions import to_date >>> >>> df = session.create_dataframe([datetime.datetime(2023, 8, 8, 1, 2, 3)], schema=["ts"]) >>> df.select(to_date(col("ts") + make_interval(days=10)).alias("next_day")).show() -------------- |"NEXT_DAY" | -------------- |2023-08-18 | -------------- You can also find some examples to use interval constants with :meth:`~snowflake.snowpark.Window.range_between` method. N) rrrrrrrrrrrVrrr Fr})rorprr r6rrz)rrrrrrrrrrrVrrrQrnrrrRrYs rVr r +sV Cjjl $ "" , ,*eg! 1}! qD  & sO>v>oGoG              C"CH JY sBz1.38.0zType YearMonthIntervalType is currently in private preview and needs to be enabled by setting parameter `FEATURE_INTERVAL_TYPES` to `ENABLED`)versionextra_doc_string_alias_column_namec d}|rJg}|j||n td|j||n tdtd|}| tdn t|d}| tdn t|d}|tdz|z}t t t t |tdz dd} t t t t |tdzdd} t|tdktdtd} t| | td| } t | d } |r)d }d ||d ||d }| j|} || _ | S)a Creates a year-month interval expression using with specified years and months. This YearMonthInterval is not to be confused with the interval created by make_interval. You can define a table column to be of data type YearMonthIntervalType. Args: years: The number of years, positive or negative months: The number of months, positive or negative _alias_column_name: If true, alias the column name to a cleaner value Returns: A Column representing a year-month interval Example:: >>> from snowflake.snowpark.functions import interval_year_month_from_parts >>> >>> _ = session.sql("ALTER SESSION SET FEATURE_INTERVAL_TYPES=ENABLED;").collect() >>> df = session.create_dataframe([[1, 2]], ["years", "months"]) >>> df.select(interval_year_month_from_parts(col("years"), col("months")).alias("interval")).show() -------------- |"INTERVAL" | -------------- |+1-02 | -------------- Nrinterval_year_month_from_parts rGr-r-zINTERVAL YEAR TO MONTHct|jtrt|jjS|j j SrN)r_expr1rrr'rrrMs rV get_col_namez4interval_year_month_from_parts..get_col_name+s5#**g.3::++,,+++rYzinterval_year_month_from_parts(, rP) rrjr%r9rIrrwrrCaliasrz)rrrrQrnrJ years_col months_col total_monthsnormalized_yearsnormalized_months sign_prefixinterval_stringrYr alias_names rVrrb+sP C U.ECF; f0Fc!f=!"BDI = A E#C D > A F$D E s2w&3LDs<'83r7'B!CUKUST%L(9CG(C"DeLeTs1v C BK [*:CHFWXO  8 9C , 7|I7N6OrR^_iRjQkklm ii #CH JrYzType DayTimeIntervalType is currently in private preview and needs to be enabled by setting parameter `FEATURE_INTERVAL_TYPES` to `ENABLED`.cd}|rg}|j||n td|j||n td|j||n td|j||n tdtd|}| tdn t|d}| tdn t|d} | tdn t|d} | tdn t|d} |tdz| tdzz| tdzz| z} | tdk} t | }t t |tdz d}|tdz}t t |tdz d}|tdz}t t |tdz d}|tdz}t|tdkttd t |d t |d }t|tdkttd t |d t |d }t t |d}t|tdkttd t |d t |d }t |t |d z d kD}|t |d z }t|ttd tt t|tdzdd dtd td}t||}t| tdtd}t|t |d td|td|td|}t |d}|r;d} d| |d| | d| | d| | d }!|j|!}||_ |S)a Creates a day-time interval expression using with specified days, hours, mins and seconds. This DayTime is not to be confused with the interval created by make_interval. You can define a table column to be of data type DayTimeIntervalType. Args: days: The number of days, positive or negative hours: The number of hours, positive or negative mins: The number of minutes, positive or negative secs: The number of seconds, positive or negative _alias_column_name: If true, alias the column name to a cleaner value Returns: A Column representing a day-time interval Example:: >>> from snowflake.snowpark.functions import interval_day_time_from_parts >>> >>> _ = session.sql("ALTER SESSION SET FEATURE_INTERVAL_TYPES=ENABLED;").collect() >>> df = session.create_dataframe([[1, 12, 30, 01.001001]], ['day', 'hour', 'min', 'sec']) >>> df.select(interval_day_time_from_parts(col("day"), col("hour"), col("min"), col("sec")).alias("interval")).show() -------------------------- |"INTERVAL" | -------------------------- |1 day, 12:30:01.001001 | -------------------------- Nrinterval_day_time_from_partsiQi<rGr0rdecimalgV瞯<.i@BrLr-r :zINTERVAL DAY TO SECONDct|jtrt|jjSt|jSrN)rrrrr'rMs rVrz2interval_day_time_from_parts..get_col_nameH,s3#**g.3::++,,3::&rYzinterval_day_time_from_parts(rrP) rrjr%r9rwrIrrrCrr rrz)"rrrrrrQrnrJdays_col hours_colmins_colsecs_col total_seconds is_negativeabs_total_seconds days_partremaining_after_days hours_partremaining_after_hours mins_part secs_part hours_strmins_strsecs_intsecs_str has_fractionfractional_part fraction_strsecs_formattedrinterval_valuerYrrs" rVrr+sZ C D,D#a&9 U.ECF; D,D#a&9 D,D#a&9!"@$G,AN49W$X = A E#A B ,AN49W$X ,AN49W$X 3u: CI 553r78JJXU #a&(KM*U,s5z9:EBI,s5z9e03t9<=uEJ03t9<U03r7:;UCI%B/ISWs3xj%01 ZI CGs3xi/0 YH E)$e,H3r7s3xh./ XuH y4)#<<=EL$x";;O H U?S\91=uEC   B LHl3Nk3s8SW5K Y C C C N ~7 8C ' 5\(5K4LB|\eOfNggijvwkAjBBDEQRZE[D\\]^ ii #CH JrYz1.28.0z^Please consider installing snowflake-ml-python and using `snowflake.cortex.summarize` instead.z/Use :meth:`snowflake.cortex.summarize` instead.)rextra_warning_textrc^|r td|gnd}d}t||}t||||S)z Summarizes the given English-language input text. Args: text: A string containing the English text from which a summary should be generated. Returns: A string containing a summary of the original text. snowflake_cortex_summarizeNzsnowflake.cortex.summarizeryr%r7rrrQrnr#text_cols rVrrV,sB"FO84&ATX1MdM2H -y QQrYz^Please consider installing snowflake-ml-python and using `snowflake.cortex.sentiment` instead.z/Use :meth:`snowflake.cortex.sentiment` instead.c^|r td|gnd}d}t||}t||||S)a} A string containing the text for which a sentiment score should be calculated. Args: text: A string containing the English text from which a summary should be generated. Returns: A floating-point number from -1 to 1 (inclusive) indicating the level of negative or positive sentiment in the text. Values around 0 indicate neutral sentiment. snowflake_cortex_sentimentNzsnowflake.cortex.sentimentryr r!s rVr$r$o,sB$FO84&ATX1MdM2H -y QQrYc6t|d}td||S)a Returns the inverse(arc) hyperbolic cosine of the input value. Example:: >>> df = session.create_dataframe([2.352409615], schema=["a"]) >>> df.select(acosh("a").as_("acosh")).collect() [Row(ACOSH=1.4999999998857607)] acoshr}rrs rVr&r&,rrYc6t|d}td||S)a Returns the inverse(arc) hyperbolic sine of the input value. Example:: >>> df = session.create_dataframe([2.129279455], schema=["a"]) >>> df.select(asinh(df["a"]).alias("asinh")).collect() [Row(ASINH=1.4999999999596934)] asinhr}rrs rVr(r(,rrYc6t|d}td||S)a  Returns the inverse(arc) hyperbolic tangent of the input value. Example:: >>> df = session.create_dataframe([0.9051482536], schema=["a"]) >>> df.select(atanh(df["a"]).alias("result")).collect() [Row(RESULT=1.4999999997517164)] atanhr}rrs rVr*r*,rrYc6t|d}td||S)u Returns the length of a string or binary value in bits. Example:: >>> df = session.create_dataframe([['abc'], ['Δ']], schema=["v"]) >>> df = df.withColumn("b", lit("A1B2").cast("binary")) >>> df.select(bit_length(col("v")).alias("BIT_LENGTH_V"), bit_length(col("b")).alias("BIT_LENGTH_B")).collect() [Row(BIT_LENGTH_V=24, BIT_LENGTH_B=16), Row(BIT_LENGTH_V=16, BIT_LENGTH_B=16)] bit_lengthr}rrs rVr,r,,s q,'A ,Y ??rY numeric_exprc6t|d}td||S)a Returns the position of the first set bit (i.e., the first '1' bit) in the binary representation of the input number. Example:: >>> df = session.create_dataframe([1, 2, 3, 32768, 32769], schema=["a"]) >>> df.select(bitmap_bit_position("a").alias("bit_position")).collect() [Row(BIT_POSITION=0), Row(BIT_POSITION=1), Row(BIT_POSITION=2), Row(BIT_POSITION=32767), Row(BIT_POSITION=0)] bitmap_bit_positionr}r)r-rQrs rVr/r/,s! |%:;A /i HHrYc6t|d}td||S)a Returns the bucket number of the input value in a bitmap index. The bucket number is a value between 1 and the number of buckets in the bitmap index. Example:: >>> df = session.create_dataframe([1, 2, 3, 32768, 32769], schema=["a"]) >>> df.select(bitmap_bucket_number(col("a")).alias("bucket_number")).collect() [Row(BUCKET_NUMBER=1), Row(BUCKET_NUMBER=1), Row(BUCKET_NUMBER=1), Row(BUCKET_NUMBER=1), Row(BUCKET_NUMBER=2)] bitmap_bucket_numberr}rrs rVr1r1,s! q01A 0!y IIrYrelative_positionc6t|d}td||S)aF Returns a bitmap constructed from the relative positions of the input values. Example:: >>> df = session.create_dataframe([1, 32769], schema=["a"]) >>> df.select(bitmap_bucket_number(df["a"]).alias("bitmap_id"),bitmap_bit_position(df["a"]).alias("bit_position")).group_by("bitmap_id").agg(bitmap_construct_agg(col("bit_position")).alias("bitmap")).order_by("bitmap_id").collect() [Row(BITMAP_ID=1, BITMAP=bytearray(b'\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00')), Row(BITMAP_ID=2, BITMAP=bytearray(b'\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00'))] bitmap_construct_aggr}r)r2rQrs rVr4r4,s" (*@AA 0!y IIrYc6t|d}td||S)a8 Returns the cube root of value in a column. Example:: >>> df = session.create_dataframe([0, 2, -10, None], schema=["x"]) >>> df.select(cbrt("x").alias("cbrt_x")).collect() [Row(CBRT_X=0.0), Row(CBRT_X=1.2599210498948734), Row(CBRT_X=-2.1544346900318834), Row(CBRT_X=None)] cbrtr}rrs rVr6r6,rrYe1e2cPt|d}t|d}td|||S)a2 Compares whether two expressions are equal. The function is NULL-safe, meaning it treats NULLs as known values for comparing equality. Note that this is different from the EQUAL comparison operator (=), which treats NULLs as unknown values. Example:: >>> df = session.create_dataframe([[1, 1], [1, None], [None, 2], [None, None]], schema=["a", "b"]) >>> df.select(equal_null(df["a"], df["b"]).alias("equal_null")).collect() [Row(EQUAL_NULL=True), Row(EQUAL_NULL=False), Row(EQUAL_NULL=False), Row(EQUAL_NULL=True)] equal_nullr}rr7r8rQrrs rVr:r:-s- L )B L )B ,B) DDrYcPt|d}t|d}td|||S)ab If expr1 is NULL, returns expr2, otherwise returns expr1. Example:: >>> df = session.create_dataframe([("a", "b"), ("c", None), (None, "d"), (None, None)], schema=["e1", "e2"]) >>> df.select(ifnull(df["e1"], df["e2"]).alias("result")).collect() [Row(RESULT='a'), Row(RESULT='c'), Row(RESULT='d'), Row(RESULT=None)] ifnullr}rr;s rVr=r=-s- H %B H %B (Bi @@rYfract_sec_precisioncX|r td|gnd}tdt|d||S)a Returns the current timestamp at the start of the query with the specified fractional second precision. Example:: >>> df = session.create_dataframe([1], schema=["a"]) >>> df.select(localtimestamp(3)).collect() # doctest: +SKIP localtimestampNFr}ry)r%rrj)r>rQrns rVr@r@+-sC  ,/B.CD   51   rY col_to_returncol_containing_maximum"maximum_number_of_values_to_returnc t|d}t|d}|/|rtd|||gnd}td||t|d||Std|||S)a| Finds the row(s) containing the maximum value for a column and returns the value of another column in that row. Example:: >>> df = session.create_dataframe([ ... [1001, 10, 10000], ... [1020, 10, 9000], ... [1030, 10, 8000], ... [900, 20, 15000], ... [2000, 20, None], ... [2010, 20, 15000], ... [2020, 20, 8000] ... ], schema=["employee_id", "department_id", "salary"]) >>> df.select(max_by("employee_id", "salary", 3)).collect() [Row(MAX_BY("EMPLOYEE_ID", "SALARY", 3)='[\n 2010,\n 900,\n 1001\n]')] max_byNFr}ryr )rArBrCrQrrrns rVrErEB-s0  x 0B . 9B)5 2r3U*V W     2e D   hB)DDrYcol_containing_minimumc t|d}t|d}|/|rtd|||gnd}td||t|d||Std|||S)ar Finds the row(s) containing the minimum value for a column and returns the value of another column in that row. Example:: >>> df = session.create_dataframe([ ... [1001, 10, 10000], ... [1020, 10, 9000], ... [1030, 10, 8000], ... [900, 20, 15000], ... [2000, 20, None], ... [2010, 20, 15000], ... [2020, 20, 8000] ... ], schema=["employee_id", "department_id", "salary"]) >>> df.select(min_by("employee_id", "salary", 3).alias("min_by")).collect() [Row(MIN_BY='[\n 2020,\n 1030,\n 1020\n]')] min_byNFr}ryr )rArFrCrQrrrns rVrHrHn-s2  x 0B . 9B)5 2r3U*V W     2e D   hB)DDrYc6t|d}td||S)u Returns the length of a string or binary value in bytes. This will be the same as LENGTH for ASCII strings and greater than LENGTH for strings using Unicode code points. For binary, this is always the same as LENGTH. Example:: >>> df = session.create_dataframe(['abc', 'Β', "X'A1B2'"], schema=["a"]) >>> df.select(octet_length(col("a")).alias("octet_length")).collect() [Row(OCTET_LENGTH=3), Row(OCTET_LENGTH=2), Row(OCTET_LENGTH=7)] octet_lengthr}rrs rVrJrJ-s q.)A .!y AArYc |rtd|||gnd}t|d}t|d}td||t|d||S)a Searches for the first occurrence of the first argument in the second argument and, if successful, returns the position (1-based) of the first argument in the second argument. Example:: >>> df = session.create_dataframe([['an', 'banana'], ['nan', 'banana']], schema=["expr1", "expr2"]) >>> df.select(position(df["expr1"], df["expr2"], 3).alias("position")).collect() [Row(POSITION=4), Row(POSITION=3)] rNFr}ryrd)r7r8rrQrnrrs rVrr-sb&  Jy(AB  z *B z *B    I'   rYcPt|d}t|d}td|||S)a Returns the average of the independent variable for non-null pairs in a group, where x is the independent variable and y is the dependent variable. Example:: >>> df = session.create_dataframe([[10, 11], [20, 22], [25, None], [30, 35]], schema=["v", "v2"]) >>> df.groupBy("v").agg(regr_avgx(df["v"], df["v2"]).alias("regr_avgx")).sort("v").collect() [Row(V=10, REGR_AVGX=11.0), Row(V=20, REGR_AVGX=22.0), Row(V=25, REGR_AVGX=None), Row(V=30, REGR_AVGX=35.0)] regr_avgxr}rrrrQrrs rVrMrM-s- ; 'B ; 'B +r2 CCrYcPt|d}t|d}td|||S)a Returns the average of the dependent variable for non-null pairs in a group, where x is the independent variable and y is the dependent variable. Example:: >>> df = session.create_dataframe([[10, 11], [20, 22], [25, None], [30, 35]], schema=["v", "v2"]) >>> df = df.group_by("v").agg(regr_avgy(df["v"], df["v2"]).alias("regr_avgy")).sort("v") >>> df.collect() [Row(V=10, REGR_AVGY=10.0), Row(V=20, REGR_AVGY=20.0), Row(V=25, REGR_AVGY=None), Row(V=30, REGR_AVGY=30.0)] regr_avgyr}rrrrQs rVrPrP-s- q+&Aq+&A +q!y AArYcPt|d}t|d}td|||S)ao Returns the number of non-null number pairs in a group. Example:: >>> df = session.create_dataframe([[1, 10, 11], [1, 20, 22], [1, 25, None], [2, 30, 35]], schema=["k", "v", "v2"]) >>> df.group_by("k").agg(regr_count(col("v"), col("v2")).alias("regr_count")).sort("k").collect() [Row(K=1, REGR_COUNT=2), Row(K=2, REGR_COUNT=1)] regr_countr}rrNs rVrSrS-s- < (B < (B ,B) DDrYcPt|d}t|d}td|||S)a Returns the intercept of the univariate linear regression line for non-null pairs in a group. It is computed for non-null pairs using the following formula: AVG(y)-REGR_SLOPE(y,x)*AVG(x), where x is the independent variable and y is the dependent variable. Example:: >>> df = session.create_dataframe([[10, 11], [20, 22], [30, 35]], schema=["v", "v2"]) >>> df.groupBy().agg(regr_intercept(df["v"], df["v2"]).alias("regr_intercept")).collect() [Row(REGR_INTERCEPT=1.1547344110854496)] regr_interceptr}rrNs rVrUrU.s0 + ,B + ,B *Bi HHrYcPt|d}t|d}td|||S)a Returns the coefficient of determination for non-null pairs in a group. It is computed for non-null pairs using the following formula: NULL if VAR_POP(x) = 0, else 1 if VAR_POP(y) = 0 and VAR_POP(x) <> 0, else POWER(CORR(y,x), 2). Where x is the independent variable and y is the dependent variable. Example:: >>> df = session.create_dataframe([[10, 11], [20, 22], [25, None], [30, 35]], schema=["v", "v2"]) >>> df.groupBy("v").agg(regr_r2(col("v"), col("v2")).alias("regr_r2")).collect() [Row(V=10, REGR_R2=None), Row(V=20, REGR_R2=None), Row(V=25, REGR_R2=None), Row(V=30, REGR_R2=None)] regr_r2r}rrQs rVrWrW.s- q)$Aq)$A )QY ??rYcPt|d}t|d}td|||S)af Returns the slope of the linear regression line for non-null pairs in a group. It is computed for non-null pairs using the following formula: COVAR_POP(x,y) / VAR_POP(x), where x is the independent variable and y is the dependent variable. Example:: >>> df = session.create_dataframe([[10, 11], [20, 22], [25, None], [30, 35]], schema=["v", "v2"]) >>> df = df.group_by("v").agg(regr_slope(df["v2"], df["v"]).alias("regr_slope")) >>> df.collect() [Row(V=10, REGR_SLOPE=None), Row(V=20, REGR_SLOPE=None), Row(V=25, REGR_SLOPE=None), Row(V=30, REGR_SLOPE=None)] regr_sloper}rrNs rVrYrY&.s- < (B < (B ,B) DDrYcPt|d}t|d}td|||S)a Returns REGR_COUNT(y, x) * VAR_POP(x) for non-null pairs. Example:: >>> df = session.create_dataframe([[10, 11], [20, 22], [25, None], [30, 35]], schema=["v", "v2"]) >>> df.group_by("v").agg(regr_sxx(col("v"), col("v2")).alias("regr_sxx")).sort("v").collect() [Row(V=10, REGR_SXX=0.0), Row(V=20, REGR_SXX=0.0), Row(V=25, REGR_SXX=None), Row(V=30, REGR_SXX=0.0)] regr_sxxr}rrs rVr[r[9.s- 1j )E 1j )E *eUi HHrYcPt|d}t|d}td|||S)a Returns REGR_COUNT(expr1, expr2) * COVAR_POP(expr1, expr2) for non-null pairs. Example:: >>> df = session.create_dataframe([[10, 11], [20, 22], [25, None], [30, 35]], schema=["v", "v2"]) >>> df = df.filter(df["v2"].is_not_null()) >>> df.group_by("v").agg(regr_sxy(df["v"], df["v2"]).alias("regr_sxy")).collect() [Row(V=10, REGR_SXY=0.0), Row(V=20, REGR_SXY=0.0), Row(V=30, REGR_SXY=0.0)] regr_sxyr}rrs rVr]r]I.s- 1j )E 1j )E *eUi HHrYcPt|d}t|d}td|||S)a Returns REGR_COUNT(y, x) * VAR_POP(y) for non-null pairs. Example:: >>> df = session.create_dataframe([[10, 11], [20, 22], [25, None], [30, 35]], schema=["v", "v2"]) >>> df.groupBy("v").agg(regr_syy(df["v"], df["v2"]).alias("regr_syy")).collect() [Row(V=10, REGR_SYY=0.0), Row(V=20, REGR_SYY=0.0), Row(V=25, REGR_SYY=None), Row(V=30, REGR_SYY=0.0)] regr_syyr}rrNs rVr_r_Z.s- : &B : &B *b" BBrYcXt|d}|rtd|||Std||S)a( A special version of TO_BINARY that performs the same operation (i.e. converts an input expression to a binary value), but with error handling support (i.e. if the conversion cannot be performed, it returns a NULL value instead of raising an error). Example:: >>> df = session.create_dataframe(["01", "A B", "Hello", None], schema=["hex_encoded_string"]) >>> df.select(try_to_binary(df["hex_encoded_string"], 'HEX').alias("b")).collect() [Row(B=bytearray(b'\x01')), Row(B=None), Row(B=None), Row(B=None)] try_to_binaryr}rrxs rVraraj.s= q/*A  3)DOQ) DrYmax_line_lengthalphabetc|rtd||g|gn|gznd}t|d}|g}|r|jt||r|jt|t dg|||dS)a3 Encodes the input (string or binary) using Base64 encoding. Example: >>> df = session.create_dataframe(["Snowflake", "Data"], schema=["input"]) >>> df.select(base64_encode(col("input")).alias("encoded")).collect() [Row(ENCODED='U25vd2ZsYWtl'), Row(ENCODED='RGF0YQ==')] base64_encodeNryr%r9rrjr)rrbrcrQrn col_inputrJs rVrere.s*     (*:B K  q/2I ;D C() CM" / PD Psi PPrYc|rtd||gn||gnd}t|d}|g}|r|jt|t dg|||dS)a, Decodes a Base64-encoded string to a string. Example: >>> df = session.create_dataframe(["U25vd2ZsYWtl", "SEVMTE8="], schema=["input"]) >>> df.select(base64_decode_string(col("input")).alias("decoded")).collect() [Row(DECODED='Snowflake'), Row(DECODED='HELLO')] base64_decode_stringNryrf)rrcrQrnrgrJs rVriri.sr"   "8+;QC!X  q"89I ;D CM" 0 W4 WcY WWrYcasecp|rtd||gnd}t|d}td|t|||S)uX Encodes the input using hexadecimal (also ‘hex’ or ‘base16’) encoding. Example: >>> df = session.create_dataframe(["Snowflake", "Hello"], schema=["input"]) >>> df.select(hex_encode(col("input")).alias("hex_encoded")).collect() [Row(HEX_ENCODED='536E6F77666C616B65'), Row(HEX_ENCODED='48656C6C6F')] hex_encodeNryrd)rrjrQrnrgs rVrlrl.sB;D lQI 6Cq,/I iT  rY max_distancec|rtd|||gn|||gnd}t|d}t|d}||g}|:t|tr t |dn t|d}|j |t dg|||dS)aComputes the Levenshtein distance between two input strings. Optionally, a maximum distance can be specified. If the distance exceeds this value, the computation halts and returns the maximum distance. Example:: >>> df = session.create_dataframe( ... [["abc", "def"], ["abcdef", "abc"], ["snow", "flake"]], ... schema=["s1", "s2"] ... ) >>> df.select( ... editdistance(col("s1"), col("s2")).alias("distance"), ... editdistance(col("s1"), col("s2"), 2).alias("max_2_distance") ... ).collect() [Row(DISTANCE=3, MAX_2_DISTANCE=2), Row(DISTANCE=3, MAX_2_DISTANCE=2), Row(DISTANCE=5, MAX_2_DISTANCE=2)] editdistanceNFr}ry)r%r9rrGrjrr) r7r8rmrQrns1s2rJmax_dists rVroro.s:   $,RH2r<2H   N +B N +B 8D,,   . n=  H . O4 OcY OOrYsubstrct|d}tt|d|d}|rtd||g|_|Sd|_|S)au Locate the position of the first occurrence of substr column in the given string. Returns null if either of the arguments are null. Example:: >>> df = session.create_dataframe([["hello world"], ["world hello"]], schema=["text"]) >>> df.select(instr(col("text"), "world").alias("position")).collect() [Row(POSITION=7), Row(POSITION=1)] instrFr}N)r9rrjr%rz)rrsrQrprs rVruru/sO W %B 3v/u EC>G"7S&M:CH JNRCH JrYrrc<|rtd|||gnd}t|ttfr t |dn|}t|ttfr t |dn|}t|ttfr t |dn t |d}t d|||||S)a~ Generates a normally-distributed pseudo-random floating point number with specified mean and stddev (standard deviation). Example:: >>> df = session.create_dataframe([1,2,3], schema=["a"]) >>> df.select(normal(0, 1, "a").alias("normal")).collect() [Row(NORMAL=-1.143416214223267), Row(NORMAL=-0.78469958830255), Row(NORMAL=-0.365971322006404)] normalNFr}ryrN)rrrCrQrns rVrwrw!/s&AJ hvs(; >> df = session.create_dataframe([1,2,3], schema=["seed"]) >>> df.select(randn("seed").alias("randn")).collect() [Row(RANDN=-1.143416214223267), Row(RANDN=-0.78469958830255), Row(RANDN=-0.365971322006404)] >>> df.select(randn().alias("randn")).collect() # doctest: +SKIP randnNFr}rr)r%r?rwrjrz)r=rQrnrs rVryryA/sf  G4>> df = session.create_dataframe([['12']], schema=['xml']) >>> result = df.select(xpath('xml', '//a/text()').alias('result')).collect() >>> json.loads(result[0].RESULT) ['1', '2'] >>> # With attributes >>> df2 = session.create_dataframe([['AB']], schema=['xml']) >>> result = df2.select(xpath('xml', '//item[@id="2"]/text()').alias('result')).collect() >>> json.loads(result[0].RESULT) ['B'] xpathr%Fr}N rrr|_get_active_sessionr9_get_or_register_xpath_udfr%rjrzrWr!rQr|xml_col xpath_udfrnrs rVr{r{_/s2  ((<<>GS'*G227;I  Ggs45/I%JK  GSY% 8CCH JrYctjjj}t |d}|j d}|rt d|t|dgnd}||t|d}||_|S)a Extracts the first value from an XML column using an XPath expression as a string. Returns NULL if no matches are found. Args: col: Column containing XML data path: XPath expression string Example:: >>> df = session.create_dataframe([['12']], schema=['xml']) >>> df.select(xpath_string('xml', '//a/text()').alias('result')).collect() [Row(RESULT='1')] xpath_stringr`Fr}Nr|rs rVrr/s"  ((<<>GS.1G228>> df = session.create_dataframe([['1']], schema=['xml']) >>> df.select(xpath_boolean('xml', 'count(//a) > 0').alias('has_a')).collect() [Row(HAS_A=True)] xpath_booleanbooleanFr}Nr|rs rVrr/s"  ((<<>GS/2G229=I  Ogs457Q-RS  GSY% 8CCH JrYctjjj}t |d}|j d}|rt d|t|dgnd}||t|d}||_|S)a Extracts a numeric value from an XML column using an XPath expression. Returns NULL if no matches are found or value cannot be converted to float. Args: col: Column containing XML data path: XPath expression string Example:: >>> df = session.create_dataframe([['19.99']], schema=['xml']) >>> df.select(xpath_number('xml', '//price/text()').alias('price')).collect() [Row(PRICE=19.99)] xpath_numberrHFr}Nr|rs rVrr/s"  ((<<>GS.1G227;I  NWc$%6P,QR  GSY% 8CCH JrYctjjj}t |d}|j d}|rt d|t|dgnd}||t|d}||_|S)a Extracts an integer value from an XML column using an XPath expression. Returns NULL if no matches are found or value cannot be converted to integer. Floats are truncated to integers (e.g., 1.9 becomes 1). Args: col: Column containing XML data path: XPath expression string Example:: >>> df = session.create_dataframe([['42']], schema=['xml']) >>> df.select(xpath_int('xml', '//count/text()').alias('count')).collect() [Row(COUNT=42)] xpath_intrGFr}Nr|rs rVrr/s$  ((<<>GS+.G2259I  K'3tu3M)NO  GSY% 8CCH JrY stage_namerelative_file_pathc td|||S)aT Generates a Snowflake file URL to a staged file using the stage name and relative file path as inputs. A file URL permits prolonged access to a specified file. That is, the file URL does not expire. The file URL is in the following format: ``https:///api/files////`` See more details `here `_. Args: stage_name: Name of the internal or external stage where the file is stored. If the stage name includes spaces or special characters, it must be enclosed in single quotes (e.g. '@"my stage"' for a stage named "my stage"). It has to be a constant instead of a column expression. relative_file_path: Path and filename of the file relative to its location in the stage. It has to be a constant instead of a column expression. Example:: >>> df.select(build_stage_file_url("@images_stage", "/us/yosemite/half_dome.jpg").alias("url")).collect() # doctest: +SKIP build_stage_file_urlr}r~)rrrQs rVrr0s0  ,>) rYstage_file_uricZ|r td|gnd}t|d}td|||S)a Converts a stage file URI to a FILE value or NULL (if input is NULL), with the `metadata `_ related to the file. Args: stage_file_uri: The stage file URI to convert to a FILE value, e.g., ``@mystage/myfile.txt``. It has to be a constant instead of a column expression. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(to_file("@mystage/testCSV.csv").alias("file")) >>> result = json.loads(df.collect()[0][0]) >>> result["RELATIVE_PATH"] 'testCSV.csv' >>> result["CONTENT_TYPE"] 'text/csv' to_fileNryr )rrQrnrs rVrr 0s62?H i.)9 :TC~y1A )QSI FFrYc:d}t||}t|||S)a Returns the content type (also known as mime type) of a FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_content_type(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] 'text/csv' fl_get_content_typer}rrrQrrgs rVrr>0s$ *Mq-0I -i HHrYc:d}t||}t|||S)a Returns the hash content (ETAG) of a FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_etag(to_file("@mystage/testCSV.csv")).alias("file")) >>> len(df.collect()[0][0]) # doctest: +SKIP fl_get_etagr}rrs rVrrS0s$"Mq-0I -i HHrYc:d}t||}t|||S)a Returns the file type (modality) of a FILE. One of following values are returned: - document - video - audio - image - compressed - unknown Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_file_type(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] 'document' fl_get_file_typer}rrs rVrrg0s$8'Mq-0I -i HHrYc:d}t||}t|||S)a Returns the last modified date of a FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_last_modified(to_file("@mystage/testCSV.csv")).alias("file")) >>> type(df.collect()[0][0]) fl_get_last_modifiedr}rrs rVrr0$ +Mq-0I -i HHrYc:d}t||}t|||S)a Returns the relative path of a FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_relative_path(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] 'testCSV.csv' fl_get_relative_pathr}rrs rVrr0rrYc:d}t||}t|||S)a Returns the scoped URL of a FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_scoped_file_url(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] fl_get_scoped_file_urlr}rrs rVrr0s$-Mq-0I -i HHrYc:d}t||}t|||S)a Returns the size, in bytes, of a FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_size(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] 32 fl_get_sizer}rrs rVrr0$ "Mq-0I -i HHrYc:d}t||}t|||S)a Returns the stage name of a FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_stage(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0].split(".")[-1] 'MYSTAGE' fl_get_stager}rrs rVrr0s$ #Mq-0I -i HHrYc:d}t||}t|||S)a Returns the stage URL of a FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_get_stage_file_url(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] # doctest: +SKIP 'https://' fl_get_stage_file_urlr}rrs rVrr0s$ ,Mq-0I -i HHrYc:d}t||}t|||S)a Checks if the input is an audio FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_is_audio(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] False fl_is_audior}rrs rVrr1rrYc:d}t||}t|||S)a Checks if the input is a video FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_is_video(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] False fl_is_videor}rrs rVrr1rrYc:d}t||}t|||S)a Checks if the input is a document FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_is_document(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] True fl_is_documentr}rrs rVrr/1s$ %Mq-0I -i HHrYc:d}t||}t|||S)a Checks if the input is a compressed FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_is_compressed(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] False fl_is_compressedr}rrs rVrrD1s$ 'Mq-0I -i HHrYc:d}t||}t|||S)a Checks if the input is an image FILE. Example:: >>> import json >>> # Create a temp stage. >>> _ = session.sql("create or replace temp stage mystage").collect() >>> # Upload a file to a stage. >>> r = session.file.put("tests/resources/testCSV.csv", "@mystage", auto_compress=False, overwrite=True) >>> df = session.range(1).select(fl_is_image(to_file("@mystage/testCSV.csv")).alias("file")) >>> df.collect()[0][0] False fl_is_imager}rrs rVrrY1rrYtemplate_stringexprscd}|rt||g|Dcgc]}|c}znd}|Dcgc]}t||}}t|t|g|||dScc}wcc}w)a Constructs a structured OBJECT containing a template string and a list of arguments. This object is useful for dynamically formatting messages, constructing structured prompts, or storing formatted data for further processing, such as by Cortex AI functions. Args: template_string: A string containing numbered placeholders like {0} where the number is at least 0 and less than the number of expressions specified. The first expression is substituted for {0}, the second for {1}, and so on. *exprs: Expressions whose values will eventually be substituted into the template string in place of the numbered placeholders. These can be column names or other expressions. Values can be of any type coercible to a string (for example, VARCHAR, NUMBER, etc.), or FILE. Returns: A SQL OBJECT with the following structure: ``{ 'template': '', 'args': ARRAY(, , ...) }`` The args array contains the value of the expressions specified in the PROMPT function call. Note: - This function does not perform any string formatting itself. It is intended to construct an object to be consumed by Cortex AI functions. - It is an error to use a placeholder in the template string that does not have a corresponding expression, but it is not an error to have expressions that are not used in the template string. Examples:: >>> df = session.create_dataframe([["Alice", "Monday"], ["Bob", "Tuesday"]], schema=["name", "day"]) >>> df.select(prompt("Hello, {0}. Today is {1}", col("name"), col("day")).alias("greeting")).show() -------------------------------------------- |"GREETING" | -------------------------------------------- |{ | | "args": [ | | "Alice", | | "Monday" | | ], | | "template": "Hello, {0}. Today is {1}" | |} | |{ | | "args": [ | | "Bob", | | "Tuesday" | | ], | | "template": "Hello, {0}. Today is {1}" | |} | -------------------------------------------- promptNryrd)rrQrrrrns rVrrn1srM  MO+C CT^D- 0 CE C s?+ .3 :=  @X Ds A Aresponse_formatcd}t|tr t|}n|}tt j |j dd}|rt|||gnd}t|||||S)a Extracts information from an input string or file based on the specified response format. Args: input: Either: - A string or Column containing text to extract information from - A FILE type Column representing a document to extract from response_format: Information to be extracted in one of the following formats: - Simple object schema (dict) mapping feature names to extraction prompts: ``{'name': 'What is the last name of the employee?', 'address': 'What is the address of the employee?'}`` - Array of strings containing the information to be extracted: ``['What is the last name of the employee?', 'What is the address of the employee?']`` - Array of arrays containing two strings (feature name and extraction prompt): ``[['name', 'What is the last name of the employee?'], ['address', 'What is the address of the employee?']]`` - Array of strings with colon-separated feature names and extraction prompts: ``['name: What is the last name of the employee?', 'address: What is the address of the employee?']`` Returns: A Column containing a JSON object with the extracted information. Note: - You can either ask questions in natural language or describe information to be extracted (e.g., 'City, street, ZIP' instead of 'What is the address?') - To extract a list, add 'List:' at the beginning of each question - Maximum of 100 features can be extracted - Documents must be no more than 125 pages long - Maximum output length is 512 tokens per question Supported file formats: PDF, PNG, PPTX, EML, DOC, DOCX, JPEG, JPG, HTM, HTML, TEXT, TXT, TIF, TIFF Files must be less than 100 MB in size. Examples:: >>> # Extract from text string >>> df = session.range(1).select( ... ai_extract( ... 'John Smith lives in San Francisco and works for Snowflake', ... {'name': 'What is the first name of the employee?', 'city': 'What is the address of the employee?'} ... ).alias("extracted") ... ) >>> df.show() -------------------------------- |"EXTRACTED" | -------------------------------- |{ | | "error": null, | | "response": { | | "city": "San Francisco", | | "name": "John" | | } | |} | -------------------------------- >>> # Extract using array format >>> df = session.create_dataframe( ... ["Alice Johnson works in Seattle", "Bob Williams works in Portland"], ... schema=["text"] ... ) >>> extracted_df = df.select( ... col("text"), ... ai_extract(col("text"), [['name', 'What is the first name?'], ['city', 'What city do they work in?']]).alias("info") ... ) >>> extracted_df.show() ------------------------------------------------------------ |"TEXT" |"INFO" | ------------------------------------------------------------ |Alice Johnson works in Seattle |{ | | | "error": null, | | | "response": { | | | "city": "Seattle", | | | "name": "Alice" | | | } | | |} | |Bob Williams works in Portland |{ | | | "error": null, | | | "response": { | | | "city": "Portland", | | | "name": "Bob" | | | } | | |} | ------------------------------------------------------------ >>> # Extract lists using List: prefix >>> df = session.range(1).select( ... ai_extract( ... 'Python, Java, and JavaScript are popular programming languages', ... [['languages', 'List: What programming languages are mentioned?']] ... ).alias("extracted") ... ) >>> df.show() ---------------------- |"EXTRACTED" | ---------------------- |{ | | "error": null, | | "response": { | | "languages": [ | | "Python", | | "Java", | | "JavaScript" | | ] | | } | |} | ---------------------- >>> # Extract from file >>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect() >>> _ = session.file.put("tests/resources/invoice.pdf", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_extract( ... to_file('@mystage/invoice.pdf'), ... [['date', 'What is the date of the invoice?'], ['amount', 'What is the amount of the invoice?']] ... ).alias("extracted") ... ) >>> df.show() -------------------------------- |"EXTRACTED" | -------------------------------- |{ | | "error": null, | | "response": { | | "amount": "USD $950.00", | | "date": "Nov 26, 2016" | | } | |} | -------------------------------- ai_extractr'Nry) rrrjrmjsondumpsr6r%r)r)rrQr# input_colresponse_format_colrns rVrr1sX!M%J  #4::o#>#F#FsC#PQ  ME?+CD     rY predicatefilecd}t||}| |r t||gnd}t||||S|rt|||gnd}t|||||S)a Classifies free-form prompt inputs into a boolean. Currently supports both text and image filtering. Args: predicate: If you're specifying an input string, it is string containing the text to be classified; If you're filtering on one file, it is a string containing the instructions to classify the file input as either TRUE or FALSE. file: The FILE type column that the file is classified by based on the instructions specified in ``predicate``. You can use IMAGE FILE as an input to the AI_FILTER function. Note: For more complicated prompts, especially with multiple file columns, you can use the :func:`prompt()` function to help with creating an input, which supports formatting across both strings and FILE datatypes. Examples:: >>> # for text >>> session.range(1).select(ai_filter('Is Canada in North America?').alias("answer")).show() ------------ |"ANSWER" | ------------ |True | ------------ >>> # use prompt function >>> df = session.create_dataframe(["Switzerland", "Korea"], schema=["country"]) >>> df.select( ... ai_filter(prompt("Is {0} in Asia?", col("country"))).as_("asia"), ... ai_filter(prompt("Is {0} in Europe?", col("country"))).as_("europe"), ... ai_filter(prompt("Is {0} in North America?", col("country"))).as_("north_america"), ... ai_filter(prompt("Is {0} in Central America?", col("country"))).as_("central_america"), ... ).show() ----------------------------------------------------------- |"ASIA" |"EUROPE" |"NORTH_AMERICA" |"CENTRAL_AMERICA" | ----------------------------------------------------------- |False |True |False |False | |True |False |False |False | ----------------------------------------------------------- >>> # for image >>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect() >>> _ = session.file.put("tests/resources/dog.jpg", "@mystage", auto_compress=False) >>> df = session.range(1).select(ai_filter("is it a dog picture?", to_file("@mystage/dog.jpg")).alias("is_dog")) >>> df.show() ------------ |"IS_DOG" | ------------ |True | ------------ ai_filterNry)r7r%r)rrrQr# predicate_colrns rVrr\2s}r M"9m>> # for text >>> session.range(1).select(ai_classify('One day I will see the world', ['travel', 'cooking']).alias("answer")).show() ----------------- |"ANSWER" | ----------------- |{ | | "labels": [ | | "travel" | | ] | |} | ----------------- >>> df = session.create_dataframe([ ... ['France', ['North America', 'Europe', 'Asia']], ... ['Singapore', ['North America', 'Europe', 'Asia']], ... ['one day I will see the world', ['travel', 'cooking', 'dancing']], ... ['my lobster bisque is second to none', ['travel', 'cooking', 'dancing']] ... ], schema=["data", "category"]) >>> df.select("data", ai_classify(col("data"), col("category"))["labels"][0].alias("class")).sort("data").show() --------------------------------------------------- |"DATA" |"CLASS" | --------------------------------------------------- |France |"Europe" | |Singapore |"Asia" | |my lobster bisque is second to none |"cooking" | |one day I will see the world |"travel" | --------------------------------------------------- >>> # using kwargs for advanced configuration >>> session.range(1).select( ... ai_classify( ... 'One day I will see the world and learn to cook my favorite dishes', ... ['travel', 'cooking', 'reading', 'driving'], ... task_description='Determine topics related to the given text', ... output_mode='multi', ... examples=[{ ... 'input': 'i love traveling with a good book', ... 'labels': ['travel', 'reading'], ... 'explanation': 'the text mentions traveling and a good book which relates to reading' ... }] ... ).alias("answer") ... ).show() ------------------ |"ANSWER" | ------------------ |{ | | "labels": [ | | "cooking", | | "travel" | | ] | |} | ------------------ >>> # for image >>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect() >>> _ = session.file.put("tests/resources/dog.jpg", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_classify( ... prompt("Please help me classify the dog within this image {0}", to_file("@mystage/dog.jpg")), ... ["French Bulldog", "Golden Retriever", "Bichon", "Cavapoo", "Beagle"] ... ).alias("classes") ... ) >>> df.show() ----------------- |"CLASSES" | ----------------- |{ | | "labels": [ | | "Cavapoo" | | ] | |} | ----------------- ai_classifyNc3<K|]}t|tywrNrrrOrs rVrPzai_classify.. 3s4 1c4FrhrQz:list_of_categories must be a list of str or a Column, got rrry)dictr%r7rrallrjr=rAr6 TypeErrorrmrrr6r) rrrQrRr# config_dictrnrcat_col config_cols rVrr2sd"Mv,K  MD2Dk+RS  dM2H$d+4$641 :<)@E  & /$HI[H\ ]  djj5==c3GH  8Wjsi   8W3)  rYc^d}|r t||gnd}t||}t||||S)a Summarizes a column of text data. Args: expr: This is an expression that contains text for summarization, such as restaurant reviews or phone transcripts. Example:: >>> df = session.create_dataframe([ ... [1, "Excellent"], ... [1, "Excellent"], ... [1, "Great"], ... [1, "Mediocre"], ... [2, "Terrible"], ... [2, "Bad"], ... ], schema=["product_id", "review"]) >>> summary_df = df.select(ai_summarize_agg(col("review"))) >>> summary_df.count() 1 >>> summary_df = df.group_by("product_id").agg(ai_summarize_agg(col("review"))) >>> summary_df.count() 2 ai_summarize_aggNryr )rrQr#rnrs rVrr83s92'M8A mdV 4tCdM2H -y QQrYtask_descriptionczd}|rt|||gnd}t||}t||}t|||||S)a Aggregates a column of text data using a natural language task description. This function reduces a column of text by performing a natural language aggregation as described in the task description. For instance, it can summarize large datasets or extract specific insights. Args: expr: A column or literal string containing the text data on which the aggregation operation is to be performed. task_description: A plain English string that describes the aggregation task, such as "Summarize the product reviews for a blog post targeting consumers" or "Identify the most positive review and translate it into French and Polish, one word only". Example:: >>> df = session.create_dataframe([ ... [1, "Excellent"], ... [1, "Excellent"], ... [1, "Great"], ... [1, "Mediocre"], ... [2, "Terrible"], ... [2, "Bad"], ... ], schema=["product_id", "review"]) >>> summary_df = df.select(ai_agg(col("review"), "Summarize the product reviews for a blog post targeting consumers")) >>> summary_df.count() 1 >>> summary_df = df.group_by("product_id").agg(ai_agg(col("review"), "Summarize the product reviews for a blog post targeting consumers")) >>> summary_df.count() 2 Note: For optimal performance, follow these guidelines: - Use plain English text for the task description. - Describe the text provided in the task description. For example, instead of a task description like "summarize", use "Summarize the phone call transcripts". - Describe the intended use case. For example, instead of "find the best review", use "Find the most positive and well-written restaurant review to highlight on the restaurant website". - Consider breaking the task description into multiple steps. For example, instead of "Summarize the new articles", use "You will be provided with news articles from various publishers presenting events from different points of view. Please create a concise and elaborative summary of source texts without missing any crucial information.". ai_aggNryr )rrrQr#rnrtask_description_cols rVrrW3s^`M  MD2B+CD  dM2H)*:MJ x!5C9 rYinput1input2c d}t|}|rt||||gnd}t||}t||}|r?tt j |j dd} t|||| ||St|||||S)u Computes a similarity score based on the vector cosine similarity value of the inputs' embedding vectors. Currently supports both text and image similarity computation. Args: input1: The first input for comparison. Can be a string with text or an image (FILE data type). input2: The second input for comparison. Can be a string with text or an image (FILE data type). Must be the same type as input1 (both text or both images). **kwargs: Configuration settings specified as key/value pairs. Supported keys: - model: The embedding model used for embedding. For STRING input, defaults to 'snowflake-arctic-embed-l-v2'. For IMAGE input, defaults to 'voyage-multimodal-3'. Supported values include: 'snowflake-arctic-embed-l-v2', 'nv-embed-qa-4', 'multilingual-e5-large', 'voyage-multilingual-2', 'snowflake-arctic-embed-m-v1.5', 'snowflake-arctic-embed-m', 'e5-base-v2', 'voyage-multimodal-3' (for images). Returns: A float value of range -1 to 1 that represents the similarity score computed using vector similarity between two embedding vectors for the inputs. Note: AI_SIMILARITY does not support computing the similarity between text and image inputs. Both inputs must be of the same type: - They are both Python ``str``. - They are both :class:`Column` objects representing a FILE data type. Examples:: >>> # Text similarity >>> df = session.range(1).select(ai_similarity('I like this dish', 'This dish is very good').alias("similarity")) >>> df.collect()[0][0] > 0.8 True >>> # Text similarity with custom model >>> df = session.range(1).select( ... ai_similarity( ... 'I love programming', ... '我喜欢编程', ... model='multilingual-e5-large' ... ).alias("similarity") ... ) >>> df.collect()[0][0] > 0.8 True >>> # Using columns >>> df = session.create_dataframe([ ... ['Hello world', 'Hi there'], ... ['Good morning', 'Good evening'], ... ], schema=["text1", "text2"]) >>> df = df.select(ai_similarity(col("text1"), col("text2")).alias("similarity")) >>> result = df.collect() >>> result[0][0] < 0.6 True >>> result[1][0] > 0.7 True >>> # Image similarity >>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect() >>> _ = session.file.put("tests/resources/dog.jpg", "@mystage", auto_compress=False) >>> _ = session.file.put("tests/resources/cat.jpeg", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_similarity( ... to_file("@mystage/dog.jpg"), ... to_file("@mystage/cat.jpeg") ... ).alias("similarity") ... ) >>> df.collect()[0][0] < 0.5 True ai_similarityNrrry)rr%r7rmrrr6r) rrrQrRr#rrn input1_col input2_colrs rVrr3sX$Mv,K  MFFK+HI    6J 6Jdjj5==c3GH         :zy  rYc d}t|}|rP|rt|||gnd}ttj|j dd}t |||||S|r t||gnd}t ||||S)a Returns the extracted content from a document as a JSON-formatted string. This function supports two types of extraction: Optical Character Recognition (OCR), and layout. Args: file: A FILE type column containing the document to parse. The document must be on a Snowflake stage that uses server-side encryption and is accessible to the user. **kwargs: Configuration settings specified as key/value pairs. Supported keys: - mode: Specifies the parsing mode. Supported modes are: - 'OCR': The function extracts text only. This is the default mode. - 'LAYOUT': The function extracts layout as well as text, including structural content such as tables. - page_split: If set to True, the function splits the document into pages and processes each page separately. This feature supports only PDF, PowerPoint (.pptx), and Word (.docx) documents. Documents in other formats return an error. The default is False. Tip: To process long documents that exceed the token limit, set this option to True. Returns: A JSON object (as a string) that contains the extracted data and associated metadata. The options argument determines the structure of the returned object. If ``page_split`` is set, the output contains: - pages: An array of JSON objects, each containing text extracted from the document. - metadata: Contains metadata about the document, such as page count. - errorInformation: Contains error information if document can't be parsed (only on error). If ``page_split`` is False or not present, the output contains: - content: Plain text (in OCR mode) or Markdown-formatted text (in LAYOUT mode). - metadata: Contains metadata about the document, such as page count. - errorInformation: Contains error information if document can't be parsed (only on error). Examples:: >>> import json >>> # Parse a PDF document with default OCR mode >>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect() >>> _ = session.file.put("tests/resources/doc.pdf", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_parse_document(to_file("@mystage/doc.pdf")).alias("parsed_content") ... ) >>> result = json.loads(df.collect()[0][0]) >>> "Sample PDF" in result["content"] True >>> result["metadata"]["pageCount"] 3 >>> # Parse with LAYOUT mode to extract tables and structure >>> _ = session.file.put("tests/resources/invoice.pdf", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_parse_document( ... to_file("@mystage/invoice.pdf"), ... mode='LAYOUT' ... ).alias("parsed_content") ... ) >>> result = json.loads(df.collect()[0][0]) >>> "| Customer Name |" in result["content"] and "| Country |" in result["content"] # Markdown format True >>> # Parse with page splitting for documents >>> df = session.range(1).select( ... ai_parse_document( ... to_file("@mystage/doc.pdf"), ... page_split=True ... ).alias("parsed_content") ... ) >>> result = json.loads(df.collect()[0][0]) >>> len(result["pages"]) 3 >>> 'Sample PDF' in result["pages"][0]["content"] True >>> result["pages"][0]["index"] 0 ai_parse_documentNrrryrr%rmrrr6r)rrQrRr#rrnrs rVrr3sd(Mv,K k/B C djj5==c3GH  4#  =F!-$84mTyQQrY audio_filec d}t|}|rP|rt|||gnd}ttj|j dd}t |||||S|r t||gnd}t ||||S)a Transcribes text from an audio file with optional timestamps and speaker labels. AI_TRANSCRIBE supports numerous languages (automatically detected), and audio can contain more than one language. Timestamps and speaker labels are extracted based on the specified timestamp granularity. Args: audio_file: A FILE type column representing an audio file. The audio file must be on a Snowflake stage that uses server-side encryption and is accessible to the user. Use the to_file() function to create a reference to your staged file. **kwargs: Configuration settings specified as key/value pairs. Supported keys: - timestamp_granularity: A string specifying the desired timestamp granularity. Possible values are: - 'word': The file is transcribed as a series of words, each with its own timestamp. - 'speaker': The file is transcribed as a series of conversational "turns", each with its own timestamp and speaker label. If this field is not specified, the entire file is transcribed as a single segment without timestamps by default. Returns: A string containing a JSON representation of the transcription result. The JSON object contains the following fields: - audio_duration: The total duration of the audio file in seconds. - text: The transcription of the complete audio file (when timestamp_granularity is not specified). - segments: An array of segments (when timestamp_granularity is set to 'word' or 'speaker'). Each segment contains: - start: The start time of the segment in seconds. - end: The end time of the segment in seconds. - text: The transcription text for the segment. - speaker_label: The label of the speaker for the segment (only when timestamp_granularity is 'speaker'). Labels are of the form "SPEAKER_00", "SPEAKER_01", etc. Note: - Supports languages: Arabic, Bulgarian, Cantonese, Catalan, Chinese, Czech, Dutch, English, French, German, Greek, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Polish, Portuguese, Romanian, Russian, Serbian, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian. - Supported audio formats: FLAC, MP3, Ogg, WAV, WebM - Maximum file size: 700 MB - Maximum duration: 60 minutes with timestamps, 120 minutes without Examples:: >>> import json >>> # Basic transcription without timestamps >>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect() >>> _ = session.file.put("tests/resources/audio.ogg", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_transcribe(to_file("@mystage/audio.ogg")).alias("transcript") ... ) >>> result = json.loads(df.collect()[0][0]) >>> result['audio_duration'] > 120 # more than 2 minutes True >>> "glad to see things are going well" in result['text'].lower() True >>> # Transcription with word-level timestamps >>> df = session.range(1).select( ... ai_transcribe( ... to_file("@mystage/audio.ogg"), ... timestamp_granularity='word' ... ).alias("transcript") ... ) >>> result = json.loads(df.collect()[0][0]) >>> len(result["segments"]) > 0 True >>> result["segments"][0]["text"].lower() 'glad' >>> 'start' in result["segments"][0] and 'end' in result["segments"][0] True >>> # Transcription with speaker diarization >>> _ = session.file.put("tests/resources/conversation.ogg", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_transcribe( ... to_file("@mystage/conversation.ogg"), ... timestamp_granularity='speaker' ... ).alias("transcript") ... ) >>> result = json.loads(df.collect()[0][0]) >>> result["audio_duration"] > 100 # more than 100 seconds True >>> len(result["segments"]) > 0 True >>> result["segments"][0]["speaker_label"] 'SPEAKER_00' >>> 'jenny' in result["segments"][0]["text"].lower() True >>> 'start' in result["segments"][0] and 'end' in result["segments"][0] True ai_transcribeNrrryr)rrQrRr#rrnrs rVrra4sP$Mv,K K/H I djj5==c3GH  :zy  CL!-*>QUmZcYWWrYrrmodel_parameters show_detailscyrNrT)rrrrrrQs rV ai_completer4srYcyrNrT)rrrrrrrQs rVrr4srYcd}||g}||j|||j|||j|||j||r t||nd} t|} t||} d| i} |@t |t st |j tr | | d<|| d<ntd| | d<|3ttj|jdd } | | d <|3ttj|jdd }|| d <|tt || d <t|| | | S)a Generates a response (completion) for a text prompt using a supported language model. This function supports three main usage patterns: 1. String prompt only: AI_COMPLETE(model, prompt, ...) 2. Prompt with file: AI_COMPLETE(model, prompt, file, ...) 3. Prompt object: AI_COMPLETE(model, prompt_object, ...) Args: model: A string specifying the model to be used. Different input types have different supported models. See details in `AI_COMPLETE `_. prompt: A string prompt, or a Column object from :func:`prompt()`. file: The FILE type column representing an image. When provided, prompt should be a string. model_parameters: Optional object containing model hyperparameters: - temperature: A value from 0 to 1 controlling randomness (default: ``0``) - top_p: A value from 0 to 1 controlling diversity (default: ``0``) - max_tokens: Maximum number of output tokens (default: ``4096``, max: ``8192``) - guardrails: Enable Cortex Guard filtering (default: ``FALSE``) response_format: Optional JSON schema that the response should follow for structured outputs. show_details: Optional boolean flag to return detailed inference information (default: ``FALSE``). Returns: ``response_format`` and ``show_details`` are only supported for single string. When ``show_details`` is ``FALSE`` and ``response_format`` is not specified: Returns a string containing the response. When ``show_details`` is ``FALSE`` and ``response_format`` is specified: Returns an object following the provided format. When ``show_details`` is ``TRUE``: Returns a JSON object with detailed inference information including choices, created timestamp, model name, and token usage statistics. See details in `AI_COMPLETE Returns `_. Examples:: >>> # Basic completion with string prompt >>> df = session.range(1).select( ... ai_complete('snowflake-arctic', 'What are large language models?').alias("response") ... ) >>> len(df.collect()[0][0]) > 10 True >>> # Using model parameters >>> df = session.range(1).select( ... ai_complete( ... model='llama3.3-70b', ... prompt='How does a snowflake get its unique pattern?', ... model_parameters={ ... 'temperature': 0.7, ... 'max_tokens': 100 ... } ... ).alias("response") ... ) >>> result = df.collect()[0][0] >>> len(result) > 0 True >>> # With detailed output >>> df = session.range(1).select( ... ai_complete( ... model='mistral-large', ... prompt='Explain AI in one sentence.', ... show_details=True ... ).alias("detailed_response") ... ) >>> result = df.collect()[0][0] >>> 'choices' in result and 'usage' in result True >>> # Prompt with image processing >>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect() >>> _ = session.file.put("tests/resources/kitchen.png", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_complete( ... model='claude-4-sonnet', ... prompt='Extract the kitchen appliances identified in this image. Respond in JSON only with the identified appliances.', ... file=to_file('@mystage/kitchen.png'), ... ) ... ) >>> result = df.collect()[0][0] >>> "microwave" in result and "refrigerator" in result True >>> # Structured output with response format >>> response_schema = { ... 'type': 'json', ... 'schema': { ... 'type': 'object', ... 'properties': { ... 'sentiment': {'type': 'string'}, ... 'confidence': {'type': 'number'} ... }, ... 'required': ['sentiment', 'confidence'] ... } ... } >>> df = session.range(1).select( ... ai_complete( ... model='llama3.3-70b', ... prompt='Analyze the sentiment of this text: I love this product!', ... response_format=response_schema ... ).alias("structured_result") ... ) >>> result = df.collect()[0][0] >>> 'sentiment' in result and 'confidence' in result True >>> # Using prompt object from prompt() function >>> df = session.range(1).select( ... ai_complete( ... model='claude-3-7-sonnet', ... prompt=prompt("Extract the kitchen appliances identified in this image. Respond in JSON only with the identified appliances? {0}", to_file('@mystage/kitchen.png')), ... ) ... ) >>> result = df.collect()[0][0] >>> "microwave" in result and "refrigerator" in result True rNrrrz+prompt must be a string or a literal columnrrrrrrry)rr%rjr7rrrrrrmrrr6r)rrrrrrrQr#rJrn model_col prompt_col call_kwargsmodel_params_colrs rVrr4swz"M 6?D  D# $%" O$ L!6? mT 2TCE I 6J K   fc "j&H'1K $"&K JK K * H##DJJ/?$@$H$Hc$RS*: &'"&tzz/'B'J'J3PS'TU)< %&&.s>> # Text embedding >>> df = session.range(1).select( ... ai_embed('snowflake-arctic-embed-l-v2.0', 'Hello, world!').alias("embedding") ... ) >>> result = df.collect()[0][0] >>> len(result) > 0 True >>> # Text embedding with multilingual model >>> df = session.create_dataframe([ ... ['Hello world'], ... ['Bonjour le monde'], ... ['Hola mundo'] ... ], schema=["text"]) >>> df = df.select( ... col("text"), ... ai_embed('multilingual-e5-large', col("text")).alias("embedding") ... ) >>> embeddings = df.collect() >>> all(len(row[1]) > 0 for row in embeddings) True >>> # Image embedding >>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect() >>> _ = session.file.put("tests/resources/dog.jpg", "@mystage", auto_compress=False) >>> df = session.range(1).select( ... ai_embed('voyage-multimodal-3', to_file('@mystage/dog.jpg')).alias("image_embedding") ... ) >>> result = df.collect()[0][0] >>> len(result) > 0 True ai_embedNry)rjr7r%r)rr)rQr#rrrns rVrr5sT|ME Ium4IAJ meU^ >> # Get overall sentiment only >>> session.range(1).select( ... ai_sentiment("A tourist's delight, in low urban light, Recommended gem, a pizza night sight. Swift arrival, a pleasure so right, Yet, pockets felt lighter, a slight pricey bite. 💰🍕🚀").alias("sentiment") ... ).show() ------------------------------ |"SENTIMENT" | ------------------------------ |{ | | "categories": [ | | { | | "name": "overall", | | "sentiment": "mixed" | | } | | ] | |} | ------------------------------ >>> # Extract sentiment for specific categories >>> df = session.create_dataframe([ ... ["The movie had amazing visual effects but the plot was terrible."], ... ["The food was delicious but the service was slow."], ... ["The movie was great, but the acting was terrible."] ... ], schema=["review"]) >>> df.select("review", ai_sentiment(col("review"), ['plot', 'visual effects', 'acting']).alias("sentiment")).show() ---------------------------------------------------------------------------------------- |"REVIEW" |"SENTIMENT" | ---------------------------------------------------------------------------------------- |The movie had amazing visual effects but the pl... |{ | | | "categories": [ | | | { | | | "name": "overall", | | | "sentiment": "mixed" | | | }, | | | { | | | "name": "acting", | | | "sentiment": "neutral" | | | }, | | | { | | | "name": "plot", | | | "sentiment": "negative" | | | }, | | | { | | | "name": "visual effects", | | | "sentiment": "positive" | | | } | | | ] | | |} | |The food was delicious but the service was slow. |{ | | | "categories": [ | | | { | | | "name": "overall", | | | "sentiment": "mixed" | | | }, | | | { | | | "name": "acting", | | | "sentiment": "unknown" | | | }, | | | { | | | "name": "plot", | | | "sentiment": "unknown" | | | }, | | | { | | | "name": "visual effects", | | | "sentiment": "unknown" | | | } | | | ] | | |} | |The movie was great, but the acting was terrible. |{ | | | "categories": [ | | | { | | | "name": "overall", | | | "sentiment": "mixed" | | | }, | | | { | | | "name": "acting", | | | "sentiment": "negative" | | | }, | | | { | | | "name": "plot", | | | "sentiment": "positive" | | | }, | | | { | | | "name": "visual effects", | | | "sentiment": "positive" | | | } | | | ] | | |} | ---------------------------------------------------------------------------------------- ai_sentimentNryc3<K|]}t|tywrNrrs rVrPzai_sentiment..6s7 #$Jq# 7 rz&categories must be a list of str, got Fr) r7r%rrrrrtype__name__rjr=rA)rrrQr#r"rnrs rVrr5s@#MdM2H`_. Examples:: >>> # Translate literal text from English to German >>> df = session.range(1).select( ... ai_translate('Hello world', 'en', 'de').alias('translation') ... ) >>> df.collect()[0][0].lower() 'hallo welt' >>> # Auto-detect source language and translate to English >>> df = session.range(1).select( ... ai_translate('Hola mundo', '', 'en').alias('translation') ... ) >>> df.collect()[0][0].lower() 'hi world' ai_translateNryr ) rrrrQr#rnr"source_lang_coltarget_lang_cols rVrr6sqJ#M  MD/?+ST dM2H$_mDO$_mDO    rY)T)NT)CALLNT)r-FFr&T)rT)r)r-rr)r-T)TT)TFT)NNT)FT)rNFT)r-FTrN)rT)NNNNNNNNNNNNNT)NNTT)NNNNTT)rLT)rNT)NNNT)NNNNT(#__doc__rsystypingrrr?rtypesrrrrr r r r snowflake.snowparkr4snowflake.snowpark._internal.proto.generated.ast_pb2r _internalro generatedast_pb2snowflake.snowpark._functionsr /snowflake.snowpark._functions.general_functionsrr!snowflake.snowpark.table_function0snowflake.snowpark._internal.analyzer.expressionrrrrrrrrrr6snowflake.snowpark._internal.analyzer.unary_expressionr7snowflake.snowpark._internal.analyzer.window_expressionrrrrr&snowflake.snowpark._internal.ast.utilsr r!r"r#r$r%'snowflake.snowpark._internal.type_utilsr&r'r(r)r*r+&snowflake.snowpark._internal.udf_utilsr,"snowflake.snowpark._internal.utilsr-r.r/r0r1r2r3.snowflake.snowpark._functions.scalar_functionssnowflake.snowpark.columnr5r6r7r8r9r:#snowflake.snowpark.stored_procedurer;r<snowflake.snowpark.typesr=r>r?r@rArBrCrDsnowflake.snowpark.udafrErFsnowflake.snowpark.udfrGrHsnowflake.snowpark.udtfrIrJ version_inforMcollections.abcrboolrWrcrjrmrxr|rrrrrrrrrrrrGrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrHr percentile_approxrrrrr r(r, grouping_idr1r4r7r9r<rErTrYr[r]r_rcrgrmrqrrrurwryr|r~rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr rRrrrr"r+r1r6r:r>r@rCrErHr^rbrrrirrrorrrtrwrzr|rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrTrrrrrrrrrrrrrr r rrrrrr(r*r-r0 is_varcharr3 is_date_valuer6r8r:r<r>r@rBrDrFrHrQr`rbrWrlrnrrrtrvrxrzr|r~rrrrrrrrrrrUrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrIrur as_numberrr r rrrrrrrrrrr"r%rr+r.rX element_atrrr<rIrKrMrOrQrVrYr[r^r`rbrdrfrirkrprsrrrTyperrrrrrrrrrrprrrrrr call_builtin collect_set collect_listbuiltin countDistinctrs to_varcharrmonotonically_increasing_id from_unixtime sort_arraymap_from_arrayssignum array_join array_union map_concatrrr rrrr$r&r(r*r,r/r1r4r6r:r=nvlr@rErHrJrrMrPrSrUrWrYr[r]r_rarebase64riunbase64rlhexrorurwryr{rrrr xpath_float xpath_double xpath_long xpath_shortrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrTrYrVr5si Yt  IIIDDD;)   IH=   SGN v(  %) IN  " BF          %       "    %    C=          %) IN  " BF          %       "   %   C=        4 $(? ?x ?? ? ?> &#&$&&& &, &* ### #c# #  # #L  Bt Bv B  B  D D D  D  ?D ?F ?  ?  Bt Bv B  B  D D D  D CCC C ?D?F? ? AdAfA A BtBvB B AdAfA A BtBvB B JtJvJ J R#RFCK(RR R R"  ? ?$ ?& ?  ?  ,46 2 DHH H$0H=AH H H* DHI I$0I=AI I I* ; tL153FF G;; ; ;|  > > > >  >   9< 9D 9F 9  9  L T V       >>> >6 H HHH H> =|=== =6 <@ #(59  :& RlRtRvR RB >B %*7;  D .O\.Od.Of.O .Ob )-? ?"&?:? ?D )-4 4"&4:4 4n 6< Z Z Z Z Z ..2 3 Z  Z;Z Zz 48ELETEVE E,  15??$?&? ?, $& ( | ( ltv . LTV . O#O$O&O O&  *  c5( )*  c5( )* |S%' (* *  * *Z s46 . s46 . s46 . s46 .  @, @4 @6 @  @ CG #,/<@  8 QU"#56JN  : L#u,- <e+ ,  @ L#u,- <e+ ,  @  @, @4 @6 @  @  :L :T :V :  : 9<9D9F9 9" :L:T:V: :& :L:T:V: :& :L:T:V: :& F\FlFtFvF F(  :L :T :V :  : 9<9D9F9 9$ :L:T:V: :$  9< 9D 9F 9  9   ? ?$ ?& ?  ?  ;\ ;d ;f ;  ;  | fck(: t   @  9< 9D 9F 9  9  :L :T :V :  :  9< 9D 9F 9  9  :L :T :V :  : =|=== =& =|=== =(  9< 9D 9F 9  9  :L :T :V :  : DLDCDDDFD D$ 04A AAA A"  ;\ ;d ;f ;  ; HLLL!-LAEL L L>   :l:t:v: :2 0>|0>l0>t0>v0> 0>f )- +T +T vs{ +T % $ %+T +T  +T +T\ QU= =1=:==JN= = =@ $%&  & & &FCK &! &  &  & &R  4 4 4  4  4  4  4 n ')#$&' 88 8 8$8FCK 8 vs{# 8 ! 88 8 8v ') $W $W $W$$W $W  $W $WN .2 :::uVS[)*: :  : :z MvMsMtMvM M* ??$?&? ?" 26C,C4C6C C" 59F\FdFfF F8 59[ [![.2[ [ [|   !"    < A,A AAQWA A(  CL C| C CPV C  C   A, A\ Ad Af A  A  !!FCK ! &#+ ! !  !  ! !H JN$)&#+$6CG  : JN$)&#+$6CG  : :l:t:v: :. EI$$%c]$>B$ $ $N @D33,39=3 3 3l QU"#56JN  & GK33"8,3@D3 3 3l QU%%"#56%JN% % %P QU"#56JN  > QU"#56JN  > <@(59  D <@(59  D NR''"?3'GK' ' 'T DDD D ?D?F? ? ?D?F? ? :L:T:V: :$ 9<9D9F9 9$ OS$Y $Y&|4$YHL$Y $Y $YN , >4 >6 >  >  @L @T @V @  @  ?< ?D ?F ?  ?  = =$ =& =  =   = =$ =& =  =    @L @T @V @  @   ?< ?D ?F ?  ?  = =$ =& =  =  @L @T @V @  @  C| C C C  C  ?< ?D ?F ?  ?  = =$ =& =  =  F,F4F6F F( F,F4F6F F& EE$E&E E& s!23 63;   s!23 ?D\SVEV?W  63; D 7; 1  c! "1 ,# $1 ,# $1% c 123 1  1  1 1h  HL(4AE      6:-1   c! "  s" #  |S !   c! "  ,# $  ,# $ |S012 )*        26"4"V" "J 7;0  c! "0 s" #0 |S !0  c! " 0 ,# $ 0 ,# $ 0% c 12300 0 0f  HL(4AE      6:   c! "  s" #  |S !   c! "  ,# $  ,# $ |S012        6:%t%% %P 7;-1CY  c! "CY s" #CY |S !CY  c! " CY ,# $ CY ,# $ CY% c 123CY)*CYCY CY CYL @,@4@6@ @$ < <<< <4 @L@T@V@ @0 ?<?D?F? ?. =AO O)O6:O O O& @,@4@6@ @* DlDtDvD D* EI--"3=1->B- - -` ??$?&? ?6 F,F4F6F F$ DH $(=A  6 BFE E".E;?E E EB EIDO DO"1DO>BDO DO DON BFD D".D;?D D D> CC$C&C C4 ;?G<GDGFG G8 CGO<ODOFO O: BFG G".G;?G G G>  ,H ,H ,H,H ,H  ,H ,H^ BFG G".G;?G G G6 BFF F".F;?F F F> @l@t@v@ @* RVG G ,G2>GKOG G GB DHH H$0H=AH H H8 F,F4F6F F6 SW0 0*03?0LP0 0f MOM,M4M M> >,>4> >. 'l't'v' 'T >BC C*C7;C C C: BFI,I4I6I I: 15SS*.S S S< RV L  L) L2> LKO L  L  LF +/ +M +M +M +M,' +M  +M  +M +M\ RV#J #J)#J2>#JKO#J #J #JT :>QQ&Q37Q Q Q* :>MM&M37M M M* :>OO&O37O O O* 8/8d8f8 8& <DF $ | & ltv & LTV &   ( | & >l>t>v> >( ?|??? ?" =\=d=f= =" @ @@@ @" =\=d=f= =" FJ #CM2?C  8 FJ #CM2?C  @  $ 0K 0K}0K C=0K 0K  0K 0Kf   ?|??? ?" =\=d=f= =$ @ @@@ @" ?|??? ?( =\=d=f= =" FlFtFvF F" FlFtFvF F" E\EdEfE E" BF"3-;?  4 > >>> >&  =| = = =  =   ? ?$ ?& ?  ? @,@4@6@ @.  BJ J*J7;J J J$ A\AdAfA A@ ./ 2E 2E 2E c)*2E 2E  2E 2Ej  C, Cl Ct Cv C  C >  c! ">  c! ">> > >B  JN55'65CG5 5 5p        D V | V &   VV V Vr <<< <: 7D7F7 7@ ?D?F? ?@ =$=&= =" =$=&= =B /3 )) )O,) )  )  ) )X :> )) )E&+"567) )  )  ) )X CG#'<@  0 CG#'<@  0 KO+/DH  0 ;U3 $ %;$;&; ;> NN$N&N N: 7; ?| ? ? ?  ?  48 VV37V1V V4 :>YY37Y4Y Y6 #{ '+,004$(;?7;>B$(15 $8<(,!)-483{ 8 { (#{ $x.) { 5hsm+, - {  { SM{ d5eCHo!567 8{ tE#z/234{ { { : ;{ { SM{ tCH~.{ !{ " #{ $ %{ &#+49"5'{ (d38n %){ *+{ ,c]-{ ."#/{ 0"$sCx.11{ 23{ 6  1 1 127{  { | "&r -104$(;?7;>B158<(,!)-48/r h r T#Y0EEFr $x.) r 5hsm+, - r  r SMr d5eCHo!567 8r tE#z/234r r r : ;r r tCH~.r  r !r "#+49"5#r $d38n %%r &'r (c])r *"#+r ,"$sCx.1-r ./r 2 #Y%6%6 673r  r j %)t '+,004$(;?7;>B158<(,!)-48+t fkk "t (#t $x.) t 5hsm+, - t  t SMt d5eCHo!567 8t tE#z/234t t t : ;t t tCH~.t t #+49"5!t "d38n %#t $c]%t &"#'t ("$sCx.1)t *+t . '):): :;/t  t n #g'+,004$(;?7;>B$(15 $8<(,!/g 8 g(#g$x.) g 5hsm+, - g  gSMgd5eCHo!567 8gtE#z/234ggg: ;ggSMgtCH~.g !g" #g$%g&#+49"5'g(d38n %)g*+g,c]-g./g2  1 1 123g gT,d,HSM,X,^ "&F-1'+04$(;?7;>B158<(,$(!/F h FT#Y0EEFF$x.) F $s)$ F 5hsm+, - FFSMFd5eCHo!567 8FtE#z/234FFF: ;FFtCH~.F !F" #F$#+49"5%F&d38n %'F()F*SM+F,c]-F./F2 #Y%6%6 673F FR FJ s ? t v   F hsm+,   ;  B #$( . VV VV V V: JCJDJHJ JF&*   o% &c] **     , #c '+,004$(;?7;6:15IP $8<(,!)-48/c 8 c (#c $x.) c 5hsm+, - c  c SMc d5eCHo!567 8c tE#z/234c c c 2 3c c tCH~.c EFc !c "#c $#+49"5%c &d38n %'c (c])c *+c ,"#-c ."$sCx.1/c 2 ?I-- -.3c  c V #C=    @    0 ,0#C=  8 """" "L      "  "      GK  "8, @D     F KO #03DH  D " !!"&"&!%[ C=[sm[ SM[ C= [ 3- [ C= [c][c][3-[3-[#[ 3-[ 3-[[ [ [| e $(%))- Q L !Q \ "Q!Q Q  Q  Qh d #'$(#'#')- S < S L !S < S < S ! S  S S  Sl  wF 15R R)-R R  R&  wF 15R R)-R R  R(  ;\ ;d ;f ;  ;  ;\ ;d ;f ;  ;  ;\ ;d ;f ;  ;  @, @4 @6 @  @  Il It Iv I  I  JL JT JV J  J  7; J# J04 J  J  J   :L :T :V :  : E<E\EdEfE E"  A| A A$ A& A  A  DF , 9= (E(E((E)1 (E (E  (E (EV 9= )E)E()E)1 )E )E  )E )EX  BL BT BV B  B         B  D D, D4 D6 D  D  BB,B4B6B B"  E, E< ED EF E  E IlI|IIPVI I" @|@ @@@ @$ E,E<EDEFE E$  I I I$ I& I  I  I I I$ I& I  I   C C C$ C& C  C BF"3-;?  , &'" #Q#Qc]#Qsm#Q #Q  #Q #QL  GKXX'}X@DX X X>   , c $     8< +P+P+P5l!234+P +P  +P +P\  | S T     V U V #u* V |S%' (V V V> NR 5sE12 3GK  : "|"3"4"6" "J l#$& : |346 : l#$& : <stv >*) l$$ [ @D),9=  8 GOGGG G: I<IDIFI I( I<IDIFI I& I III I@ ILITIVI I( ILITIVI I( IlItIvI I& I<IDIFI I( ILITIVI I( I\IdIfI I( I<IDIFI I( I<IDIFI I( IlItIvI I( I III I( I<IDIFI I( AA AA A AH e #V+ ,e4:&ee e eP "E !E 6 E E  E  E P O O fd3i/0O O  O  O d R-R$R&R R< 9 9(99 9 9x d d d d  d  d N aR aRaR aR aRH wXwXwX wX wXt  (,&*#'   tnd^  4.        (,&*#'       tn  d^  4.        "'+&*#'n n n 6 ntn n d^ n 4. nn n nb I I II I IX '+Z Z c#Z Z  Z  Z z  : :':(: :  : :rY