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: The linking operation encountered an error and was unsuccessful.

  If the linking operation fails, resolve the error first. Snowflake then automatically schedules the next table discovery sync, unless discovery has been suspended for the catalog-linked database. If you suspended discovery, run ALTER DATABASE … RESUME DISCOVERY after you resolve the error to resume discovery.

  For example:

  ALTER DATABASE IF EXISTS my_linked_db RESUME DISCOVERY;
  

  Copy

failedExecutionStateReason

Error message associated with a FAILED execution state. Doesn’t 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 a table or schema, DROP.

• If the operation is CATALOG_CONNECTION, there was an error when Snowflake attempted to connect to the remote catalog.

• If the operation is DISCOVERY, there was an error when Snowflake attempted to discover the tables or namespaces in your remote catalog. To see which table or namespace caused the error, see entityDomain, which will either be TABLE or NAMESPACE.

Type: String

errorCode

Error code associated with the failure.

Type: String

errorMessage

Error code associated with the failure.

Type: String

Access control requirements¶

A role used to execute this SQL command must have either of the following privileges at a minimum:

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."
    }
  ]
}