Introduction to Python UDFs

You can write the handler for a user-defined function (UDF) in Python. Topics in this section describe how to design and write a Python handler. You’ll also find examples.

For an introduction to UDFs, including a list of languages in which you can write a UDF handler, refer to User-Defined Functions Overview.

Once you have a handler, you create the UDF with SQL. For information on using SQL to create or call a UDF, refer to Creating a UDF or Calling a UDF.

Snowflake currently supports writing UDFs in the following versions of Python:

  • 3.8

  • 3.9

  • 3.10

  • 3.11


For limitations related to Python UDF handlers, refer to Python UDF Limitations.

How a Python Handler Works

When a user calls a UDF, the user passes UDF’s name and arguments to Snowflake. Snowflake calls the associated handler code (with arguments, if any) to execute the UDF’s logic. The handler method then returns the output to Snowflake, which passes it back to the client.

For each row passed to a UDF, the UDF returns either a scalar (i.e. single) value or, if defined as a table function, a set of rows.

Python UDFs can contain both new code and calls to existing packages, allowing you both flexibility and code reuse. For example, if you already have data analysis code in Python, then you can probably incorporate that into a Python UDF handler.


Code in the following example creates a UDF called addone with a handler method addone_py. The Python argument and return types are converted to and from SQL by Snowflake according to mappings described in SQL-Python Data Type Mappings.

create or replace function addone(i int)
returns int
language python
runtime_version = '3.8'
handler = 'addone_py'
def addone_py(i):
  return i+1

Design Considerations

Keep in mind the following for designing a useful handler.

Handler Coding

From basics to detailed examples, the following topics describe how to write a UDF handler in Python.

  • Python module definition. You write the logic for a UDF in a Python module. For more about how Snowflake interacts with your code, refer to Designing the Module.

  • Error handling. For information about how Snowflake surfaces errors generated by handlers, refer to Handling Errors.

  • Tabular return values. You can return tabular values as well as scalar (single) values from a UDF. For information on how to write a handler that returns tabular values, refer to Writing a UDTF in Python.

  • Logging and event tracing. For information on capturing log and trace data as your handler code executes, refer to Logging and Tracing Overview.

  • Dependencies. You can make dependences available to your code at run time by uploading them to a stage. For more informaiton, refer to Making Dependencies Available to Your Code.

  • Code examples For a range of handler examples in Python, refer to Python UDF Handler Examples.