Organization
Users and User Groups
Permissions
Data Source
Workspaces
Logical Data Model
Analytical Objects
Reporting
Export & Automations
AI Lake
    AI Lake - Databases
    AI Lake - Pipe Tables
    AI Lake - Services & Operations
    AI Lake - Iceberg REST Catalog
      (BETA) Get catalog configurationget(BETA) Load namespace propertiesget(BETA) Check whether a namespace existshead(BETA) List tables in the namespaceget(BETA) Create a tablepost(BETA) Load a tableget(BETA) Commit updates to a tablepost(BETA) Drop a tabledelete(BETA) Check whether a table existshead
AI Assistant
Agents
Other
Schemas
powered by Zudoku
OpenAPI definition

AI Lake - Iceberg REST Catalog

Endpoint:/

(BETA) Public Apache Iceberg REST Catalog for AI Lake databases.

Point any Iceberg-REST-capable client (PyIceberg, Spark, Trino, dbt, ...) at https://<org-host>/api/v1/ailake/database/<database>/catalog and authenticate with a standard GoodData API token. You never handle cloud credentials: catalog calls are re-signed by the proxy, and data files are read/written by your client directly against object storage using per-request remote signing handled automatically by the client — no credentials are ever returned to the client.

Schema stability disclaimer. The request and response bodies on these endpoints are defined by the Apache Iceberg REST Catalog specification, not by GoodData. The proxy forwards them to the underlying catalog, so their exact shape follows the Apache Iceberg version in use and can change as Apache Iceberg evolves — new fields may appear and existing structures may be extended without a GoodData API version change. The schemas documented here are informative outlines; the authoritative definition is the Apache Iceberg REST Catalog OpenAPI specification (https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml).

Namespaces are provisioned, not created. Each AI Lake database maps to exactly one namespace, created when the database is provisioned. GET .../namespaces (list) and POST .../namespaces (create) are rejected with 403 ForbiddenException; multi-level namespaces are not supported. Address tables as <namespace>.<table> using the database's own namespace.

Not supported through this catalog: registering an existing Iceberg table (registerTable), renaming tables, and views.

Errors use the standard Iceberg REST error envelope {"error": {"message", "type", "code"}}.

(BETA) Get catalog configuration

GET
/api/v1/ailake/database/{databaseId}/catalog/v1/config

(BETA) Returns the catalog configuration for this AI Lake database, per the Apache Iceberg REST Catalog specification. The proxy injects the correct warehouse for the database (any client-supplied warehouse query parameter is ignored) and configures remote signing, so standard clients need no manual setup beyond the catalog URI and a GoodData API token. Response shape follows the Apache Iceberg REST Catalog specification and may change as Apache Iceberg evolves.

(BETA) Get catalog configuration › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

(BETA) Get catalog configuration › Responses

Catalog configuration (defaults, overrides). Includes the catalog prefix used in all subsequent requests — treat it as an opaque value chosen by the server.

  • defaultsobject

    Configuration defaults the client may override.

  • overridesobject

    Configuration the client must apply (includes the catalog prefix and warehouse).

Additional properties are allowed
GET /api/v1/ailake/database/{databaseId}/catalog/v1/config

(BETA) Load namespace properties

GET
/api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}

(BETA) Loads the properties of this database's own namespace. Only the database's provisioned namespace is addressable — any other namespace returns 404 NoSuchNamespaceException. Response shape follows the Apache Iceberg REST Catalog specification and may change as Apache Iceberg evolves.

(BETA) Load namespace properties › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

  • prefixstring · required

    Catalog prefix returned by the config endpoint (GET .../catalog/v1/config). Opaque server-chosen value — Iceberg clients insert it automatically; do not construct it manually.

  • namespacestring · required

    The database's own namespace (commonly the database name). Each AI Lake database has exactly one namespace, created at provisioning time; any other namespace returns 404 NoSuchNamespaceException.

(BETA) Load namespace properties › Responses

Namespace and its properties.

  • namespacestring[]

    Namespace levels. AI Lake namespaces are always single-level.

  • propertiesobject

    Namespace properties.

Additional properties are allowed
GET /api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}

(BETA) Check whether a namespace exists

HEAD
/api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}

(BETA) Existence check for this database's own namespace, per the Apache Iceberg REST Catalog specification.

(BETA) Check whether a namespace exists › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

  • prefixstring · required

    Catalog prefix returned by the config endpoint (GET .../catalog/v1/config). Opaque server-chosen value — Iceberg clients insert it automatically; do not construct it manually.

  • namespacestring · required

    The database's own namespace (commonly the database name). Each AI Lake database has exactly one namespace, created at provisioning time; any other namespace returns 404 NoSuchNamespaceException.

(BETA) Check whether a namespace exists › Responses

Namespace exists.

No data returned
HEAD /api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}

(BETA) List tables in the namespace

GET
/api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables

(BETA) Lists table identifiers in this database's namespace, per the Apache Iceberg REST Catalog specification. Response shape follows the Apache Iceberg REST Catalog specification and may change as Apache Iceberg evolves.

(BETA) List tables in the namespace › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

  • prefixstring · required

    Catalog prefix returned by the config endpoint (GET .../catalog/v1/config). Opaque server-chosen value — Iceberg clients insert it automatically; do not construct it manually.

  • namespacestring · required

    The database's own namespace (commonly the database name). Each AI Lake database has exactly one namespace, created at provisioning time; any other namespace returns 404 NoSuchNamespaceException.

(BETA) List tables in the namespace › query Parameters

  • pageTokenstring

    Opaque pagination token from a previous response.

  • pageSizeinteger

    Maximum number of results to return.

(BETA) List tables in the namespace › Responses

List of table identifiers.

  • identifiersobject[]
  • next-page-tokenstring
Additional properties are allowed
GET /api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables

(BETA) Create a table

POST
/api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables

(BETA) Creates an Iceberg table in this database's namespace, per the Apache Iceberg REST Catalog specification. Table properties, partition specs (identity/day/month/bucket/truncate transforms), and advisory identifier fields are supported. The returned table is immediately write-ready: writes are remote-signed through the catalog with no client-held credentials. Request and response shapes follow the Apache Iceberg REST Catalog specification and may change as Apache Iceberg evolves.

(BETA) Create a table › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

  • prefixstring · required

    Catalog prefix returned by the config endpoint (GET .../catalog/v1/config). Opaque server-chosen value — Iceberg clients insert it automatically; do not construct it manually.

  • namespacestring · required

    The database's own namespace (commonly the database name). Each AI Lake database has exactly one namespace, created at provisioning time; any other namespace returns 404 NoSuchNamespaceException.

(BETA) Create a table › Request Body

  • namestring · required

    Table name.

  • schemaobject · required

    Iceberg schema (Apache Iceberg Schema structure).

  • partition-specobject

    Iceberg partition spec (identity/day/month/bucket/truncate transforms supported).

  • propertiesobject

    Table properties, e.g. format-version, write.format.default.

  • stage-createboolean
  • write-orderobject

    Iceberg sort order.

Additional properties are allowed

(BETA) Create a table › Responses

Table created; result contains the table metadata.

  • configobject
  • metadataobject

    Iceberg table metadata (Apache Iceberg TableMetadata structure).

  • metadata-locationstring
Additional properties are allowed
POST /api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables

(BETA) Load a table

GET
/api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}

(BETA) Loads table metadata (current snapshot, schema, partition spec, snapshot history), per the Apache Iceberg REST Catalog specification. Snapshot history enables time travel by snapshot_id and metadata-table inspection in standard clients. Response shape follows the Apache Iceberg REST Catalog specification and may change as Apache Iceberg evolves.

(BETA) Load a table › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

  • prefixstring · required

    Catalog prefix returned by the config endpoint (GET .../catalog/v1/config). Opaque server-chosen value — Iceberg clients insert it automatically; do not construct it manually.

  • namespacestring · required

    The database's own namespace (commonly the database name). Each AI Lake database has exactly one namespace, created at provisioning time; any other namespace returns 404 NoSuchNamespaceException.

  • tablestring · required

    Table name within the namespace.

(BETA) Load a table › query Parameters

  • snapshotsstring · enum

    Which snapshots to return in the metadata (all or refs), per the Apache Iceberg REST Catalog specification.

    Enum values:
    all
    refs

(BETA) Load a table › Responses

Table metadata.

  • configobject
  • metadataobject

    Iceberg table metadata (Apache Iceberg TableMetadata structure).

  • metadata-locationstring
Additional properties are allowed
GET /api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}

(BETA) Commit updates to a table

POST
/api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}

(BETA) Commits a set of metadata updates and requirements to the table, per the Apache Iceberg REST Catalog specification. This single endpoint carries all write commits made by Iceberg clients: appends, overwrites, row-level deletes, upserts/merges, schema evolution (add/rename/drop column, widening type promotion), and partition-spec evolution. Commits use optimistic concurrency: a concurrent writer that commits first causes 409 CommitFailedException — re-load the table and retry with backoff. Request and response shapes follow the Apache Iceberg REST Catalog specification and may change as Apache Iceberg evolves.

(BETA) Commit updates to a table › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

  • prefixstring · required

    Catalog prefix returned by the config endpoint (GET .../catalog/v1/config). Opaque server-chosen value — Iceberg clients insert it automatically; do not construct it manually.

  • namespacestring · required

    The database's own namespace (commonly the database name). Each AI Lake database has exactly one namespace, created at provisioning time; any other namespace returns 404 NoSuchNamespaceException.

  • tablestring · required

    Table name within the namespace.

(BETA) Commit updates to a table › Request Body

  • requirementsobject[] · required
  • updatesobject[] · required
  • identifierobject
Additional properties are allowed

(BETA) Commit updates to a table › Responses

Commit succeeded; result contains the new metadata location and metadata.

  • metadataobject

    Iceberg table metadata (Apache Iceberg TableMetadata structure).

  • metadata-locationstring
Additional properties are allowed
POST /api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}

(BETA) Drop a table

DELETE
/api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}

(BETA) Drops a table, per the Apache Iceberg REST Catalog specification. Tables on managed storage must be dropped with purge: set purgeRequested=true, which removes the table and its data and metadata files. A plain drop without purge is rejected with 400 BadRequest.

(BETA) Drop a table › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

  • prefixstring · required

    Catalog prefix returned by the config endpoint (GET .../catalog/v1/config). Opaque server-chosen value — Iceberg clients insert it automatically; do not construct it manually.

  • namespacestring · required

    The database's own namespace (commonly the database name). Each AI Lake database has exactly one namespace, created at provisioning time; any other namespace returns 404 NoSuchNamespaceException.

  • tablestring · required

    Table name within the namespace.

(BETA) Drop a table › query Parameters

  • purgeRequestedboolean

    Whether to also purge the table's underlying data and metadata files. Required (true) for AI Lake managed storage; a drop without purge returns 400 BadRequest.

    Default: false

(BETA) Drop a table › Responses

Table dropped.

No data returned
DELETE /api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}

(BETA) Check whether a table exists

HEAD
/api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}

(BETA) Existence check for a table, per the Apache Iceberg REST Catalog specification.

(BETA) Check whether a table exists › path Parameters

  • databaseIdstring · required

    AI Lake database name (preferred, e.g. sales) or UUID. Must be a provisioned AI Lake database owned by the calling organization.

  • prefixstring · required

    Catalog prefix returned by the config endpoint (GET .../catalog/v1/config). Opaque server-chosen value — Iceberg clients insert it automatically; do not construct it manually.

  • namespacestring · required

    The database's own namespace (commonly the database name). Each AI Lake database has exactly one namespace, created at provisioning time; any other namespace returns 404 NoSuchNamespaceException.

  • tablestring · required

    Table name within the namespace.

(BETA) Check whether a table exists › Responses

Table exists.

No data returned
HEAD /api/v1/ailake/database/{databaseId}/catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}
AI Lake - Services & OperationsConversations