DESCRIBE ICEBERG TABLE¶

Describes either the columns in an Apache Iceberg™ table or the current values, as well as the default values, for the properties of an Iceberg table.

DESCRIBE can be abbreviated to DESC.

Note that this topic refers to Iceberg tables as simply “tables” except where specifying Iceberg tables avoids confusion.

See also:

ALTER ICEBERG TABLE, DROP ICEBERG TABLE, CREATE ICEBERG TABLE, SHOW ICEBERG TABLES

Syntax¶

DESC[RIBE] [ ICEBERG ] TABLE <name> [ TYPE =  { COLUMNS | STAGE } ]
Copy

Parameters¶

name

Specifies the identifier for the table to describe. 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.

TYPE = COLUMNS | STAGE

Specifies whether to display the columns for the table or the stage properties (including their current and default values) for the table.

Default: TYPE = COLUMNS

Access control requirements¶

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

Privilege

Object

Notes

SELECT

Iceberg table

The USAGE privilege on the parent database and schema are required to perform operations on any object in a schema. Note that a role granted any privilege on a schema allows that role to resolve the schema. For example, a role granted CREATE privilege on a schema can create objects on that schema without also having USAGE granted on that 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¶

  • This command does not show the object parameters for a table. Instead, use SHOW PARAMETERS IN TABLE.

  • DESC ICEBERG TABLE, DESCRIBE TABLE, and DESCRIBE VIEW are interchangeable. Any of these commands retrieves the details for the table or view that matches the criteria in the statement; however, TYPE = STAGE does not apply for views because views don’t have stage properties.

  • The output includes a POLICY NAME column to indicate the masking policy set on the column.

    If a masking policy isn’t set on the column or if the Snowflake account isn’t Enterprise Edition or higher, Snowflake returns NULL.

  • The command returns the NAME_MAPPING column only if you configure Iceberg Compatibility V2 (icebergCompatV2) for the Delta table that your Iceberg table is based on.

    Note

    To view the NAME_MAPPING column, you must also enable the 2025_01 behavior change bundle in your account.

    To enable this bundle in your account, execute the following statement:

    SELECT SYSTEM$ENABLE_BEHAVIOR_CHANGE_BUNDLE('2025_01');
    Copy

  • To post-process the output of this command, you can use the pipe operator (->>) or the RESULT_SCAN function. Both constructs treat the output as a result set that you can query.

    For example, you can use the pipe operator or RESULT_SCAN function to select specific columns from the SHOW command output or filter the rows.

    When you refer to the output columns, use double-quoted identifiers for the column names. For example, to select the output column type, specify SELECT "type".

    You must use double-quoted identifiers because the output column names for SHOW commands are in lowercase. The double quotes ensure that the column names in the SELECT list or WHERE clause match the column names in the SHOW command output that was scanned.

Example¶

Create an example Iceberg table:

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
  CATALOG='my_catalog_integration'
  EXTERNAL_VOLUME='my_ext_volume'
  METADATA_FILE_PATH='path/to/metadata/v2.metadata.json';
Copy

Describe the columns in the table:

DESC ICEBERG TABLE my_iceberg_table ;
Copy
Language: English