services

Creates, updates, deletes, gets or lists a services resource.

Overview

Name	services
Type	Resource
Id	snowflake.service.services

Fields

The following fields are returned by SELECT queries:

list_services

A Snowflake service object.

Name	Datatype	Description
name	string	A Snowflake object identifier. 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. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
database_name	string	A Snowflake object identifier. 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. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
dns_name	string	Snowflake-assiged DNS name of the service. The DNS name enables service-to-service communications.
managing_object_name	string	The name of the managing object (for example, the name of the notebook that manages the service). NULL if the service is not managed by a Snowflake entity.
schema_name	string	A Snowflake object identifier. 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. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
auto_resume	boolean	Specifies whether to automatically resume a service when a service function or ingress is called.
auto_suspend_secs	integer (int64)	Number of seconds of inactivity after which the service will be automatically suspended. The default value is 0 which represents the service will not be automatically suspended.
comment	string	Specifies a comment for the service.
compute_pool	string	Specifies the name of the compute pool in your account on which to run the service.
created_on	string (date-time)	Timestamp when the service was created.
current_instances	integer	The current number of instances for the service.
external_access_integrations	array	Specifies the names of the external access integrations that allow your service to access external sites.
is_async_job	boolean	True if the service is an async job service; false otherwise.
is_job	boolean	True if the service is a job service; false otherwise.
is_upgrading	boolean	TRUE, if Snowflake is in the process of upgrading the service.
managing_object_domain	string	The domain of the managing object (for example, the domain of the notebook that manages the service). NULL if the service is not managed by a Snowflake entity.
max_instances	integer	Specifies the maximum number of service instances to run.
min_instances	integer	Specifies the minimum number of service instances to run.
min_ready_instances	integer	The minimum number of ready service instances to declare the service as READY.
owner	string	Role that owns the service.
owner_role_type	string	The role type of the service owner.
query_warehouse	string	A Snowflake object identifier. 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. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
resumed_on	string (date-time)	Timestamp when the service was last resumed.
spec	object	Specifies service specification.
spec_digest	string	The unique and immutable identifier representing the service spec content.
status	string	The current status of the service.
suspended_on	string (date-time)	Timestamp when the service was last suspended.
target_instances	integer	The target number of service instances that should be running as determined by Snowflake.
updated_on	string (date-time)	Timestamp when the service was last updated.

fetch_service

A Snowflake service object.

Name	Datatype	Description
name	string	A Snowflake object identifier. 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. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
database_name	string	A Snowflake object identifier. 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. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
dns_name	string	Snowflake-assiged DNS name of the service. The DNS name enables service-to-service communications.
managing_object_name	string	The name of the managing object (for example, the name of the notebook that manages the service). NULL if the service is not managed by a Snowflake entity.
schema_name	string	A Snowflake object identifier. 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. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
auto_resume	boolean	Specifies whether to automatically resume a service when a service function or ingress is called.
auto_suspend_secs	integer (int64)	Number of seconds of inactivity after which the service will be automatically suspended. The default value is 0 which represents the service will not be automatically suspended.
comment	string	Specifies a comment for the service.
compute_pool	string	Specifies the name of the compute pool in your account on which to run the service.
created_on	string (date-time)	Timestamp when the service was created.
current_instances	integer	The current number of instances for the service.
external_access_integrations	array	Specifies the names of the external access integrations that allow your service to access external sites.
is_async_job	boolean	True if the service is an async job service; false otherwise.
is_job	boolean	True if the service is a job service; false otherwise.
is_upgrading	boolean	TRUE, if Snowflake is in the process of upgrading the service.
managing_object_domain	string	The domain of the managing object (for example, the domain of the notebook that manages the service). NULL if the service is not managed by a Snowflake entity.
max_instances	integer	Specifies the maximum number of service instances to run.
min_instances	integer	Specifies the minimum number of service instances to run.
min_ready_instances	integer	The minimum number of ready service instances to declare the service as READY.
owner	string	Role that owns the service.
owner_role_type	string	The role type of the service owner.
query_warehouse	string	A Snowflake object identifier. 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. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
resumed_on	string (date-time)	Timestamp when the service was last resumed.
spec	object	Specifies service specification.
spec_digest	string	The unique and immutable identifier representing the service spec content.
status	string	The current status of the service.
suspended_on	string (date-time)	Timestamp when the service was last suspended.
target_instances	integer	The target number of service instances that should be running as determined by Snowflake.
updated_on	string (date-time)	Timestamp when the service was last updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_services	select	database_name, schema_name, endpoint	like, startsWith, showLimit, fromName	Lists the services under the database and schema.
fetch_service	select	database_name, schema_name, name, endpoint		Fetch a service.
create_service	insert	database_name, schema_name, endpoint	createMode	Create a service, with standard create modifiers as query parameters. See the Service component definition for what is required to be provided in the request body.
create_or_alter_service	replace	database_name, schema_name, name, endpoint		Create a (or alter an existing) service. Even if the operation is just an alter, the full property set must be provided.
delete_service	delete	database_name, schema_name, name, endpoint	ifExists	Delete a service with the given name. If ifExists is used, the operation will succeed even if the object does not exist. Otherwise, there will be a failure if the drop is unsuccessful.
execute_job_service	exec	database_name, schema_name, endpoint		Create and execute a job service. See the JobService component definition for what is required to be provided in the request body.
resume_service	exec	database_name, schema_name, name, endpoint	ifExists	Resume a service.
suspend_service	exec	database_name, schema_name, name, endpoint	ifExists	Suspend a service.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
database_name	string	Identifier (i.e. name) for the database to which the resource belongs. You can use the /api/v2/databases GET request to get a list of available databases.
endpoint	string	Organization and Account Name (default: orgid-acctid)
name	string	Identifier (i.e. name) for the resource.
schema_name	string	Identifier (i.e. name) for the schema to which the resource belongs. You can use the /api/v2/databases/{database}/schemas GET request to get a list of available schemas for the specified database.
createMode	string	Query parameter allowing support for different modes of resource creation. Possible values include: - errorIfExists: Throws an error if you try to create a resource that already exists. - ifNotExists: Creates a new resource when an alter is requested for a non-existent resource.
fromName	string	Query parameter to enable fetching rows only following the first row whose object name matches the specified string. Case-sensitive and does not have to be the full name.
ifExists	boolean	Query parameter that specifies how to handle the request for a resource that does not exist: - true: The endpoint does not throw an error if the resource does not exist. It returns a 200 success response, but does not take any action on the resource. - false: The endpoint throws an error if the resource doesn't exist.
like	string	Query parameter to filter the command output by resource name. Uses case-insensitive pattern matching, with support for SQL wildcard characters.
showLimit	integer	Query parameter to limit the maximum number of rows returned by a command.
startsWith	string	Query parameter to filter the command output based on the string of characters that appear at the beginning of the object name. Uses case-sensitive pattern matching.

