snowflake.snowpark.functions.udtf¶
- snowflake.snowpark.functions.udtf(handler: Optional[Callable] = None, *, output_schema: Union[StructType, List[str], PandasDataFrameType], input_types: Optional[List[DataType]] = None, name: Optional[Union[str, Iterable[str]]] = None, is_permanent: bool = False, stage_location: Optional[str] = None, imports: Optional[List[Union[str, Tuple[str, str]]]] = None, packages: Optional[List[Union[str, module]]] = None, replace: bool = False, if_not_exists: bool = False, session: Optional[Session] = None, parallel: int = 4, statement_params: Optional[Dict[str, str]] = None, strict: bool = False, secure: bool = False, external_access_integrations: Optional[List[str]] = None, secrets: Optional[Dict[str, str]] = None, immutable: bool = False) Union[UserDefinedTableFunction, partial] [source]¶
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, usesession.udtf.register
instead. See examples inUDTFRegistration
.- Parameters:
handler – A Python class used for creating the UDTF.
output_schema – A list of column names, or a
StructType
instance that represents the table function’s columns, or aPandasDataFrameType
instance for vectorized UDTF. If a list of column names is provided, theprocess
method of the handler class must have return type hints to indicate the output schema data types.input_types – A list of
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
call_udtf()
. If it is not provided, a name will be automatically generated for the UDTF. A name must be specified whenis_permanent
isTrue
.is_permanent – Whether to create a permanent UDTF. The default is
False
. If it isTrue
, a validstage_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
isTrue
, and it will be ignored whenis_permanent
isFalse
. 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 inadd_import()
) in this list, or a tuple of two strings to represent a file path and an import path (similar to theimport_path
argument inadd_import()
). These UDTF-level imports will override the session-level imports added byadd_import()
.packages – A list of packages that only apply to this UDTF. These UDTF-level packages will override the session-level packages added by
add_packages()
andadd_requirements()
. To use Python packages that are not available in Snowflake, refer tocustom_package_usage_config()
.replace – Whether to replace a UDTF that already was registered. The default is
False
. If it isFalse
, attempting to register a UDTF with a name that already exists results in aSnowparkSQLException
exception being thrown. If it isTrue
, 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
andreplace
are mutually exclusive and aValueError
is raised when both are set. If it isTrue
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.
- Returns:
A UDTF function that can be called with
Column
expressions.
Note
1. When type hints are provided and are complete for a function,
return_type
andinput_types
are optional and will be ignored. See details of supported data types for UDTFs inUDTFRegistration
.You can use use
Variant
to annotate a variant, and useGeography
orGeometry
to annotate geospatial types when defining a UDTF.typing.Union
is not a valid type annotation for UDTFs, buttyping.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
isFalse
) is scoped to thissession
and all UDTF related files will be uploaded to a temporary session stage (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
udtf()
withreplace
set toTrue
will overwrite the previously registered function.See also
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)]