EXECUTE JOB SERVICE¶

Syntax¶

EXECUTE JOB SERVICE
  IN COMPUTE POOL <compute_pool_name>
  {
     fromSpecification
     | fromSpecificationTemplate
  }
  NAME = [<db>.<schema>.]<name>
  [ QUERY_WAREHOUSE = <warehouse_name> ]
  [ COMMENT = '<string_literal>']
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <EAI_name> [ , ... ] ) ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Where:

fromSpecification ::=
  {
    FROM @<stage> SPECIFICATION_FILE = '<yaml_file_stage_path>'
    | FROM SPECIFICATION <specification_text>
  }

Copy

fromSpecificationTemplate ::=
  {
    FROM @<stage> SPECIFICATION_TEMPLATE_FILE = '<yaml_file_stage_path>'
    | FROM SPECIFICATION_TEMPLATE <specification_text>
  }
  USING ( <key> => <value> [ , <key> => <value> [ , ... ] ]  )

Copy

Required parameters¶

IN COMPUTE POOL compute_pool_name

Specifies the name of the compute pool in your account on which to run the service.

FROM stage

Specifies the Snowflake internal stage where the specification file is stored; for example, @tutorial_stage.

SPECIFICATION_FILE = 'yaml_file_stage_path'

Specifies the path to the service specification file on the stage; for example, 'some-dir/echo_spec.yaml'.

SPECIFICATION_TEMPLATE_FILE = 'yaml_file_stage_path'

Specifies the path to the service specification template file on the stage; for example, 'some-dir/echo_template_spec.yaml'. When SPECIFICATION_TEMPLATE_FILE is specified, the USING parameter is required.

FROM SPECIFICATION specification_text

Specifies service specification. You can use a pair of dollar signs ($$) to delimit the beginning and ending of the specification string.

FROM SPECIFICATION_TEMPLATE specification_text

Specifies service specification. You can use a pair of dollar signs ($$) to delimit the beginning and ending of the specification string. When SPECIFICATION_TEMPLATE is specified, the USING parameter is required.

NAME = [db.schema.]name

The name (that is the identifier) for the service, that executes like a job; it must be unique for the schema in which the service is created.

Quoted names for special characters or case-sensitive names are not supported. The same constraint also applies to database and schema names where you create a service. That is, database and schema names without quotes are valid when creating a service.

Optional parameters¶

EXTERNAL_ACCESS_INTEGRATIONS = ( EAI_name [ , ... ] )

Specifies the names of the external access integrations that allow your job to access external sites. The names in this list are case-sensitive. By default, application containers don’t have permission to access the internet. If you want to allow your job to access an external site, create an External Access Integration (EAI), and configure your job to use that integration. For more information, see Network egress.

QUERY_WAREHOUSE = warehouse_name

Warehouse to use if a service container connects to Snowflake to execute a query but does not explicitly specify a warehouse to use.

Default: none.

COMMENT = 'string_literal'

Specifies a comment for the service.

Default: No value

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

Specifies the tag name and the tag string value.

The tag value is always a string, and the maximum number of characters for the tag value is 256.

For information about specifying tags in a statement, see Tag quotas for objects and columns.

USING ( key => value [ , key => value [ , ... ] ]  )

Lets you provide values to parameterize specification template expansion.

USING is required when using a specification template (FROM SPECIFICATION_TEMPLATE_FILE or FROM SPECIFICATION_TEMPLATE). The key-value pairs must form a comma-separated list.

Where:

• key is the name of the template variable. The template variable name can optionally be enclosed in double quotes (").

• value is the value to assign to the variable in the template. String values must be enclosed in ' or $$. The value must either be alphanumeric or valid JSON.

Access control requirements¶

A role used to execute this SQL command must have the following privileges at a minimum:

Note that operating on any object in a schema also requires the USAGE privilege on the parent database and schema.

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¶

• When calling EXECUTE JOB SERVICE, the parameters should be provided in this order: specify compute pool, followed by other properties, and finally the service specification (either provide specification file name on stage or inline specification).

• Regarding metadata:

  Attention

  Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

Examples¶

Execute a Snowpark Container Services job service:

EXECUTE JOB SERVICE
  IN COMPUTE POOL tutorial_compute_pool
  NAME = tutorial_db.data_schema.example_job
  FROM @tutorial_stage
  SPECIFICATION_FILE='my_job_spec.yaml';