SELECT examples

list_services

Lists the services under the database and schema.

SELECT
name,
database_name,
dns_name,
managing_object_name,
schema_name,
auto_resume,
auto_suspend_secs,
comment,
compute_pool,
created_on,
current_instances,
external_access_integrations,
is_async_job,
is_job,
is_upgrading,
managing_object_domain,
max_instances,
min_instances,
min_ready_instances,
owner,
owner_role_type,
query_warehouse,
resumed_on,
spec,
spec_digest,
status,
suspended_on,
target_instances,
updated_on
FROM snowflake.service.services
WHERE database_name = '{{ database_name }}' -- required
AND schema_name = '{{ schema_name }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND like = '{{ like }}'
AND startsWith = '{{ startsWith }}'
AND showLimit = '{{ showLimit }}'
AND fromName = '{{ fromName }}';

fetch_service

Fetch a service.

SELECT
name,
database_name,
dns_name,
managing_object_name,
schema_name,
auto_resume,
auto_suspend_secs,
comment,
compute_pool,
created_on,
current_instances,
external_access_integrations,
is_async_job,
is_job,
is_upgrading,
managing_object_domain,
max_instances,
min_instances,
min_ready_instances,
owner,
owner_role_type,
query_warehouse,
resumed_on,
spec,
spec_digest,
status,
suspended_on,
target_instances,
updated_on
FROM snowflake.service.services
WHERE database_name = '{{ database_name }}' -- required
AND schema_name = '{{ schema_name }}' -- required
AND name = '{{ name }}' -- required
AND endpoint = '{{ endpoint }}' -- required;

INSERT examples

create_service

Create a service, with standard create modifiers as query parameters. See the Service component definition for what is required to be provided in the request body.

INSERT INTO snowflake.service.services (
data__name,
data__status,
data__compute_pool,
data__spec,
data__external_access_integrations,
data__query_warehouse,
data__comment,
data__is_async_job,
data__auto_resume,
data__min_ready_instances,
data__min_instances,
data__max_instances,
data__database_name,
data__schema_name,
data__auto_suspend_secs,
database_name,
schema_name,
endpoint,
createMode
)
SELECT 
'{{ name }}' --required,
'{{ status }}',
'{{ compute_pool }}' --required,
'{{ spec }}' --required,
'{{ external_access_integrations }}',
'{{ query_warehouse }}',
'{{ comment }}',
{{ is_async_job }},
{{ auto_resume }},
{{ min_ready_instances }},
{{ min_instances }},
{{ max_instances }},
'{{ database_name }}',
'{{ schema_name }}',
{{ auto_suspend_secs }},
'{{ database_name }}',
'{{ schema_name }}',
'{{ endpoint }}',
'{{ createMode }}'
;

Manifest

# Description fields are for documentation purposes
- name: services
  props:
    - name: database_name
      value: string
      description: Required parameter for the services resource.
    - name: schema_name
      value: string
      description: Required parameter for the services resource.
    - name: endpoint
      value: string
      description: Required parameter for the services resource.
    - name: name
      value: string
      description: >
        A Snowflake object identifier. 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.
        
    - name: status
      value: string
      description: >
        The current status of the service.
        
    - name: compute_pool
      value: string
      description: >
        Specifies the name of the compute pool in your account on which to run the service.
        
    - name: spec
      value: object
      description: >
        Specifies service specification.
        
    - name: external_access_integrations
      value: array
      description: >
        Specifies the names of the external access integrations that allow your service to access external sites.
        
    - name: query_warehouse
      value: string
      description: >
        A Snowflake object identifier. 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.
        
    - name: comment
      value: string
      description: >
        Specifies a comment for the service.
        
    - name: is_async_job
      value: boolean
      description: >
        True if the service is an async job service; false otherwise.
        
    - name: auto_resume
      value: boolean
      description: >
        Specifies whether to automatically resume a service when a service function or ingress is called.
        
    - name: min_ready_instances
      value: integer
      description: >
        The minimum number of ready service instances to declare the service as READY.
        
    - name: min_instances
      value: integer
      description: >
        Specifies the minimum number of service instances to run.
        
    - name: max_instances
      value: integer
      description: >
        Specifies the maximum number of service instances to run.
        
    - name: database_name
      value: string
      description: >
        A Snowflake object identifier. 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.
        
    - name: schema_name
      value: string
      description: >
        A Snowflake object identifier. 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.
        
    - name: auto_suspend_secs
      value: integer
      description: >
        Number of seconds of inactivity after which the service will be automatically suspended. The default value is 0 which represents the service will not be automatically suspended.
        
    - name: createMode
      value: string
      description: Query parameter allowing support for different modes of resource creation. Possible values include: - `errorIfExists`: Throws an error if you try to create a resource that already exists. - `ifNotExists`: Creates a new resource when an alter is requested for a non-existent resource.

REPLACE examples

create_or_alter_service

Create a (or alter an existing) service. Even if the operation is just an alter, the full property set must be provided.

REPLACE snowflake.service.services
SET 
data__name = '{{ name }}',
data__status = '{{ status }}',
data__compute_pool = '{{ compute_pool }}',
data__spec = '{{ spec }}',
data__external_access_integrations = '{{ external_access_integrations }}',
data__query_warehouse = '{{ query_warehouse }}',
data__comment = '{{ comment }}',
data__is_async_job = {{ is_async_job }},
data__auto_resume = {{ auto_resume }},
data__min_ready_instances = {{ min_ready_instances }},
data__min_instances = {{ min_instances }},
data__max_instances = {{ max_instances }},
data__database_name = '{{ database_name }}',
data__schema_name = '{{ schema_name }}',
data__auto_suspend_secs = {{ auto_suspend_secs }}
WHERE 
database_name = '{{ database_name }}' --required
AND schema_name = '{{ schema_name }}' --required
AND name = '{{ name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND data__name = '{{ name }}' --required
AND data__compute_pool = '{{ compute_pool }}' --required
AND data__spec = '{{ spec }}' --required
RETURNING
status;

DELETE examples

delete_service

Delete a service with the given name. If ifExists is used, the operation will succeed even if the object does not exist. Otherwise, there will be a failure if the drop is unsuccessful.

DELETE FROM snowflake.service.services
WHERE database_name = '{{ database_name }}' --required
AND schema_name = '{{ schema_name }}' --required
AND name = '{{ name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND ifExists = '{{ ifExists }}';

Lifecycle Methods

execute_job_service

Create and execute a job service. See the JobService component definition for what is required to be provided in the request body.

EXEC snowflake.service.services.execute_job_service 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"name": "{{ name }}", 
"status": "{{ status }}", 
"compute_pool": "{{ compute_pool }}", 
"spec": "{{ spec }}", 
"external_access_integrations": "{{ external_access_integrations }}", 
"query_warehouse": "{{ query_warehouse }}", 
"comment": "{{ comment }}", 
"is_async_job": {{ is_async_job }}
}';

resume_service

Resume a service.

EXEC snowflake.service.services.resume_service 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ifExists={{ ifExists }};

suspend_service

Suspend a service.

EXEC snowflake.service.services.suspend_service 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ifExists={{ ifExists }};