tables

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

Overview

Name	tables
Type	Resource
Id	snowflake.table.tables

Fields

The following fields are returned by SELECT queries:

list_tables

A Snowflake table

Name	Datatype	Description
name	string	Specifies the name for the table, must be unique for the schema in which the table is created
database_name	string	Database in which the table is stored
schema_name	string	Schema in which the table is stored
automatic_clustering	boolean	If Automatic Clustering is enabled for your account, specifies whether it is explicitly enabled or disabled for the table.
budget	string	Name of the budget if the object is monitored by a budget
bytes	integer (int64)	Number of bytes that will be scanned if the entire table is scanned in a query. Note that this number may be different than the number of actual physical bytes stored on-disk for the table
change_tracking	boolean	Change tracking is enabled or disabled
cluster_by	array	Specifies one or more columns or column expressions in the table as the clustering key
columns	array
comment	string	Comment for the table
constraints	array
created_on	string (date-time)	Date and time when the table was created.
data_retention_time_in_days	integer	Specifies the retention period for the table so that Time Travel actions SELECT, CLONE, UNDROP can be performed on historical data in the table
default_ddl_collation	string	Specifies a default collation specification for the columns in the table, including columns added to the table in the future
dropped_on	string (date-time)	Date and time when the table was dropped
enable_schema_evolution	boolean	Table has schema evolution enabled or disabled
kind	string	Table type - permanent, transient, or temporary (default: PERMANENT)
max_data_extension_time_in_days	integer	Specifies the retention period for the table so that Time Travel actions SELECT, CLONE, UNDROP can be performed on historical data in the table
owner	string	Role that owns the table
owner_role_type	string	The type of role that owns the object.
rows	integer (int64)	Number of rows in the table. Returns NULL for external tables.
search_optimization	boolean	If ON, the table has the search optimization service enabled
search_optimization_bytes	integer (int64)	Number of additional bytes of storage that the search optimization service consumes for this table
search_optimization_progress	integer (int64)	Percentage of the table that has been optimized for search.
table_type	string	Type of the table

fetch_table

A Snowflake table

