Making Dependencies Available to Your Code¶
When your user-defined function (UDF) or stored procedure depends on code or files that are external to the UDF or procedure, you can make the dependency available to the UDF or procedure by uploading it to a stage, then referencing it at that location.
For example, you might want your UDF or procedure to have access to the following:
Python handler code in a module.
Java or Scala handler code compiled and packaged in a JAR.
Dependency code written in Java, Python, or Scala.
Files, such as configuration files, read by your handler code.
You can also use the PACKAGES clause of CREATE FUNCTION or CREATE PROCEDURE to import libraries that are included in Snowflake.
Follow these steps to make dependencies available to your function or procedure.
Choose or create a stage that’s available to your handler.
Upload the dependency to the stage.
Reference the dependency with IMPORTS when you create the function or procedure.
Choosing or Creating a Stage for Dependency Files¶
To make your dependency file available to a function or procedure, you’ll need to copy the dependency file to a stage where it can be reached at runtime. The owner of the function or procedure must have the READ privilege to the stage.
Typically, you upload the dependency to a named internal stage using the PUT command. For more about creating stages, see CREATE STAGE.
You can’t execute the
PUT command through the Snowflake GUI; you can use SnowSQL to execute
PUT. For an example
to copy a .jar file to a stage, see Uploading the Dependency to the Stage in this topic.
Choose or create one of the following kinds of stage for your dependency:
A user or named internal stage.
If you plan to use the
PUTcommand to upload the files, use a named internal stage. For more on choosing an internal stage type, see Choosing an Internal Stage for Local Files.
An external stage.
External stages are locations associated with external storage services, as described in CREATE STAGE. The
PUTcommand does not support uploading files to external stages.
You can use an existing stage or you can create a new stage by executing CREATE STAGE. For example,
the following command creates a new internal stage named
CREATE STAGE mystage;
Snowflake does not currently support using a table stage to store handler code.
Uploading the Dependency to the Stage¶
Upload the files required for your stored procedure to a stage.
If you’re using an external stage, use that storage service’s means for uploading files. If you’re using an internal stage, you can copy
the file from a local drive to the stage by using the
PUT command. For command reference, see PUT. For
information on staging files with PUT, see Staging Data Files from a Local File System.
PUT command to upload files to the stage.
Code in the following example uploads
myjar.jar to a stage called
mystage, overwriting an existing file of the same
name if it exists.
PUT file:///Users/MyUserName/MyCompiledJavaCode.jar @mystage AUTO_COMPRESS = FALSE OVERWRITE = TRUE ;
If you omit
AUTO_COMPRESS = FALSE, the PUT command automatically compresses the file. The name of the compressed
file on the stage will be
myjar.jar.gz. Later, when you execute a command such as
CREATE PROCEDURE, you will need to specify the filename
.gz extension in the command’s IMPORTS clause.
The PUT command does not support uploading files to external stages. To upload files to external stages, use the utilities provided by the cloud service.
Referencing the Dependency¶
To make a function or procedure you’re creating aware of the dependency’s location, specify the dependency’s location in the IMPORTS clause of the SQL you use to create the function or procedure.
If you have UDF handler code that must read the contents of a file on a stage – such as to process unstructured data – you can do so without referencing the file in the IMPORTS clause. Instead, you can use APIs that read the file at its stage path using APIs included in Snowflake. For more information, see Reading a File Using IMPORTS.
If you have multiple dependency files, such as when you have third-party libraries on which a handler depends, you can specify the stage location and file path-and-name of all dependency files as values of the IMPORTS clause.
Code in the following example creates a procedure called
MYPROC, specifying that the file
mystage stage) should be included in the procedure’s execution environment. In this case,
contains the procedure’s handler – the compiled code for
CREATE OR REPLACE PROCEDURE MYPROC(value INT, fromTable STRING, toTable STRING, count INT) RETURNS INT LANGUAGE JAVA RUNTIME_VERSION = '11' PACKAGES = ('com.snowflake:snowpark:latest') IMPORTS = ('@mystage/MyCompiledJavaCode.jar') HANDLER = 'MyJavaClass.run';