SYSTEM$CATALOG_LINK_STATUS¶

Syntax¶

SYSTEM$CATALOG_LINK_STATUS( '<catalog_linked_db_name>' )

Arguments¶

'catalog_linked_db_name'

Specifies the name of the catalog-linked database that you want to check the status of.

Returns¶

The function returns a JSON object containing the following name/value pairs:

{
  "executionState":"<value>",
  "failedExecutionStateReason":"<value>",
  "failedExecutionStateErrorCode":"<value>",
  "lastLinkAttemptStartTime":"<value>",
  "failureDetails":[
    {
      "qualifiedEntityName":"<value>",
      "entityDomain":"<value>",
      "operation":"<value>",
      "errorCode":"<value>",
      "errorMessage":"<value>"
    },
    { ... },
    ...
  ]
}

Where:

executionState

Current execution state of the linking operation that Snowflake uses to connect to your Iceberg catalog.

Values:

• RUNNING: The next table discovery sync is scheduled or executing; does not guarantee that all tables have successfully synced.

• FAILED: Linking operation encountered an error and was unsuccessful.

failedExecutionStateReason

Error message associated with a FAILED execution state. Does not appear in the function output if the last sync attempt was successful.

failedExecutionStateErrorCode

Error code associated with a FAILED execution state. Does not appear in the function output if the last sync attempt was successful.

lastLinkAttemptStartTime

Timestamp that indicates when Snowflake last started the process of discovering and syncing changes in the remote catalog.

failureDetails

An array of objects that provide details about entities (for example, tables) in the remote catalog that Snowflake can’t sync. Each object has the following fields:

qualifiedEntityName

The qualified name of the entity in the remote catalog, relative to the catalog name.

For example, namespace_level_1.namespace_level_2.table_name.

Type: String

entityDomain

The entity domain in the remote catalog; for example, TABLE.

Type: String

operation

The operation in Snowflake associated with the sync; for example, CREATE (table or schema), DROP.

Type: String

errorCode

Error code associated with the failure.

Type: String

errorMessage

Error code associated with the failure.

Type: String

Usage notes¶

• The failureDetails field returns information about DROP SCHEMA and DROP ICEBERG TABLE failures.

• Returns results as long as you use a role with a privilege on the specified catalog-linked database. For more information, see Database privileges.

Examples¶

Retrieve the link status for a catalog-linked database named my_cld:

SELECT SYSTEM$CATALOG_LINK_STATUS('my_cld');

Output:

{
  "executionState": "RUNNING",
  "lastLinkAttemptStartTime": "2025-02-14T01:35:01.71Z",
  "failureDetails": [
    {
      "qualifiedEntityName": "my_namespace.table_1",
      "entityDomain": "TABLE",
      "operation": "CREATE",
      "errorCode": "0040000",
      "errorMessage": "An internal error occurred. Please contact Snowflake support."
    },
    {
      "qualifiedEntityName": "my_namespace.table_2",
      "entityDomain": "TABLE",
      "operation": "CREATE",
      "errorCode": "0040000",
      "errorMessage": "An internal error occurred. Please contact Snowflake support."
    }
  ]
}