Name	Datatype	Description
name	string	Specifies the name for the table, must be unique for the schema in which the table is created
database_name	string	Database in which the table is stored
schema_name	string	Schema in which the table is stored
automatic_clustering	boolean	If Automatic Clustering is enabled for your account, specifies whether it is explicitly enabled or disabled for the table.
budget	string	Name of the budget if the object is monitored by a budget
bytes	integer (int64)	Number of bytes that will be scanned if the entire table is scanned in a query. Note that this number may be different than the number of actual physical bytes stored on-disk for the table
change_tracking	boolean	Change tracking is enabled or disabled
cluster_by	array	Specifies one or more columns or column expressions in the table as the clustering key
columns	array
comment	string	Comment for the table
constraints	array
created_on	string (date-time)	Date and time when the table was created.
data_retention_time_in_days	integer	Specifies the retention period for the table so that Time Travel actions SELECT, CLONE, UNDROP can be performed on historical data in the table
default_ddl_collation	string	Specifies a default collation specification for the columns in the table, including columns added to the table in the future
dropped_on	string (date-time)	Date and time when the table was dropped
enable_schema_evolution	boolean	Table has schema evolution enabled or disabled
kind	string	Table type - permanent, transient, or temporary (default: PERMANENT)
max_data_extension_time_in_days	integer	Specifies the retention period for the table so that Time Travel actions SELECT, CLONE, UNDROP can be performed on historical data in the table
owner	string	Role that owns the table
owner_role_type	string	The type of role that owns the object.
rows	integer (int64)	Number of rows in the table. Returns NULL for external tables.
search_optimization	boolean	If ON, the table has the search optimization service enabled
search_optimization_bytes	integer (int64)	Number of additional bytes of storage that the search optimization service consumes for this table
search_optimization_progress	integer (int64)	Percentage of the table that has been optimized for search.
table_type	string	Type of the table

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_tables	select	database_name, schema_name, endpoint	like, startsWith, showLimit, fromName, history, deep	Lists the tables under the database and schema.
fetch_table	select	database_name, schema_name, name, endpoint		Fetch a Table using the describe command output.
create_table	insert	database_name, schema_name, endpoint	createMode, copyGrants	Create a table.
create_or_alter_table	replace	database_name, schema_name, name, endpoint		Create a (or alter an existing) table. Even if the operation is just an alter, the full property set must be provided.
delete_table	delete	database_name, schema_name, name, endpoint	ifExists	Delete a table with the given name.
create_table_as_select_deprecated	exec	database_name, schema_name, name, query, endpoint	createMode, copyGrants	Create a table as select.
create_table_as_select	exec	database_name, schema_name, query, endpoint	createMode, copyGrants	Create a table as select.
create_table_using_template_deprecated	exec	database_name, schema_name, name, query, endpoint	createMode, copyGrants	Create a table using template.
create_table_using_template	exec	database_name, schema_name, query, endpoint	createMode, copyGrants	Create a table using template.
clone_table	exec	database_name, schema_name, name, endpoint	createMode, copyGrants, targetDatabase, targetSchema	Create a new table by cloning from the specified resource
create_table_like_deprecated	exec	database_name, schema_name, name, newTableName, endpoint	createMode, copyGrants	Create a new table like the specified resource, but empty
create_table_like	exec	database_name, schema_name, name, endpoint	createMode, copyGrants	Create a new table like the specified resource, but empty
undrop_table	exec	database_name, schema_name, name, endpoint		Undrop specified table
suspend_recluster_table_deprecated	exec	database_name, schema_name, name, endpoint	ifExists	Suspend recluster of a table
suspend_recluster_table	exec	database_name, schema_name, name, endpoint	ifExists	Suspend recluster of a table
resume_recluster_table_deprecated	exec	database_name, schema_name, name, endpoint	ifExists	Resume recluster of a table
resume_recluster_table	exec	database_name, schema_name, name, endpoint	ifExists	Resume recluster of a table
swap_with_table_deprecated	exec	database_name, schema_name, name, targetTableName, endpoint	ifExists	Swap with another table
swap_with_table	exec	database_name, schema_name, name, targetName, endpoint	ifExists, targetDatabase, targetSchema	Swap with another table

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.
newTableName	string	The name of the table to be created.
query	string	The SQL query that uses INFER_SCHEMA on staged files to set the column definitions for the new table.
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.
targetName	string	The name of the target table to be swapped with.
targetTableName	string	The fully-specified name of the target table to be swapped with.
copyGrants	boolean	Query parameter to enable copy grants when creating the object.
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. - 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.
deep	boolean	Optionally includes dependency information of the table.
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.
history	boolean	Optionally includes dropped tables that have not yet been purged.
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.
targetDatabase	string	Database of the target table. Defaults to the source table's database.
targetSchema	string	Schema of the target table. Defaults to the source table's schema.

SELECT examples

list_tables

Lists the tables under the database and schema.

SELECT
name,
database_name,
schema_name,
automatic_clustering,
budget,
bytes,
change_tracking,
cluster_by,
columns,
comment,
constraints,
created_on,
data_retention_time_in_days,
default_ddl_collation,
dropped_on,
enable_schema_evolution,
kind,
max_data_extension_time_in_days,
owner,
owner_role_type,
rows,
search_optimization,
search_optimization_bytes,
search_optimization_progress,
table_type
FROM snowflake.table.tables
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 }}'
AND history = '{{ history }}'
AND deep = '{{ deep }}';

fetch_table

Fetch a Table using the describe command output.

