- 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> ] )
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>"
},
]
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');
List every table in the catalog:
SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG('myCatalogIntegration', '', 0);
List all of the tables recursively under the db1
namespace:
SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG('myCatalogIntegration', 'db1', 0);
List all of the tables three levels under the db1
namespace:
SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG('myCatalogIntegration', 'db1', 3);