CREATE SERVICE¶

Creates a new Snowpark Container Services service in the current schema. If a service with that name already exists, use the DROP SERVICE command to delete the previously created service.

You can run more than one instance of your service. Each service instance is a collection of containers, as defined in the service specification file, that run together on a node in your compute pool. If you run multiple instances of a service, a load balancer manages incoming traffic.

Note that the command parameters must be specified in specific order. For more information, see the Usage Notes section.

See also:

ALTER SERVICE , DESCRIBE SERVICE, DROP SERVICE , SHOW SERVICES

Syntax¶

CREATE SERVICE [ IF NOT EXISTS ] <name>
  IN COMPUTE POOL <compute_pool_name>
  {
     fromSpecification
     | fromSpecificationTemplate
  }
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <EAI_name> [ , ... ] ) ]
  [ AUTO_RESUME = { TRUE | FALSE } ]
  [ MIN_INSTANCES = <num> ]
  [ MIN_READY_INSTANCES = <num> ]
  [ MAX_INSTANCES = <num> ]
  [ QUERY_WAREHOUSE = <warehouse_name> ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ COMMENT = '{string_literal}']
Copy

Where:

fromSpecification ::=
  {
    FROM SPECIFICATION_FILE = '<yaml_file_path>' -- for native app service.
    | FROM @<stage> SPECIFICATION_FILE = '<yaml_file_path>' -- for non-native app service.
    | FROM SPECIFICATION <specification_text>
  }
Copy
fromSpecificationTemplate ::=
  {
    FROM SPECIFICATION_TEMPLATE_FILE = '<yaml_file_stage_path>' -- for native app service.
    | FROM @<stage> SPECIFICATION_TEMPLATE_FILE = '<yaml_file_stage_path>' -- for non-native app service.
    | FROM SPECIFICATION_TEMPLATE <specification_text>
  }
  USING ( <key> => <value> [ , <key> => <value> [ , ... ] ]  )
Copy

Required parameters¶

name

String that specifies the identifier (that is, the name) for the service; 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.

IN COMPUTE POOL compute_pool_name

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

FROM ...

Identifies the specification or the template specification for the service.

Using a service specification

You can either define the specification either inline or in a separate file.

SPECIFICATION_FILE = 'yaml_file_path' or . @stage SPECIFICATION_FILE = 'yaml_file_path' or . SPECIFICATION specification_text

Specifies the file containing the service specification or the service specification inline. If your service specification is in a file, use SPECIFICATION_FILE. For services created in a Snowflake Native App, omit @stage, and specify a path relative to the app root directory. For services created in other contexts, specify the Snowflake internal stage and path to the service specification file.

Using a service specification template

You can either define the template specification either inline or in a separate file.

SPECIFICATION_TEMPLATE_FILE = 'yaml_file_path' or . @stage SPECIFICATION_TEMPLATE_FILE = 'yaml_file_path' or . SPECIFICATION_TEMPLATE specification_text

Specifies the file containing the service specification template or the service specification template inline. If your service specification template is in a file, use SPECIFICATION_TEMPLATE_FILE. For services created in a Snowflake Native App, omit @stage, and specify a path relative to the app root directory. For services created in other contexts, specify the Snowflake internal stage and path to the service specification file. When using template specification, you should also include the USING parameter.

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

Specifies the template variables and the values of those variables.

  • 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.

Use a comma between each key-value pair.

Optional parameters¶

EXTERNAL_ACCESS_INTEGRATIONS = ( EAI_name [ , ... ] )

Specifies the names of the external access integrations that allow your service 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 service to access an external site, create an External Access Integration (EAI), and configure your service to use that integration. For more information, see Configuring network egress.

AUTO_RESUME = { TRUE | FALSE }

Specifies whether to automatically resume a service when a service function or ingress is called.

  • If AUTO_RESUME is FALSE, you need to explicitly resume the service (using ALTER SERVICE … RESUME).

  • If AUTO_RESUME is TRUE, Snowflake resumes the suspended service when a service function is called or when a request is received (ingress).

MIN_INSTANCES = num

Specifies the minimum number of service instances to run.

Default: 1.

MIN_READY_INSTANCES = num

Indicates the minimum service instances that must be ready for Snowflake to consider the service is ready to process requests. MIN_READY_INSTANCES must be equal to or less than MIN_INSTANCES.

Note

After you create a service, if you want to use the SHOW SERVICES or DESCRIBE SERVICE command to find the MIN_READY_INSTANCES configured for the service, you must enable the 2024_08 behavior change bundle in your account. To enable this bundle in your account, execute the following statement:

SELECT SYSTEM$ENABLE_BEHAVIOR_CHANGE_BUNDLE('2024_08');
Copy

It works as follows: Suppose MIN_INSTANCES for a service is set to three. Then, Snowflake does not consider the service to be READY until at least three instances are available. While the service is not ready, Snowflake blocks access to it, meaning that associated service functions or ingress requests are denied until readiness is confirmed.

In some cases, you might want Snowflake to consider the service ready (and forward incoming requests) even if fewer than the specified minimum instances are available. You can achieve this by setting the MIN_READY_INSTANCES property.

Consider another scenario: During maintenance or a rolling service upgrade, Snowflake might terminate one or more service instances. This could lead to fewer available instances than the specified MIN_INSTANCES, causing the service to not be in a READY state. In such cases, you might want to set MIN_READY_INSTANCES to a value smaller than MIN_INSTANCES to ensure the service can continue accepting requests.

Default: The value of the MIN_INSTANCES property.

MAX_INSTANCES = num

Specifies the maximum number of service instances to run.

Default: The value of the MIN_INSTANCES property.

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.

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.

COMMENT = 'string_literal'

Specifies a comment for the service.

Default: No value

Access control requirements¶

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

Privilege

Object

Notes

CREATE SERVICE

Schema

USAGE

Compute pool

READ

Stage

This is the stage where the specification is stored.

READ

Image repository

Repository of images referenced by the specification.

BIND SERVICE ENDPOINT

Account

A role must have this privilege to create a service with public endpoints. This allows the service access through the public endpoints. If the service’s owner role loses this privilege, the public endpoints will not be accessible.

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 CREATE SERVICE, the parameters should be provided in this order: specify compute pool, followed by the service specification (either provider specification file on stage or inline specification), and then other properties.

  • 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¶

Create a service with two service instances running:

CREATE SERVICE echo_service
  IN COMPUTE POOL tutorial_compute_pool
  FROM @tutorial_stage
  SPECIFICATION_FILE='echo_spec.yaml'
  MIN_INSTANCES=2
  MAX_INSTANCES=2
Copy
Language: English