SELECT
name,
database_name,
schema_name,
automatic_clustering,
budget,
bytes,
change_tracking,
cluster_by,
columns,
comment,
constraints,
created_on,
data_retention_time_in_days,
default_ddl_collation,
dropped_on,
enable_schema_evolution,
kind,
max_data_extension_time_in_days,
owner,
owner_role_type,
rows,
search_optimization,
search_optimization_bytes,
search_optimization_progress,
table_type
FROM snowflake.table.tables
WHERE database_name = '{{ database_name }}' -- required
AND schema_name = '{{ schema_name }}' -- required
AND name = '{{ name }}' -- required
AND endpoint = '{{ endpoint }}' -- required;

INSERT examples

create_table

Create a table.

INSERT INTO snowflake.table.tables (
data__name,
data__kind,
data__cluster_by,
data__enable_schema_evolution,
data__change_tracking,
data__data_retention_time_in_days,
data__max_data_extension_time_in_days,
data__default_ddl_collation,
data__columns,
data__constraints,
data__comment,
database_name,
schema_name,
endpoint,
createMode,
copyGrants
)
SELECT 
'{{ name }}' --required,
'{{ kind }}',
'{{ cluster_by }}',
{{ enable_schema_evolution }},
{{ change_tracking }},
{{ data_retention_time_in_days }},
{{ max_data_extension_time_in_days }},
'{{ default_ddl_collation }}',
'{{ columns }}',
'{{ constraints }}',
'{{ comment }}',
'{{ database_name }}',
'{{ schema_name }}',
'{{ endpoint }}',
'{{ createMode }}',
'{{ copyGrants }}'
;

Manifest

