EXECUTE CODE BUNDLE¶
Note
Notebook Project Objects have been renamed to Code Bundles. The NOTEBOOK PROJECT grammar is still supported; for that syntax, see EXECUTE NOTEBOOK PROJECT. For background on the rename, see the behavior change announcement.
Runs a Code Bundle at the specified entrypoint, or runs source files from a stage or workspace without creating a Code Bundle first (an anonymous run). The command runs the code in a non-interactive (headless) mode and waits for the run to finish. It’s useful for CI/CD pipelines and other orchestrated workflows where you want to pass parameters or lock dependency versions for repeatable runs. You can run the command from:
- SQL files and SQL worksheets.
- Tasks and other Snowflake executables.
- External orchestrators that issue SQL (for example, Airflow, Prefect, Dagster, or CI/CD systems).
The compute type, runtime, dependencies, external access integrations, and secrets are defined in the code_bundle.yml specification. You
can change the specification for a single run with the WITH SPECIFICATION clause, which is merged over the stored specification.
Important
Before triggering a non-interactive run of a notebook, ensure that your notebook sets its execution context (database and schema) or uses fully qualified object names. For more information, see Editing and running notebooks in Workspaces.
Syntax¶
Run a Code Bundle:
Run source files without creating a Code Bundle (anonymous run):
Required parameters¶
nameIdentifier of the Code Bundle to run. Mutually exclusive with
FROM.Must reference an existing Code Bundle created with CREATE CODE BUNDLE. The run uses the Code Bundle’s default version.
Must be fully qualified unless it resides in the current database and schema.
For more information, see Identifier requirements.
FROM 'source'Runs source files directly, without creating a Code Bundle. Mutually exclusive with
name. An anonymous run requiresWITH SPECIFICATION, and the inline specification is the whole configuration: acode_bundle.ymlfile in the source location is ignored.The source you can use depends on the bundle type, compute type, and language in the inline specification:
Specification Source type: custom,compute_type: warehouse,language: pythonA stage directory that contains the entrypoint file, for example '@my_db.my_schema.my_stage/jobs'. A.jarfile is rejected.type: custom,compute_type: warehouse,language: javaorscalaThe stage path of the JAR file that contains the main class, for example '@my_db.my_schema.my_stage/app/app.jar'. A directory is rejected. Add other JAR files withproperties.java_dependencies.jars; JAR files next to the main JAR aren’t added to the classpath.type: custom,compute_type: compute_poolA workspace path, for example 'snow://workspace/USER$.PUBLIC."my_workspace"/versions/live'. Stages aren’t supported. For a shared workspace, use a committed version;versions/liveisn’t supported.type: sparkFor Scala or Java, the stage path of the .jarfile. For Python, the stage directory that contains the entrypoint file, with no trailing slash. See Submit Spark jobs on Snowflake.ENTRYPOINT = 'entrypoint'Specifies what Snowflake runs. The form depends on the language:
- Python script: the path of a
.pyfile, relative to the bundle root (for example,main.pyorjobs/main.py). The file runs as a script, as withpython main.py. - Python method: a
.pyfile and the name of a function in it, separated by a colon (for example,main.py:run). Snowflake imports the file and calls the function, instead of running the file as a script, so code underif __name__ == "__main__":doesn’t run. The function’s return value becomes the run’s return value. - Notebook: the path of a
.ipynbfile (for example,notebooks/train.ipynb). Notebooks run only on compute pools (Container Runtime). - Java or Scala: the fully qualified name of a class that defines
public static void main(String[] args)(Java) ordef main(args: Array[String]): Unit(Scala), for examplecom.example.MyApp. Calling another method of the class isn’t supported. - Spark: for Scala or Java, the fully qualified main class; for Python, the
.pyfile name.
- Python script: the path of a
Optional parameters¶
ARGUMENTS = ( 'arg' [ , 'arg' ... ] )Passes one or more string arguments to the entrypoint at runtime. Arguments are useful for making logic dynamic (for example, selecting an environment such as
--env prod).Specify each argument as a separate quoted string in the list:
- In a Python entrypoint, the arguments appear in
sys.argv:sys.argv[0]is the entrypoint name,sys.argv[1]is the first argument, and so on. - In a Java or Scala entrypoint, the arguments are passed to
mainas theString[]argument.
Each value must be a string literal or a SQL variable reference such as
:my_var. Function calls and other expressions aren’t supported. For an example of passing values computed at runtime, see Pass arguments computed at runtime.Only strings are supported; other data types (such as integers or Booleans) are interpreted as NULL.
The
ARGUMENTSsyntax differs between the two commands:EXECUTE CODE BUNDLEtakes a parenthesized list of strings, while EXECUTE NOTEBOOK PROJECT takes a single string.Example:
- In a Python entrypoint, the arguments appear in
EXECUTION_NAME = 'execution_name'A name for this run. Snowflake records it with the run, so you can find the run later by name, for example with
EXECUTION_NAME => '<execution_name>'in CODE_BUNDLE_HISTORY. The name doesn’t have to be unique. If you omit it, the run has no execution name.Execution names are most useful for anonymous runs, which have no Code Bundle name to filter on.
WITH SPECIFICATION $$ yaml_spec $$Provides a
code_bundle.ymlspecification inline, for this run only. The stored Code Bundle isn’t changed.- Running a Code Bundle by name: the inline specification is merged over the stored
code_bundle.yml. Name only the fields you want to change; every other field keeps its stored value. For the merge rules, see How WITH SPECIFICATION is merged. - Anonymous run (
FROM): the inline specification is required and is the whole configuration. It must includetypeandcompute_type, and every other field the run needs.
The merged (or inline) specification is validated with the same rules as a
code_bundle.ymlfile, so an invalid combination fails with the same error. For the fields, see thecode_bundle.ymlreference.- Running a Code Bundle by name: the inline specification is merged over the stored
INTO :variableIn Snowflake Scripting, assigns the run’s
RETURN_VALUEto a variable. Declare the variable asVARCHAR. See Capture the return value in a variable.
Output¶
Note
Before the RETURN_VALUE behavior change, a successful run returned
a single column named status or result that contained a success message, such as Statement executed successfully. If your code or
tools read that column, update them.
A successful run returns one row with one column:
| Column | Data type | Description |
|---|---|---|
RETURN_VALUE | VARCHAR | The value that the run returned, or NULL. For a notebook on a compute pool, the value passed to notebook.exit(value). For a Python method entrypoint (file.py:method), the value that the method returns. A Python str is returned as is; any other value is returned as JSON text, as produced by json.dumps() with its default settings (for example, {"rows_loaded": 42}, with non-ASCII characters escaped). Every other run returns NULL, including a Python script entrypoint and a Java or Scala entrypoint. |
RETURN_VALUE is also NULL in the following cases:
- The statement returns before the run finishes, for example when the run is executed asynchronously.
- The stages that Snowflake uses to cache notebook results in your account aren’t encrypted with
SNOWFLAKE_FULLencryption.
On a compute pool, including notebook runs, returning a value requires Container Runtime 3.0 or later. Container Runtime 2.x versions don’t support return values.
A return value that can’t be encoded as JSON fails the run with a ReturnValueError. On a compute pool, including notebook runs, the
encoded value can be at most 16 MiB; a larger value fails the run with a ReturnValueError. On a warehouse, the size limits for
stored procedure return values apply.
If the run fails, the command raises an error and returns no row. Decide whether a run succeeded from whether the statement raises an error,
not from RETURN_VALUE. To review past runs, use the CODE_BUNDLE_HISTORY table function.
How WITH SPECIFICATION is merged¶
When you run a Code Bundle by name, the inline specification is applied as a patch over the stored code_bundle.yml (the same convention as
an RFC 7386 JSON merge patch): fields you name override the stored value, and fields you don’t name are inherited. How a field is merged
depends on its shape:
| Field shape | Examples | Behavior |
|---|---|---|
| Scalar | runtime_version, compute_type, requirements_file | The inline value replaces the stored value. |
| Object or map | compute_options, properties, stage_mounts, spark_conf | Merged key by key: keys you name override the stored keys, and other stored keys are kept. |
Empty object ({}) | Any object field | Changes nothing; the stored object is kept. |
| List | secrets, external_access_integrations, artifact_repositories, env_vars, dependency lists | The inline list replaces the whole stored list. To add one item, restate the full list. |
null | Any field | Removes the field for this run. |
env_vars is a list, so naming one environment variable inline drops the other stored variables for that run. Restate every variable that
the run needs.
For example, the stored code_bundle.yml contains:
The following statement changes only the Python version:
The specification used for the run is:
Access control requirements¶
The role that runs the command must have the following privileges:
- To run a Code Bundle by name: OWNERSHIP or USAGE on the Code Bundle, and USAGE on the database and schema that contain it.
- For an anonymous run: read access to the
FROMsource, such as READ on an internal stage or access to the workspace. - For
compute_type: warehouse: USAGE on the current warehouse of the session. The run uses that warehouse. - For
compute_type: compute_pool: USAGE or OWNERSHIP on the compute pool, and USAGE on the query warehouse. - For objects referenced in the specification:
- READ or OWNERSHIP on each secret. USAGE on a secret isn’t sufficient.
- USAGE or OWNERSHIP on each external access integration and artifact repository.
- Read access to the stages in
stage_mountsand to the stages that holdproperties.java_dependencies.jars.
For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.
For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.
Usage notes¶
- The command is synchronous: it returns when the run finishes. The query ID of the statement identifies the run in
CODE_BUNDLE_HISTORY (
QUERY_ID => '<query_id>') and in the event table. - To run the command without waiting for the run to finish, submit it asynchronously from your client (for example,
snow bundle execute --asyncorexecute_async()in the Python connector), then check the run’s status with its query ID. An asynchronous run returns NULL inRETURN_VALUE. - You can’t run the
EXECUTE CODE BUNDLEcommand from a notebook cell. - You can call
EXECUTE CODE BUNDLEfrom tasks, enabling runs as part of larger workflows. For details, see Supported invocation contexts. - Run history and run result visibility for executions triggered by this command depends on the viewing role’s Code Bundle privileges and
IMPERSONATEprivilege over the initiating user. For details, see Run history and result visibility. - For an anonymous run from a workspace, if the workspace changes while Snowflake reads it, the run fails with error 099139. Run the statement again.
Supported invocation contexts¶
EXECUTE CODE BUNDLE runs with caller’s rights, so it’s only supported in contexts that preserve the caller’s identity.
The following table shows where you can run the command:
| Context | Supported | Notes |
|---|---|---|
| SQL worksheet or SQL file | Yes | Runs as the calling user. |
| Task body | Yes | Supported both as a single-statement body and inside a BEGIN ... END Snowflake Scripting block. |
Stored procedure with EXECUTE AS CALLER | Yes | The procedure runs with the caller’s privileges. |
Stored procedure with EXECUTE AS OWNER | No | Owner’s rights procedures can’t run the command. Use EXECUTE AS CALLER instead. |
Stored procedure with EXECUTE AS RESTRICTED CALLER | Only with FULL MANAGEMENT | The caller must grant the FULL MANAGEMENT high-level caller privilege. The run doesn’t apply restricted caller’s rights semantics. |
| Streamlit app | No | Streamlit in Snowflake apps run with owner’s rights by default, and the restricted caller’s rights option isn’t supported by this command. |
| Notebook cell | No | Nested execution isn’t supported. |
Examples¶
Run a Code Bundle:
Run a Code Bundle with arguments and an execution name:
Run a notebook packaged in a Code Bundle (runs on a compute pool):
Call a function in a Python file and return its result. If main.py defines def run(): return {"rows_loaded": 42}, the statement returns
{"rows_loaded": 42} in RETURN_VALUE:
Change one setting for a single run, keeping the rest of the stored specification:
Run Python files from a stage on a warehouse, without creating a Code Bundle:
Run a Java application from a JAR file on a warehouse, without creating a Code Bundle:
Run files from a workspace on a compute pool, without creating a Code Bundle:
Capture the return value in a variable¶
In a Snowflake Scripting block, use INTO to assign RETURN_VALUE to a variable, then use it in later statements:
Pass arguments computed at runtime¶
ARGUMENTS accepts string literals or SQL variables, but not function calls. To pass a value that’s computed at runtime,
assign it to a variable first inside a BEGIN ... END block, then reference the variable with a colon prefix.
The following task reads values from its own CONFIG property with SYSTEM$GET_TASK_GRAPH_CONFIG and passes them to the entrypoint:
Read the arguments in the entrypoint with sys.argv:
The same pattern works with other values available at runtime, such as a predecessor task’s return value from SYSTEM$GET_PREDECESSOR_RETURN_VALUE or a session variable set with SET.
Passing a function call directly to ARGUMENTS isn’t supported and fails to compile: