schemas

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

Overview

Name	schemas
Type	Resource
Id	snowflake.databases.schemas

Fields

The following fields are returned by SELECT queries:

get

successful

Name	Datatype	Description
name	string	Name of the schema. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
database_name	string	Database that the schema belongs to
budget	string	Budget that defines a monthly spending limit on the compute costs for a Snowflake account or a custom group of Snowflake objects.
comment	string	Optional comment in which to store information related to the schema.
created_on	string (date-time)	Date and time the schema was created.
data_retention_time_in_days	integer	Number of days for which Time Travel actions (CLONE and UNDROP) can be performed on the schema, as well as specifying the default Time Travel retention time for all tables created in the schema
default_ddl_collation	string	Specifies a default collation specification for all tables added to the schema. You an override the default at the schema and individual table levels.
dropped_on	string (date-time)	Date and time the schema was dropped.
is_current	boolean	Current schema for the session.
is_default	boolean	Default schema for a user.
kind	string	Schema type, permanent (default) or transient. (PERMANENT, TRANSIENT) (default: PERMANENT)
log_level	string	Severity level of messages that should be ingested and made available in the active event table. Currently, Snowflake supports only TRACE, DEBUG, INFO, WARN, ERROR, FATAL and OFF.
managed_access	boolean	Whether this schema is a managed access schema that centralizes privilege management with the schema owner.
max_data_extension_time_in_days	integer	Maximum number of days for which Snowflake can extend the data retention period for tables in the schema to prevent streams on the tables from becoming stale.
options	string
owner	string	Name of the role that owns the schema.
owner_role_type	string	Type of role that owns the object, either ROLE or DATABASE_ROLE.
pipe_execution_paused	boolean	Whether pipe execution is paused.
retention_time	integer	Number of days that historical data is retained for Time Travel.
serverless_task_max_statement_size	string	Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
serverless_task_min_statement_size	string	Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
suspend_task_after_num_failures	integer	Specifies the number of consecutive failed task runs after which the current task is suspended automatically.
trace_level	string	How trace events are ingested into the event table. Currently, Snowflake supports only ALWAYS, ON_EVENT, and OFF.
user_task_managed_initial_warehouse_size	string	Size of the compute resources to provision for the first run of the serverless task, before a task history is available for Snowflake to determine an ideal size.
user_task_timeout_ms	integer	Time limit, in milliseconds, for a single run of the task before it times out.

list

Snowflake schema definition.

Name	Datatype	Description
name	string	Name of the schema. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
database_name	string	Database that the schema belongs to
budget	string	Budget that defines a monthly spending limit on the compute costs for a Snowflake account or a custom group of Snowflake objects.
comment	string	Optional comment in which to store information related to the schema.
created_on	string (date-time)	Date and time the schema was created.
data_retention_time_in_days	integer	Number of days for which Time Travel actions (CLONE and UNDROP) can be performed on the schema, as well as specifying the default Time Travel retention time for all tables created in the schema
default_ddl_collation	string	Specifies a default collation specification for all tables added to the schema. You an override the default at the schema and individual table levels.
dropped_on	string (date-time)	Date and time the schema was dropped.
is_current	boolean	Current schema for the session.
is_default	boolean	Default schema for a user.
kind	string	Schema type, permanent (default) or transient. (PERMANENT, TRANSIENT) (default: PERMANENT)
log_level	string	Severity level of messages that should be ingested and made available in the active event table. Currently, Snowflake supports only TRACE, DEBUG, INFO, WARN, ERROR, FATAL and OFF.
managed_access	boolean	Whether this schema is a managed access schema that centralizes privilege management with the schema owner.
max_data_extension_time_in_days	integer	Maximum number of days for which Snowflake can extend the data retention period for tables in the schema to prevent streams on the tables from becoming stale.
options	string
owner	string	Name of the role that owns the schema.
owner_role_type	string	Type of role that owns the object, either ROLE or DATABASE_ROLE.
pipe_execution_paused	boolean	Whether pipe execution is paused.
retention_time	integer	Number of days that historical data is retained for Time Travel.
serverless_task_max_statement_size	string	Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
serverless_task_min_statement_size	string	Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
suspend_task_after_num_failures	integer	Specifies the number of consecutive failed task runs after which the current task is suspended automatically.
trace_level	string	How trace events are ingested into the event table. Currently, Snowflake supports only ALWAYS, ON_EVENT, and OFF.
user_task_managed_initial_warehouse_size	string	Size of the compute resources to provision for the first run of the serverless task, before a task history is available for Snowflake to determine an ideal size.
user_task_timeout_ms	integer	Time limit, in milliseconds, for a single run of the task before it times out.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	database_name, name, endpoint		Fetches a schema.
list	select	database_name, endpoint	like, startsWith, showLimit, fromName, history	Lists the accessible schemas.
create	insert	database_name, endpoint, name	createMode, kind	Creates a schema, with modifiers as query parameters. You must provide the full schema definition when creating a schema.
create_or_alter	replace	database_name, schema_name, endpoint, name	kind	Creates a new, or alters an existing, schema. You must provide the full schema definition even when altering an existing schema.
delete	delete	database_name, name, endpoint	ifExists, restrict	Deletes the specified schema. If you enable the ifExists parameter, the operation succeeds even if the schema does not exist. Otherwise, a 404 failure is returned if the schema does not exist. if the drop is unsuccessful.
clone	exec	database_name, name, endpoint, name	createMode, kind, targetDatabase	Clones an existing schema, with modifiers as query parameters. You must provide the full schema definition when cloning an existing schema.
undrop	exec	database_name, name, endpoint		Undrops schema.

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 identifier (orgname-accountname) (default: orgname-accountname)
name	string	Identifier (i.e. name) for the resource.
schema_name	string	Identifier (i.e. name) for the resource.
createMode	string	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. - orReplace: Automatically replaces the existing resource with the current one. - ifNotExists: Creates a new resource when an alter is requested for a non-existent resource.
fromName	string	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.
history	boolean	Whether to include dropped schemas that have not yet been purged. Default: false.
ifExists	boolean	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.
kind	string	Type of schema to clone. Currently, Snowflake supports only transient and permanent (also represented by the empty string).
like	string	Parameter to filter the command output by resource name. Uses case-insensitive pattern matching, with support for SQL wildcard characters.
restrict	boolean	Whether to drop the schema if foreign keys exist that reference any tables in the schema. - true: Return a warning about existing foreign key references and don't drop the schema. - false: Drop the schema and all objects in the database, including tables with primary or unique keys that are referenced by foreign keys in other tables. Default: false.
showLimit	integer	Parameter to limit the maximum number of rows returned by a command.
startsWith	string	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.
targetDatabase	string	Database of the newly created schema. Defaults to the source schema's database.

SELECT examples

get

Fetches a schema.

SELECT
name,
database_name,
budget,
comment,
created_on,
data_retention_time_in_days,
default_ddl_collation,
dropped_on,
is_current,
is_default,
kind,
log_level,
managed_access,
max_data_extension_time_in_days,
options,
owner,
owner_role_type,
pipe_execution_paused,
retention_time,
serverless_task_max_statement_size,
serverless_task_min_statement_size,
suspend_task_after_num_failures,
trace_level,
user_task_managed_initial_warehouse_size,
user_task_timeout_ms
FROM snowflake.databases.schemas
WHERE database_name = '{{ database_name }}' -- required
AND name = '{{ name }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

list

Lists the accessible schemas.

SELECT
name,
database_name,
budget,
comment,
created_on,
data_retention_time_in_days,
default_ddl_collation,
dropped_on,
is_current,
is_default,
kind,
log_level,
managed_access,
max_data_extension_time_in_days,
options,
owner,
owner_role_type,
pipe_execution_paused,
retention_time,
serverless_task_max_statement_size,
serverless_task_min_statement_size,
suspend_task_after_num_failures,
trace_level,
user_task_managed_initial_warehouse_size,
user_task_timeout_ms
FROM snowflake.databases.schemas
WHERE database_name = '{{ database_name }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND "like" = '{{ like }}'
AND startsWith = '{{ startsWith }}'
AND showLimit = '{{ showLimit }}'
AND fromName = '{{ fromName }}'
AND history = '{{ history }}'
;

INSERT examples

create

Creates a schema, with modifiers as query parameters. You must provide the full schema definition when creating a schema.

INSERT INTO snowflake.databases.schemas (
name,
kind,
comment,
managed_access,
data_retention_time_in_days,
default_ddl_collation,
log_level,
pipe_execution_paused,
max_data_extension_time_in_days,
suspend_task_after_num_failures,
trace_level,
user_task_managed_initial_warehouse_size,
user_task_timeout_ms,
serverless_task_min_statement_size,
serverless_task_max_statement_size,
database_name,
endpoint,
createMode,
kind
)
SELECT 
'{{ name }}' /* required */,
'{{ kind }}',
'{{ comment }}',
{{ managed_access }},
{{ data_retention_time_in_days }},
'{{ default_ddl_collation }}',
'{{ log_level }}',
{{ pipe_execution_paused }},
{{ max_data_extension_time_in_days }},
{{ suspend_task_after_num_failures }},
'{{ trace_level }}',
'{{ user_task_managed_initial_warehouse_size }}',
{{ user_task_timeout_ms }},
'{{ serverless_task_min_statement_size }}',
'{{ serverless_task_max_statement_size }}',
'{{ database_name }}',
'{{ endpoint }}',
'{{ createMode }}',
'{{ kind }}'
RETURNING
status
;

Manifest

# Description fields are for documentation purposes
- name: schemas
props:
  - name: database_name
    value: "{{ database_name }}"
    description: Required parameter for the schemas resource.
  - name: endpoint
    value: "{{ endpoint }}"
    description: Required parameter for the schemas resource.
  - name: name
    value: "{{ name }}"
    description: |
      Name of the schema.
  - name: kind
    value: "{{ kind }}"
    description: |
      Schema type, permanent (default) or transient.
    valid_values: ['PERMANENT', 'TRANSIENT']
    default: PERMANENT
  - name: comment
    value: "{{ comment }}"
    description: |
      Optional comment in which to store information related to the schema.
  - name: managed_access
    value: {{ managed_access }}
    description: |
      Whether this schema is a managed access schema that centralizes privilege management with the schema owner.
    default: false
  - name: data_retention_time_in_days
    value: {{ data_retention_time_in_days }}
    description: |
      Number of days for which Time Travel actions (CLONE and UNDROP) can be performed on the schema, as well as specifying the default Time Travel retention time for all tables created in the schema
  - name: default_ddl_collation
    value: "{{ default_ddl_collation }}"
    description: |
      Specifies a default collation specification for all tables added to the schema. You an override the default at the schema and individual table levels.
  - name: log_level
    value: "{{ log_level }}"
    description: |
      Severity level of messages that should be ingested and made available in the active event table. Currently, Snowflake supports only `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` and `OFF`.
  - name: pipe_execution_paused
    value: {{ pipe_execution_paused }}
    description: |
      Whether pipe execution is paused.
  - name: max_data_extension_time_in_days
    value: {{ max_data_extension_time_in_days }}
    description: |
      Maximum number of days for which Snowflake can extend the data retention period for tables in the schema to prevent streams on the tables from becoming stale.
  - name: suspend_task_after_num_failures
    value: {{ suspend_task_after_num_failures }}
    description: |
      Specifies the number of consecutive failed task runs after which the current task is suspended automatically.
  - name: trace_level
    value: "{{ trace_level }}"
    description: |
      How trace events are ingested into the event table. Currently, Snowflake supports only `ALWAYS`, `ON_EVENT`, and `OFF`.
  - name: user_task_managed_initial_warehouse_size
    value: "{{ user_task_managed_initial_warehouse_size }}"
    description: |
      Size of the compute resources to provision for the first run of the serverless task, before a task history is available for Snowflake to determine an ideal size.
  - name: user_task_timeout_ms
    value: {{ user_task_timeout_ms }}
    description: |
      Time limit, in milliseconds, for a single run of the task before it times out.
  - name: serverless_task_min_statement_size
    value: "{{ serverless_task_min_statement_size }}"
    description: |
      Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
  - name: serverless_task_max_statement_size
    value: "{{ serverless_task_max_statement_size }}"
    description: |
      Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
  - name: createMode
    value: "{{ createMode }}"
    description: 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. - `orReplace`: Automatically replaces the existing resource with the current one. - `ifNotExists`: Creates a new resource when an alter is requested for a non-existent resource.
    description: 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. - `orReplace`: Automatically replaces the existing resource with the current one. - `ifNotExists`: Creates a new resource when an alter is requested for a non-existent resource.
  - name: kind
    value: "{{ kind }}"
    description: Type of schema to create. Currently, Snowflake supports only `transient` and `permanent` (also represented by the empty string).
    description: Type of schema to create. Currently, Snowflake supports only `transient` and `permanent` (also represented by the empty string).