# Description fields are for documentation purposes
- name: tables
  props:
    - name: database_name
      value: string
      description: Required parameter for the tables resource.
    - name: schema_name
      value: string
      description: Required parameter for the tables resource.
    - name: endpoint
      value: string
      description: Required parameter for the tables resource.
    - name: name
      value: string
      description: >
        Specifies the name for the table, must be unique for the schema in which the table is created
        
    - name: kind
      value: string
      description: >
        Table type - permanent, transient, or temporary
        
      valid_values: ['PERMANENT', 'TRANSIENT', 'TEMPORARY', '', 'transient', 'temporary']
      default: PERMANENT
    - name: cluster_by
      value: array
      description: >
        Specifies one or more columns or column expressions in the table as the clustering key
        
    - name: enable_schema_evolution
      value: boolean
      description: >
        Table has schema evolution enabled or disabled
        
    - name: change_tracking
      value: boolean
      description: >
        Change tracking is enabled or disabled
        
    - name: data_retention_time_in_days
      value: integer
      description: >
        Specifies the retention period for the table so that Time Travel actions SELECT, CLONE, UNDROP can be performed on historical data in the table
        
    - name: max_data_extension_time_in_days
      value: integer
      description: >
        Specifies the retention period for the table so that Time Travel actions SELECT, CLONE, UNDROP can be performed on historical data in the table
        
    - name: default_ddl_collation
      value: string
      description: >
        Specifies a default collation specification for the columns in the table, including columns added to the table in the future
        
    - name: columns
      value: array
    - name: constraints
      value: array
    - name: comment
      value: string
      description: >
        Comment for the table
        
    - 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. - `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: copyGrants
      value: boolean
      description: Query parameter to enable copy grants when creating the object.

REPLACE examples

create_or_alter_table

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

REPLACE snowflake.table.tables
SET 
data__name = '{{ name }}',
data__kind = '{{ kind }}',
data__cluster_by = '{{ cluster_by }}',
data__enable_schema_evolution = {{ enable_schema_evolution }},
data__change_tracking = {{ change_tracking }},
data__data_retention_time_in_days = {{ data_retention_time_in_days }},
data__max_data_extension_time_in_days = {{ max_data_extension_time_in_days }},
data__default_ddl_collation = '{{ default_ddl_collation }}',
data__columns = '{{ columns }}',
data__constraints = '{{ constraints }}',
data__comment = '{{ comment }}'
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;

DELETE examples

delete_table

Delete a table with the given name.

DELETE FROM snowflake.table.tables
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

create_table_as_select_deprecated

Create a table as select.

EXEC snowflake.table.tables.create_table_as_select_deprecated 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@query='{{ query }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@copyGrants={{ copyGrants }} 
@@json=
'{
"name": "{{ name }}", 
"kind": "{{ kind }}", 
"cluster_by": "{{ cluster_by }}", 
"enable_schema_evolution": {{ enable_schema_evolution }}, 
"change_tracking": {{ change_tracking }}, 
"data_retention_time_in_days": {{ data_retention_time_in_days }}, 
"max_data_extension_time_in_days": {{ max_data_extension_time_in_days }}, 
"default_ddl_collation": "{{ default_ddl_collation }}", 
"columns": "{{ columns }}", 
"constraints": "{{ constraints }}", 
"comment": "{{ comment }}"
}';

create_table_as_select

Create a table as select.

EXEC snowflake.table.tables.create_table_as_select 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@query='{{ query }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@copyGrants={{ copyGrants }} 
@@json=
'{
"name": "{{ name }}", 
"columns": "{{ columns }}", 
"cluster_by": "{{ cluster_by }}"
}';

create_table_using_template_deprecated

Create a table using template.

EXEC snowflake.table.tables.create_table_using_template_deprecated 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@query='{{ query }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@copyGrants={{ copyGrants }};

create_table_using_template

Create a table using template.

EXEC snowflake.table.tables.create_table_using_template 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@query='{{ query }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@copyGrants={{ copyGrants }} 
@@json=
'{
"name": "{{ name }}"
}';

clone_table

Create a new table by cloning from the specified resource

EXEC snowflake.table.tables.clone_table 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@copyGrants={{ copyGrants }}, 
@targetDatabase='{{ targetDatabase }}', 
@targetSchema='{{ targetSchema }}' 
@@json=
'{
"name": "{{ name }}", 
"kind": "{{ kind }}", 
"cluster_by": "{{ cluster_by }}", 
"enable_schema_evolution": {{ enable_schema_evolution }}, 
"change_tracking": {{ change_tracking }}, 
"data_retention_time_in_days": {{ data_retention_time_in_days }}, 
"max_data_extension_time_in_days": {{ max_data_extension_time_in_days }}, 
"default_ddl_collation": "{{ default_ddl_collation }}", 
"columns": "{{ columns }}", 
"constraints": "{{ constraints }}", 
"comment": "{{ comment }}"
}';

create_table_like_deprecated

Create a new table like the specified resource, but empty

EXEC snowflake.table.tables.create_table_like_deprecated 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@newTableName='{{ newTableName }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@copyGrants={{ copyGrants }};

create_table_like

Create a new table like the specified resource, but empty

EXEC snowflake.table.tables.create_table_like 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@copyGrants={{ copyGrants }} 
@@json=
'{
"name": "{{ name }}"
}';

undrop_table

Undrop specified table

EXEC snowflake.table.tables.undrop_table 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required;

suspend_recluster_table_deprecated

Suspend recluster of a table

EXEC snowflake.table.tables.suspend_recluster_table_deprecated 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ifExists={{ ifExists }};

suspend_recluster_table

Suspend recluster of a table

EXEC snowflake.table.tables.suspend_recluster_table 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ifExists={{ ifExists }};

resume_recluster_table_deprecated

Resume recluster of a table

EXEC snowflake.table.tables.resume_recluster_table_deprecated 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ifExists={{ ifExists }};

resume_recluster_table

Resume recluster of a table

EXEC snowflake.table.tables.resume_recluster_table 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ifExists={{ ifExists }};

swap_with_table_deprecated

Swap with another table

EXEC snowflake.table.tables.swap_with_table_deprecated 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@targetTableName='{{ targetTableName }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ifExists={{ ifExists }};

swap_with_table

Swap with another table

EXEC snowflake.table.tables.swap_with_table 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@targetName='{{ targetName }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ifExists={{ ifExists }}, 
@targetDatabase='{{ targetDatabase }}', 
@targetSchema='{{ targetSchema }}';