ALTER SERVICE¶

Syntax¶

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

ALTER SERVICE [ IF EXISTS ] <name>
  {
    FROM @<stage>
    SPECIFICATION_FILE = '<yaml_file_stage_path>'
    |
    FROM SPECIFICATION <specification_text>
  }

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> ]
                                       [ QUERY_WAREHOUSE = <warehouse_name> ]
                                       [ AUTO_RESUME = { TRUE | FALSE } ]
                                       [ COMMENT = '<string_literal>' ]

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

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

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, if the image in the repository was updated, Snowflake uses the updated image to recreate the containers.

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

FROM SPECIFICATION specification_text

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

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.

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.

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

• QUERY_WAREHOUSE

• AUTO_RESUME

• COMMENT

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¶

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

Modify the MIN_INSTANCES and MAX_INSTANCES properties of an existing service.

ALTER SERVICE echo_service SET MIN_INSTANCES=3 MAX_INSTANCES=5;

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;