ALTER SERVICE¶

Modifies Snowpark Container Services service configuration, upgrades the code for the service, and allows you to suspend or resume a service. You can:

Apply modifications to a running service. For example, suspend or resume a service, and update the number of service instances running.
Apply modifications that take effect only after service is restarted. For example, specify a default warehouse for queries.
Apply modifications that cause Snowflake to shut down the service, and restart using new code. For example, you might want to deploy updated service code.
Restart the specified instances of a service using the snapshot provided as the initial content for the specified volume. The service must be suspended before you execute ALTER SERVICE.

See also:: CREATE SERVICE , DESCRIBE SERVICE, DROP SERVICE , SHOW SERVICES

Syntax¶

ALTER SERVICE [ IF EXISTS ] <name> { SUSPEND | RESUME }

ALTER SERVICE [ IF EXISTS ] <name>
  {
     fromSpecification
     | fromSpecificationTemplate
  }

ALTER SERVICE [IF EXISTS] <service_name> RESTORE VOLUME <volume_name>
                                                 INSTANCES <comma_separated_instance_ids>
                                                 FROM SNAPSHOT <snapshot_name>

ALTER SERVICE [ IF EXISTS ] <name> SET [ MIN_INSTANCES = <num> ]
                                       [ MAX_INSTANCES = <num> ]
                                       [ MIN_READY_INSTANCES = <num> ]
                                       [ QUERY_WAREHOUSE = <warehouse_name> ]
                                       [ AUTO_RESUME = { TRUE | FALSE } ]
                                       [ EXTERNAL_ACCESS_INTEGRATIONS = ( <EAI_name> [ , ... ] ) ]
                                       [ COMMENT = '<string_literal>' ]



ALTER SERVICE [ IF EXISTS ] <name> UNSET { MIN_INSTANCES                |
                                           MAX_INSTANCES                |
                                           MIN_READY_INSTANCES          |
                                           QUERY_WAREHOUSE              |
                                           AUTO_RESUME                  |
                                           EXTERNAL_ACCESS_INTEGRATIONS |
                                           COMMENT
                                         }
                                         [ , ... ]

ALTER SERVICE [ IF EXISTS ] <name> SET [ TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]]

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_path>' -- for native app service.
    | FROM @<stage> SPECIFICATION_TEMPLATE_FILE = '<yaml_file_path>' -- for non-native app service.
    | FROM SPECIFICATION_TEMPLATE <specification_text>
  }
  USING ( <key> => <value> [ , <key> => <value> [ , ... ] ]  )

Copy

Parameters¶

name

Specifies the identifier for the service to alter.

If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive.

For more information, see Identifier requirements.

{ SUSPEND | RESUME }

Specifies whether to suspend or resume the service.

When you suspend a service, Snowflake shuts down and deletes the containers. If you later resume a suspended service,Snowflake recreates the containers. That is, Snowflake takes the image from your repository and starts the containers. Note that, Snowflake deploys the same image version; it is not a service update operation.

When you invoke a suspended service using either a service function or invoking the public endpoint (ingress), Snowflake automatically resumes 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.

RESTORE VOLUME volume_name INSTANCES comma_separated_instance_ids FROM SNAPSHOT snapshot_name

Restores the snapshot snapshot_name on the existing block storage volume volume_name for the instances comma_separated_instance_ids.

Snapshots can only be taken for block storage volumes (and not for local, memory, or stage volumes).

Volume names are case-sensitive. Therefore, double quotes should always be used to match the corresponding name in the service specification.

SET ...

Sets one or more specified properties or parameters for the service:

MIN_INSTANCES = num

Specifies the minimum number of service instances.

MAX_INSTANCES = num

Specifies the maximum number of service instances.

MIN_READY_INSTANCES = num

Specifies the minimum service instances that must be ready for Snowflake to consider the service ready to process requests. For more information, see Scaling services.

Note

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

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.

AUTO_RESUME = { TRUE | FALSE }

Specifies whether to automatically resume the service when the service function is called or a request is received.

EXTERNAL_ACCESS_INTEGRATIONS = ( EAI_name [ , ... ] )

Specifies the names of the external access integrations that allow your service to access external sites. Snowflake replaces all the existing EAIs with those specified in this parameter. The names in this list are case-sensitive. For more information, see Configuring network egress. Note that this changes the allowed network access for all running instances of the service. You don’t need to explicitly suspend and resume the service.

COMMENT = 'string_literal'

Specifies a comment for the compute pool.

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.

UNSET ...

Specifies one or more properties and/or parameters to unset for the service, which resets them to the defaults (see CREATE SERVICE):

MIN_INSTANCES
MAX_INSTANCES
MIN_READY_INSTANCES
QUERY_WAREHOUSE
AUTO_RESUME
EXTERNAL_ACCESS_INTEGRATIONS
COMMENT

Access control requirements¶

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

Privilege	Object	Notes
OPERATE	Service
USAGE	Snapshot

The USAGE privilege on the parent database and schema are required to perform operations on any object in a 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¶

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¶

Suspend a service.

ALTER SERVICE echo_service SUSPEND;

Copy

Modify the MIN_INSTANCES and MAX_INSTANCES properties of an existing service.

ALTER SERVICE echo_service SET MIN_INSTANCES=3 MAX_INSTANCES=5;

Copy

Restore a snapshot on an existing block volume associated with instances 0 and 2 of the example_service service.

ALTER SERVICE example_service
  RESTORE VOLUME "myvolume"
  INSTANCES 0,2
  FROM SNAPSHOT my_snapshot;

Copy