REPLACE examples

create_or_alter

Creates a new, or alters an existing, schema. You must provide the full schema definition even when altering an existing schema.

REPLACE snowflake.databases.schemas
SET 
name = '{{ name }}',
kind = '{{ kind }}',
comment = '{{ comment }}',
managed_access = {{ managed_access }},
data_retention_time_in_days = {{ data_retention_time_in_days }},
default_ddl_collation = '{{ default_ddl_collation }}',
log_level = '{{ log_level }}',
pipe_execution_paused = {{ pipe_execution_paused }},
max_data_extension_time_in_days = {{ max_data_extension_time_in_days }},
suspend_task_after_num_failures = {{ suspend_task_after_num_failures }},
trace_level = '{{ trace_level }}',
user_task_managed_initial_warehouse_size = '{{ user_task_managed_initial_warehouse_size }}',
user_task_timeout_ms = {{ user_task_timeout_ms }},
serverless_task_min_statement_size = '{{ serverless_task_min_statement_size }}',
serverless_task_max_statement_size = '{{ serverless_task_max_statement_size }}'
WHERE 
database_name = '{{ database_name }}' --required
AND schema_name = '{{ schema_name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND name = '{{ name }}' --required
AND kind = '{{ kind}}'
RETURNING
status;

DELETE examples

delete

Deletes the specified schema. If you enable the ifExists parameter, the operation succeeds even if the schema does not exist. Otherwise, a 404 failure is returned if the schema does not exist. if the drop is unsuccessful.

DELETE FROM snowflake.databases.schemas
WHERE database_name = '{{ database_name }}' --required
AND name = '{{ name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND ifExists = '{{ ifExists }}'
AND restrict = '{{ restrict }}'
;

Lifecycle Methods

clone

Clones an existing schema, with modifiers as query parameters. You must provide the full schema definition when cloning an existing schema.

EXEC snowflake.databases.schemas.clone 
@database_name='{{ database_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@kind='{{ kind }}', 
@targetDatabase='{{ targetDatabase }}' 
@@json=
'{
"point_of_time": "{{ point_of_time }}", 
"name": "{{ name }}", 
"kind": "{{ kind }}", 
"comment": "{{ comment }}", 
"managed_access": {{ managed_access }}, 
"data_retention_time_in_days": {{ data_retention_time_in_days }}, 
"default_ddl_collation": "{{ default_ddl_collation }}", 
"log_level": "{{ log_level }}", 
"pipe_execution_paused": {{ pipe_execution_paused }}, 
"max_data_extension_time_in_days": {{ max_data_extension_time_in_days }}, 
"suspend_task_after_num_failures": {{ suspend_task_after_num_failures }}, 
"trace_level": "{{ trace_level }}", 
"user_task_managed_initial_warehouse_size": "{{ user_task_managed_initial_warehouse_size }}", 
"user_task_timeout_ms": {{ user_task_timeout_ms }}, 
"serverless_task_min_statement_size": "{{ serverless_task_min_statement_size }}", 
"serverless_task_max_statement_size": "{{ serverless_task_max_statement_size }}"
}'
;

undrop

Undrops schema.

EXEC snowflake.databases.schemas.undrop 
@database_name='{{ database_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required
;