Categories:

System functions (System Information)

SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG¶

Lists tables in a remote Apache Icebergâ„¢ REST catalog (including Polaris Catalog).

See also:

Syntax¶

SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG( '<catalog_integration_name>'
  [ , '<parent_namespace>', <levels> ] )
Copy

Arguments¶

Required:

catalog_integration_name

Identifier for the catalog integration for Iceberg REST or Polaris Catalog.

Optional:

parent_namespace

The identifier of the namespace from which to start listing tables. To retrieve results for the 0th namespace level in the catalog, specify an empty string ('').

Default: The default namespace for the catalog integration (CATALOG_NAMESPACE).

levels

Specifies the number of levels to traverse in the namespace hierarchy for listing tables.

For example:

  • If set to 0, the function returns all of the tables recursively, relative to the parent_namespace.

  • If set to 1, the function returns all of the tables within the parent_namespace.

  • If set to n, the function returns tables up to n levels deep, relative to the parent_namespace.

Default: 1

Returns¶

Returns a JSON-formatted string which lists tables in the Iceberg REST catalog for the specified namespace and number of levels.

The JSON-formatted string has the following structure:

[
  {
    "namespace": "<namespace_identifier>",
    "name": "<table_name>"
  },
  {
    "namespace": "<namespace_identifier>",
    "name": "<table_name_n>"
  },
]
Copy

Access control requirements¶

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

Privilege

Object

Notes

USAGE

Integration (catalog)

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.

Examples¶

List only the tables in the default catalog namespace:

SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG('myCatalogIntegration');
Copy

List every table in the catalog:

SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG('myCatalogIntegration', '', 0);
Copy

List all of the tables recursively under the db1 namespace:

SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG('myCatalogIntegration', 'db1', 0);
Copy

List all of the tables three levels under the db1 namespace:

SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG('myCatalogIntegration', 'db1', 3);
Copy