diff --git a/.github/ISSUE_TEMPLATE/1-bug_report.yml b/.github/ISSUE_TEMPLATE/1-bug_report.yml index f7491b37e5..6bf592a367 100644 --- a/.github/ISSUE_TEMPLATE/1-bug_report.yml +++ b/.github/ISSUE_TEMPLATE/1-bug_report.yml @@ -22,7 +22,7 @@ body: - type: markdown attributes: value: | - Verify that the issue is not already reported, looking at the [currently open issues](https://github.com/polaris-catalog/polaris/issues), use the `Filter` field to narrow down your search. + Verify that the issue is not already reported, looking at the [currently open issues](https://github.com/apache/polaris/issues), use the `Filter` field to narrow down your search. Please provide a title above with a short, concise summary - don't leave it "empty". diff --git a/.github/ISSUE_TEMPLATE/2-feature_request.yml b/.github/ISSUE_TEMPLATE/2-feature_request.yml index 6ef8fc8b6e..492174aef9 100644 --- a/.github/ISSUE_TEMPLATE/2-feature_request.yml +++ b/.github/ISSUE_TEMPLATE/2-feature_request.yml @@ -22,7 +22,7 @@ body: - type: markdown attributes: value: | - Verify that the feature request is not already reported, looking at the [currently open issues](https://github.com/polaris-catalog/polaris/issues), use the `Filter` field to narrow down your search. + Verify that the feature request is not already reported, looking at the [currently open issues](https://github.com/apache/polaris/issues), use the `Filter` field to narrow down your search. Please provide a title above with a short, concise summary - don't leave it "empty". diff --git a/build.gradle.kts b/build.gradle.kts index 151e50efe5..80eb3a7e37 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -45,7 +45,7 @@ if (System.getProperty("idea.sync.active").toBoolean()) { val img = java.net .URI( - "https://raw.githubusercontent.com/polaris-catalog/polaris/main/docs/img/logos/polaris-brandmark.png" + "https://raw.githubusercontent.com/apache/polaris/main/docs/img/logos/polaris-brandmark.png" ) .toURL() .openConnection() diff --git a/docs/configuring-polaris-for-production.md b/docs/configuring-polaris-for-production.md index 5f0a21c250..5172744c35 100644 --- a/docs/configuring-polaris-for-production.md +++ b/docs/configuring-polaris-for-production.md @@ -31,7 +31,7 @@ Notable configuration used to secure a Polaris deployment are outlined below. > Ensure that the `tokenBroker` setting reflects the token broker specified in `authenticator` below. * Configure [OAuth](https://oauth.net/2/) with this setting. Remove the `TestInlineBearerTokenPolarisAuthenticator` option and uncomment the `DefaultPolarisAuthenticator` authenticator option beneath it. -* Then, configure the token broker. You can configure the token broker to use either [asymmetric](https://github.com/polaris-catalog/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTRSAKeyPair.java#L24) or [symmetric](https://github.com/polaris-catalog/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTSymmetricKeyBroker.java#L23) keys. +* Then, configure the token broker. You can configure the token broker to use either [asymmetric](https://github.com/apache/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTRSAKeyPair.java#L24) or [symmetric](https://github.com/apache/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTSymmetricKeyBroker.java#L23) keys. #### authenticator.tokenBroker @@ -40,14 +40,14 @@ Notable configuration used to secure a Polaris deployment are outlined below. #### callContextResolver & realmContextResolver * Use these configurations to specify a service that can resolve a realm from bearer tokens. -* The service(s) used here must implement the relevant interfaces (i.e. [CallContextResolver](https://github.com/polaris-catalog/polaris/blob/8290019c10290a600e40b35ddb1e2f54bf99e120/polaris-service/src/main/java/io/polaris/service/context/CallContextResolver.java#L27) and [RealmContextResolver](https://github.com/polaris-catalog/polaris/blob/7ce86f10a68a3b56aed766235c88d6027c0de038/polaris-service/src/main/java/io/polaris/service/context/RealmContextResolver.java)). +* The service(s) used here must implement the relevant interfaces (i.e. [CallContextResolver](https://github.com/apache/polaris/blob/8290019c10290a600e40b35ddb1e2f54bf99e120/polaris-service/src/main/java/io/polaris/service/context/CallContextResolver.java#L27) and [RealmContextResolver](https://github.com/apache/polaris/blob/7ce86f10a68a3b56aed766235c88d6027c0de038/polaris-service/src/main/java/io/polaris/service/context/RealmContextResolver.java)). ## Metastore Management > [!IMPORTANT] > The default `in-memory` implementation for `metastoreManager` is meant for testing and not suitable for production usage. Instead, consider an implementation such as `eclipse-link` which allows you to store metadata in a remote database. -A Metastore Manger should be configured with an implementation that durably persists Polaris entities. Use the configuration `metaStoreManager` to configure a [MetastoreManager](https://github.com/polaris-catalog/polaris/blob/627dc602eb15a3258dcc32babf8def34cf6de0e9/polaris-core/src/main/java/io/polaris/core/persistence/PolarisMetaStoreManager.java#L47) implementation where Polaris entities will be persisted. +A Metastore Manger should be configured with an implementation that durably persists Polaris entities. Use the configuration `metaStoreManager` to configure a [MetastoreManager](https://github.com/apache/polaris/blob/627dc602eb15a3258dcc32babf8def34cf6de0e9/polaris-core/src/main/java/io/polaris/core/persistence/PolarisMetaStoreManager.java#L47) implementation where Polaris entities will be persisted. Be sure to secure your metastore backend since it will be storing credentials and catalog metadata. diff --git a/docs/index.html b/docs/index.html index ca2c54008b..7bb93a95e1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -12,425 +12,425 @@ margin: 0; } - -
Polaris Catalog Logo
API docs by Redocly
Polaris Catalog Logo
API docs by Redocly

Polaris Catalog Documentation

Download OpenAPI specification:Download

E-mail: community [at] polaris.io URL: https://github.com/polaris-catalog/polaris License: Apache v2.0

Polaris Catalog Documentation

Download OpenAPI specification:Download

E-mail: community [at] polaris.io URL: https://github.com/apache/polaris License: Apache v2.0
-

Quick Start

Quick Start

This guide serves as a introduction to several key entities that can be managed with Polaris, describes how to build and deploy Polaris locally, and finally includes examples of how to use Polaris with Apache Spark.

-

Prerequisites

Prerequisites

Building and Deploying Polaris

Then, use git to clone the Polaris repo:

cd ~
-git clone https://github.com/polaris-catalog/polaris.git
+git clone https://github.com/apache/polaris.git

With Docker

If you plan to deploy Polaris inside Docker, you'll need to install docker itself. For example, this can be done using homebrew:

@@ -548,7 +548,7 @@

With Spark

cd ~/spark git checkout branch-3.5 -

Deploying Polaris

Deploying Polaris

Building Polaris INFO [...] [main] [] o.eclipse.jetty.server.Server: Started Server@...

At this point, Polaris is running.

-

Bootstrapping Polaris

Bootstrapping Polaris

Building Polaris 
export CLIENT_ID=<client-id> 
 export CLIENT_SECRET=<client-secret>
-

Defining a Catalog

Defining a Catalog

Creating a Principal a

This grants the catalog privileges CATALOG_MANAGE_CONTENT to our catalog role, linking everything together like so:

Principal to Catalog with Catalog Role

CATALOG_MANAGE_CONTENT has create/list/read/write privileges on all entities within the catalog. The same privilege could be granted to a namespace, in which case the principal could create/list/read/write any entity under that namespace.

-

Using Iceberg & Polaris

Using Iceberg & Polaris

Connecting with Spark org.apache.iceberg.exceptions.ForbiddenException: Forbidden: Principal 'quickstart_user' with activated PrincipalRoles '[]' and activated ids '[6, 7]' is not authorized for op LOAD_TABLE_WITH_READ_DELEGATION -

Polaris Catalog Overview

Polaris Catalog Overview

Connecting with Spark

Polaris Catalog is a catalog implementation for Apache Iceberg™ tables and is built on the open source Apache Iceberg™ REST protocol.

With Polaris Catalog, you can provide centralized, secure read and write access to your Iceberg tables across different REST-compatible query engines.

Conceptual diagram of Polaris Catalog.

-

Key concepts

Key concepts

Storage configuration
  • Default base location for your Microsoft Azure container
  • Locations for your Microsoft Azure container
  • Azure tenant ID
-

Example workflow

Example workflow

Storage configuration

Diagram that shows an example workflow for Polaris Catalog

-

Security and access control

Security and access control

Access control

For more information, see Access control.

-

Legal Notices

Legal Notices

Apache®, Apache Iceberg™, Apache Spark™, Apache Flink®, and Flink® are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries.

-

Polaris Catalog Entities

Polaris Catalog Entities

Access control -->

This page documents various entities that can be managed in Polaris.

-

Catalog

Catalog

Access control

Storage Type

All catalogs in Polaris are associated with a storage type. Valid Storage Types are S3, Azure, and GCS. The FILE type is also additionally available for testing. Each of these types relates to a different storage provider where data within the catalog may reside. Depending on the storage type, various other configurations may be set for a catalog including credentials to be used when accessing data inside the catalog.

For details on how to use Storage Types in the REST API, see the API docs.

-

Namespace

Namespace

A namespace is a logical entity that resides within a catalog and can contain other entities such as tables or views. Some other systems may refer to namespaces as schemas or databases.

In Polaris, namespaces can be nested. For example, a.b.c.d.e.f.g is a valid namespace. b is said to reside within a, and so on.

For information on managing namespaces with the REST API or for more information on what data can be associated with a namespace, see the API docs.

-

Table

Table

Polaris tables are entities that map to Apache Iceberg tables.

For information on managing tables with the REST API or for more information on what data can be associated with a table, see the API docs.

-

View

View

Polaris views are entities that map to Apache Iceberg views.

For information on managing views with the REST API or for more information on what data can be associated with a view, see the API docs.

-

Principal

Principal

Polaris principals are unique identities that can be used to represent users or services. Each principal may have one or more principal roles assigned to it for the purpose of accessing catalogs and the entities within them.

For information on managing principals with the REST API or for more information on what data can be associated with a principal, see the API docs.

-

Principal Role

Principal Role

Polaris principal roles are labels that may be granted to principals. Each principal may have one or more principal roles, and the same principal role may be granted to multiple principals. Principal roles may be assigned based on the persona or responsibilities of a given principal, or on how that principal will need to access different entities within Polaris.

For information on managing principal roles with the REST API or for more information on what data can be associated with a principal role, see the API docs.

-

Catalog Role

Catalog Role

Polaris catalog roles are labels that may be granted to catalogs. Each catalog may have one or more catalog roles, and the same catalog role may be granted to multiple catalogs. Catalog roles may be assigned based on the nature of data that will reside in a catalog, or by the groups of users and services that might need to access that data.

Each catalog role may have multiple privileges granted to it, and each catalog role can be granted to one or more principal roles. This is the mechanism by which principals are granted access to entities inside a catalog such as namespaces and tables.

-

Privilege

Privilege

Storage Type
  • Namespace Privileges
  • Catalog Privileges
    • -

    Access Control

    Access Control

    Storage Type
  • Catalog role
  • Privilege
    • -

    Securable object

    Securable object

    Storage Type
  • Iceberg table
  • View
    • -

    Principal role

    Principal role

    Storage Type A role that is granted to multiple service principals for running data science or AI jobs. -

    Catalog role

    Catalog role

    Storage Type A role that has been granted read and write access privileges to all tables that belong to the catalog.

    Principal roles that have been granted this role are allowed to perform read and write operations on tables in the catalog. -

    RBAC model

    RBAC model

    Storage Type privileges to catalog roles and then grants service principals access to resources by assigning catalog roles to principal roles. Polaris supports a many-to-one relationship between service principals and principal roles.

    Diagram that shows the RBAC model for Polaris Catalog.

    -

    Access control privileges

    Access control privileges

    Catalog privileges Enables configuring catalog properties. -

    RBAC example

    RBAC example

    Catalog privileges

    Diagram that shows an example of how RBAC works in Polaris Catalog.

    -

    Configuring Polaris for Production

    Configuring Polaris for Production

    Catalog privileges --> -

    Configuring Polaris for Production

    Configuring Polaris for Production

    The default polaris-server.yml configuration is intended for develoment and testing. When deploying Polaris in production, there are several best practices to keep in mind.

    -

    Security

    Security

    Catalog privileges </blockquote> <ul> <li>Configure <a href="https://oauth.net/2/">OAuth</a> with this setting. Remove the <code>TestInlineBearerTokenPolarisAuthenticator</code> option and uncomment the <code>DefaultPolarisAuthenticator</code> authenticator option beneath it.</li> -<li>Then, configure the token broker. You can configure the token broker to use either <a href="https://github.com/polaris-catalog/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTRSAKeyPair.java#L24">asymmetric</a> or <a href="https://github.com/polaris-catalog/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTSymmetricKeyBroker.java#L23">symmetric</a> keys.</li> +<li>Then, configure the token broker. You can configure the token broker to use either <a href="https://github.com/apache/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTRSAKeyPair.java#L24">asymmetric</a> or <a href="https://github.com/apache/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTSymmetricKeyBroker.java#L23">symmetric</a> keys.</li> </ul> <h4 id="authenticatortokenbroker">authenticator.tokenBroker</h4> <blockquote> @@ -1973,7 +1973,7 @@

    Catalog privileges

    <h4 id="callcontextresolver--realmcontextresolver">callContextResolver &amp; realmContextResolver</h4> <ul> <li>Use these configurations to specify a service that can resolve a realm from bearer tokens.</li> -<li>The service(s) used here must implement the relevant interfaces (i.e. <a href="https://github.com/polaris-catalog/polaris/blob/8290019c10290a600e40b35ddb1e2f54bf99e120/polaris-service/src/main/java/io/polaris/service/context/CallContextResolver.java#L27">CallContextResolver</a> and <a href="https://github.com/polaris-catalog/polaris/blob/7ce86f10a68a3b56aed766235c88d6027c0de038/polaris-service/src/main/java/io/polaris/service/context/RealmContextResolver.java">RealmContextResolver</a>).</li> +<li>The service(s) used here must implement the relevant interfaces (i.e. <a href="https://github.com/apache/polaris/blob/8290019c10290a600e40b35ddb1e2f54bf99e120/polaris-service/src/main/java/io/polaris/service/context/CallContextResolver.java#L27">CallContextResolver</a> and <a href="https://github.com/apache/polaris/blob/7ce86f10a68a3b56aed766235c88d6027c0de038/polaris-service/src/main/java/io/polaris/service/context/RealmContextResolver.java">RealmContextResolver</a>).</li> </ul> ">

    Configurations

    Notable configuration used to secure a Polaris deployment are outlined below.

    @@ -1983,7 +1983,7 @@

    oauth2

    • Configure OAuth with this setting. Remove the TestInlineBearerTokenPolarisAuthenticator option and uncomment the DefaultPolarisAuthenticator authenticator option beneath it.
      • -
    • Then, configure the token broker. You can configure the token broker to use either asymmetric or symmetric keys.
      • +
    • Then, configure the token broker. You can configure the token broker to use either asymmetric or symmetric keys.

    authenticator.tokenBroker

    @@ -1992,39 +1992,39 @@

    authenticator.tokenBroker

    callContextResolver & realmContextResolver

    -

    Metastore Management

    Metastore Management

    [!IMPORTANT]
    The default in-memory implementation for metastoreManager is meant for testing and not suitable for production usage. Instead, consider an implementation such as eclipse-link which allows you to store metadata in a remote database.

    -

    A Metastore Manger should be configured with an implementation that durably persists Polaris entities. Use the configuration metaStoreManager to configure a MetastoreManager implementation where Polaris entities will be persisted.

    +

    A Metastore Manger should be configured with an implementation that durably persists Polaris entities. Use the configuration metaStoreManager to configure a MetastoreManager implementation where Polaris entities will be persisted.

    Be sure to secure your metastore backend since it will be storing credentials and catalog metadata.

    To use EclipseLink for metastore management, specify the configuration metaStoreManager.conf-file to point to an EclipseLink persistence.xml file. This file, local to the Polaris service, will contain information on what database to use for metastore management and how to connect to it.

    Bootstrapping

    Before using Polaris when using a metastore manager other than in-memory, you must bootstrap the metastore manager. This is a manual operation that must be performed only once in order to prepare the metastore manager to integrate with Polaris. When the metastore manager is bootstrapped, any existing Polaris entities in the metastore manager may be purged.

    To bootstrap Polaris, run:

    -
    java -jar /path/to/jar/polaris-service-1.0.0-all.jar bootstrap polaris-server.yml
+
    java -jar /path/to/jar/polaris-service-all.jar bootstrap polaris-server.yml
 
    
 
    Afterwards, Polaris can be launched normally:
    
-
    java -jar /path/to/jar/polaris-service-1.0.0-all.jar server polaris-server.yml
+
    java -jar /path/to/jar/polaris-service-all.jar server polaris-server.yml
 
    
-

    Other Configurations

    Other Configurations

    featureConfiguratio
  • By default Polaris catalogs are allowed to be located in local filesystem with the FILE storage type. This should be disabled for production systems.
  • Use this configuration to additionally disable any other storage types that will not be in use.
    • -

    other

    listCatalogs

    List all catalogs in this polaris service

    -
    Authorizations:
    Polaris_Management_Service_OAuth2

    Responses

    Response samples

    Content type
    application/json
    {
    • "catalogs": [
      ]
    }

    createCatalog

    Add a new Catalog

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    Request Body schema: application/json
    required

    The Catalog to create

    -
    required
    object (Polaris_Management_Service_Catalog)

    A catalog object. A catalog may be internal or external. Internal catalogs are managed entirely by an external catalog interface. Third party catalogs may be other Iceberg REST implementations or other services with their own proprietary APIs

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "catalog": {
      }
    }

    getCatalog

    Get the details of a catalog

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog

    -

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "type": "INTERNAL",
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0,
    • "storageConfigInfo": {
      }
    }

    updateCatalog

    Update an existing catalog

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog

    -
    Request Body schema: application/json
    required

    The catalog details to use in the update

    -
    currentEntityVersion
    integer

    The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.

    -
    object
    object (Polaris_Management_Service_StorageConfigInfo)

    A storage configuration used by catalogs

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "currentEntityVersion": 0,
    • "properties": {
      },
    • "storageConfigInfo": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "type": "INTERNAL",
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0,
    • "storageConfigInfo": {
      }
    }

    deleteCatalog

    Delete an existing catalog. This is a cascading operation that deletes all metadata, including principals, roles and grants. If the catalog is an internal catalog, all tables and namespaces are dropped without purge.

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog

    -

    Responses

    listPrincipals

    List the principals for the current catalog

    -
    Authorizations:
    Polaris_Management_Service_OAuth2

    Responses

    Response samples

    Content type
    application/json
    {
    • "principals": [
      ]
    }

    createPrincipal

    Create a principal

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    Request Body schema: application/json
    required

    The principal to create

    -
    object (Polaris_Management_Service_Principal)

    A Polaris principal.

    -
    credentialRotationRequired
    boolean

    If true, the initial credentials can only be used to call rotateCredentials

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "principal": {
      },
    • "credentialRotationRequired": true
    }

    Response samples

    Content type
    application/json
    {
    • "principal": {
      },
    • "credentials": {
      }
    }

    getPrincipal

    Get the principal details

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal name

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "clientId": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    updatePrincipal

    Update an existing principal

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal name

    -
    Request Body schema: application/json
    required

    The principal details to use in the update

    -
    currentEntityVersion
    required
    integer

    The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.

    -
    required
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "currentEntityVersion": 0,
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "clientId": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    deletePrincipal

    Remove a principal from polaris

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal name

    -

    Responses

    rotateCredentials

    Rotate a principal's credentials. The new credentials will be returned in the response. This is the only API, aside from createPrincipal, that returns the user's credentials. This API is not idempotent.

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The user name

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "principal": {
      },
    • "credentials": {
      }
    }

    listPrincipalRolesAssigned

    List the roles assigned to the principal

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the target principal

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    assignPrincipalRole

    Add a role to the principal

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the target principal

    -
    Request Body schema: application/json
    required

    The principal role to assign

    -
    object (Polaris_Management_Service_PrincipalRole)

    Responses

    Request samples

    Content type
    application/json
    {
    • "principalRole": {
      }
    }

    revokePrincipalRole

    Remove a role from a catalog principal

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the target principal

    -
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role

    -

    Responses

    listPrincipalRoles

    List the principal roles

    -
    Authorizations:
    Polaris_Management_Service_OAuth2

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    createPrincipalRole

    Create a principal role

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    Request Body schema: application/json
    required

    The principal to create

    -
    object (Polaris_Management_Service_PrincipalRole)

    Responses

    Request samples

    Content type
    application/json
    {
    • "principalRole": {
      }
    }

    getPrincipalRole

    Get the principal role details

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    updatePrincipalRole

    Update an existing principalRole

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    -
    Request Body schema: application/json
    required

    The principalRole details to use in the update

    -
    currentEntityVersion
    required
    integer

    The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.

    -
    required
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "currentEntityVersion": 0,
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    deletePrincipalRole

    Remove a principal role from polaris

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    -

    Responses

    listAssigneePrincipalsForPrincipalRole

    List the Principals to whom the target principal role has been assigned

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "principals": [
      ]
    }

    listCatalogRolesForPrincipalRole

    Get the catalog roles mapped to the principal role

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    -
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the catalogRoles reside

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    assignCatalogRoleToPrincipalRole

    Assign a catalog role to a principal role

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    -
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the catalogRoles reside

    -
    Request Body schema: application/json
    required

    The principal to create

    -
    object (Polaris_Management_Service_CatalogRole)

    Responses

    Request samples

    Content type
    application/json
    {
    • "catalogRole": {
      }
    }

    revokeCatalogRoleFromPrincipalRole

    Remove a catalog role from a principal role

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    -
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog that contains the role to revoke

    -
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog role that should be revoked

    -

    Responses

    listCatalogRoles

    List existing roles in the catalog

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are reading/updating roles

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    createCatalogRole

    Create a new role in the catalog

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are reading/updating roles

    -
    Request Body schema: application/json
    object (Polaris_Management_Service_CatalogRole)

    Responses

    Request samples

    Content type
    application/json
    {
    • "catalogRole": {
      }
    }

    getCatalogRole

    Get the details of an existing role

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are retrieving roles

    -
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    updateCatalogRole

    Update an existing role in the catalog

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are retrieving roles

    -
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role

    -
    Request Body schema: application/json
    currentEntityVersion
    required
    integer

    The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.

    -
    required
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "currentEntityVersion": 0,
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    deleteCatalogRole

    Delete an existing role from the catalog. All associated grants will also be deleted

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are retrieving roles

    -
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role

    -

    Responses

    listAssigneePrincipalRolesForCatalogRole

    List the PrincipalRoles to which the target catalog role has been assigned

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the catalog role resides

    -
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog role

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    listGrantsForCatalogRole

    List the grants the catalog role holds

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the role will receive the grant

    -
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role receiving the grant (must exist)

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "grants": [
      ]
    }

    addGrantToCatalogRole

    Add a new grant to the catalog role

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the role will receive the grant

    -
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role receiving the grant (must exist)

    -
    Request Body schema: application/json
    object (Polaris_Management_Service_GrantResource)

    Responses

    Request samples

    Content type
    application/json
    {
    • "grant": {
      }
    }

    revokeGrantFromCatalogRole

    Delete a specific grant from the role. This may be a subset or a superset of the grants the role has. In case of a subset, the role will retain the grants not specified. If the cascade parameter is true, grant revocation will have a cascading effect - that is, if a principal has specific grants on a subresource, and grants are revoked on a parent resource, the grants present on the subresource will be revoked as well. By default, this behavior is disabled and grant revocation only affects the specified resource.

    -
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the role will receive the grant

    -
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role receiving the grant (must exist)

    -
    query Parameters
    cascade
    boolean
    Default: false

    If true, the grant revocation cascades to all subresources.

    -
    Request Body schema: application/json
    object (Polaris_Management_Service_GrantResource)

    Responses

    Request samples

    Content type
    application/json
    {
    • "grant": {
      }
    }

    Configuration API

    List all catalog configuration settings

    other

    listCatalogs

    List all catalogs in this polaris service

    +
    Authorizations:
    Polaris_Management_Service_OAuth2

    Responses

    Response samples

    Content type
    application/json
    {
    • "catalogs": [
      ]
    }

    createCatalog

    Add a new Catalog

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    Request Body schema: application/json
    required

    The Catalog to create

    +
    required
    object (Polaris_Management_Service_Catalog)

    A catalog object. A catalog may be internal or external. Internal catalogs are managed entirely by an external catalog interface. Third party catalogs may be other Iceberg REST implementations or other services with their own proprietary APIs

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "catalog": {
      }
    }

    getCatalog

    Get the details of a catalog

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog

    +

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "type": "INTERNAL",
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0,
    • "storageConfigInfo": {
      }
    }

    updateCatalog

    Update an existing catalog

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog

    +
    Request Body schema: application/json
    required

    The catalog details to use in the update

    +
    currentEntityVersion
    integer

    The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.

    +
    object
    object (Polaris_Management_Service_StorageConfigInfo)

    A storage configuration used by catalogs

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "currentEntityVersion": 0,
    • "properties": {
      },
    • "storageConfigInfo": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "type": "INTERNAL",
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0,
    • "storageConfigInfo": {
      }
    }

    deleteCatalog

    Delete an existing catalog. This is a cascading operation that deletes all metadata, including principals, roles and grants. If the catalog is an internal catalog, all tables and namespaces are dropped without purge.

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog

    +

    Responses

    listPrincipals

    List the principals for the current catalog

    +
    Authorizations:
    Polaris_Management_Service_OAuth2

    Responses

    Response samples

    Content type
    application/json
    {
    • "principals": [
      ]
    }

    createPrincipal

    Create a principal

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    Request Body schema: application/json
    required

    The principal to create

    +
    object (Polaris_Management_Service_Principal)

    A Polaris principal.

    +
    credentialRotationRequired
    boolean

    If true, the initial credentials can only be used to call rotateCredentials

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "principal": {
      },
    • "credentialRotationRequired": true
    }

    Response samples

    Content type
    application/json
    {
    • "principal": {
      },
    • "credentials": {
      }
    }

    getPrincipal

    Get the principal details

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal name

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "clientId": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    updatePrincipal

    Update an existing principal

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal name

    +
    Request Body schema: application/json
    required

    The principal details to use in the update

    +
    currentEntityVersion
    required
    integer

    The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.

    +
    required
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "currentEntityVersion": 0,
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "clientId": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    deletePrincipal

    Remove a principal from polaris

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal name

    +

    Responses

    rotateCredentials

    Rotate a principal's credentials. The new credentials will be returned in the response. This is the only API, aside from createPrincipal, that returns the user's credentials. This API is not idempotent.

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The user name

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "principal": {
      },
    • "credentials": {
      }
    }

    listPrincipalRolesAssigned

    List the roles assigned to the principal

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the target principal

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    assignPrincipalRole

    Add a role to the principal

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the target principal

    +
    Request Body schema: application/json
    required

    The principal role to assign

    +
    object (Polaris_Management_Service_PrincipalRole)

    Responses

    Request samples

    Content type
    application/json
    {
    • "principalRole": {
      }
    }

    revokePrincipalRole

    Remove a role from a catalog principal

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the target principal

    +
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role

    +

    Responses

    listPrincipalRoles

    List the principal roles

    +
    Authorizations:
    Polaris_Management_Service_OAuth2

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    createPrincipalRole

    Create a principal role

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    Request Body schema: application/json
    required

    The principal to create

    +
    object (Polaris_Management_Service_PrincipalRole)

    Responses

    Request samples

    Content type
    application/json
    {
    • "principalRole": {
      }
    }

    getPrincipalRole

    Get the principal role details

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    updatePrincipalRole

    Update an existing principalRole

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    +
    Request Body schema: application/json
    required

    The principalRole details to use in the update

    +
    currentEntityVersion
    required
    integer

    The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.

    +
    required
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "currentEntityVersion": 0,
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    deletePrincipalRole

    Remove a principal role from polaris

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    +

    Responses

    listAssigneePrincipalsForPrincipalRole

    List the Principals to whom the target principal role has been assigned

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "principals": [
      ]
    }

    listCatalogRolesForPrincipalRole

    Get the catalog roles mapped to the principal role

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    +
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the catalogRoles reside

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    assignCatalogRoleToPrincipalRole

    Assign a catalog role to a principal role

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    +
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the catalogRoles reside

    +
    Request Body schema: application/json
    required

    The principal to create

    +
    object (Polaris_Management_Service_CatalogRole)

    Responses

    Request samples

    Content type
    application/json
    {
    • "catalogRole": {
      }
    }

    revokeCatalogRoleFromPrincipalRole

    Remove a catalog role from a principal role

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    principalRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The principal role name

    +
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog that contains the role to revoke

    +
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog role that should be revoked

    +

    Responses

    listCatalogRoles

    List existing roles in the catalog

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are reading/updating roles

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    createCatalogRole

    Create a new role in the catalog

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are reading/updating roles

    +
    Request Body schema: application/json
    object (Polaris_Management_Service_CatalogRole)

    Responses

    Request samples

    Content type
    application/json
    {
    • "catalogRole": {
      }
    }

    getCatalogRole

    Get the details of an existing role

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are retrieving roles

    +
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    updateCatalogRole

    Update an existing role in the catalog

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are retrieving roles

    +
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role

    +
    Request Body schema: application/json
    currentEntityVersion
    required
    integer

    The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.

    +
    required
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "currentEntityVersion": 0,
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "name": "string",
    • "properties": {
      },
    • "createTimestamp": 0,
    • "lastUpdateTimestamp": 0,
    • "entityVersion": 0
    }

    deleteCatalogRole

    Delete an existing role from the catalog. All associated grants will also be deleted

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The catalog for which we are retrieving roles

    +
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role

    +

    Responses

    listAssigneePrincipalRolesForCatalogRole

    List the PrincipalRoles to which the target catalog role has been assigned

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the catalog role resides

    +
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog role

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    listGrantsForCatalogRole

    List the grants the catalog role holds

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the role will receive the grant

    +
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role receiving the grant (must exist)

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "grants": [
      ]
    }

    addGrantToCatalogRole

    Add a new grant to the catalog role

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the role will receive the grant

    +
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role receiving the grant (must exist)

    +
    Request Body schema: application/json
    object (Polaris_Management_Service_GrantResource)

    Responses

    Request samples

    Content type
    application/json
    {
    • "grant": {
      }
    }

    revokeGrantFromCatalogRole

    Delete a specific grant from the role. This may be a subset or a superset of the grants the role has. In case of a subset, the role will retain the grants not specified. If the cascade parameter is true, grant revocation will have a cascading effect - that is, if a principal has specific grants on a subresource, and grants are revoked on a parent resource, the grants present on the subresource will be revoked as well. By default, this behavior is disabled and grant revocation only affects the specified resource.

    +
    Authorizations:
    Polaris_Management_Service_OAuth2
    path Parameters
    catalogName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the catalog where the role will receive the grant

    +
    catalogRoleName
    required
    string [ 1 .. 256 ] characters ^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$

    The name of the role receiving the grant (must exist)

    +
    query Parameters
    cascade
    boolean
    Default: false

    If true, the grant revocation cascades to all subresources.

    +
    Request Body schema: application/json
    object (Polaris_Management_Service_GrantResource)

    Responses

    Request samples

    Content type
    application/json
    {
    • "grant": {
      }
    }

    Configuration API

    List all catalog configuration settings

    featureConfiguratio <p>Catalog configuration is constructed by setting the defaults, then client- provided configuration, and finally overrides. The final property set is then used to configure the catalog.</p> <p>For example, a default configuration property might set the size of the client pool, which can be replaced with a client-specific setting. An override might be used to set the warehouse location, which is stored on the server rather than in client configuration.</p> <p>Common catalog configuration settings are documented at <a href="https://iceberg.apache.org/docs/latest/configuration/#catalog-properties">https://iceberg.apache.org/docs/latest/configuration/#catalog-properties</a> </p> -" class="sc-eeDSqt sc-eBMFzZ bSgSrX cWARBq">

    All REST clients should first call this route to get catalog configuration properties from the server to configure the catalog and its HTTP client. Configuration from the server consists of two sets of key/value pairs.

    +" class="sc-euGpHm sc-exayXG fwfkcU kqJXdD">

    All REST clients should first call this route to get catalog configuration properties from the server to configure the catalog and its HTTP client. Configuration from the server consists of two sets of key/value pairs.

    • defaults - properties that should be used as default configuration; applied before client configuration
    • overrides - properties that should be used to override client configuration; applied after defaults and client configuration
      • @@ -2604,31 +2604,31 @@

      featureConfiguratio

      Catalog configuration is constructed by setting the defaults, then client- provided configuration, and finally overrides. The final property set is then used to configure the catalog.

      For example, a default configuration property might set the size of the client pool, which can be replaced with a client-specific setting. An override might be used to set the warehouse location, which is stored on the server rather than in client configuration.

      Common catalog configuration settings are documented at https://iceberg.apache.org/docs/latest/configuration/#catalog-properties

      -

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    query Parameters
    warehouse
    string

    Warehouse location or identifier to request from the service

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "overrides": {
      },
    • "defaults": {
      }
    }

    OAuth2 API

    Get a token using an OAuth2 flow

    5XX

    A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

    +

    Response samples

    Content type
    application/json
    {
    • "overrides": {
      },
    • "defaults": {
      }
    }

    OAuth2 API

    Get a token using an OAuth2 flow

    featureConfiguratio <p>For example, a catalog client may be configured with client credentials from the OAuth2 Authorization flow. This client would exchange its client ID and secret for an access token using the client credentials request with this endpoint (1). Subsequent requests would then use that access token.</p> <p>Some clients may also handle sessions that have additional user context. These clients would use the token exchange flow to exchange a user token (the &quot;subject&quot; token) from the session for a more specific access token for that user, using the catalog&#39;s access token as the &quot;actor&quot; token (2). The user ID token is the &quot;subject&quot; token and can be any token type allowed by the OAuth2 token exchange flow, including a unsecured JWT token with a sub claim. This request should use the catalog&#39;s bearer token in the &quot;Authorization&quot; header.</p> <p>Clients may also use the token exchange flow to refresh a token that is about to expire by sending a token exchange request (3). The request&#39;s &quot;subject&quot; token should be the expiring token. This request should use the subject token in the &quot;Authorization&quot; header.</p> -" class="sc-eeDSqt sc-eBMFzZ bSgSrX cWARBq">

    Exchange credentials for a token using the OAuth2 client credentials flow or token exchange.

    +" class="sc-euGpHm sc-exayXG fwfkcU kqJXdD">

    Exchange credentials for a token using the OAuth2 client credentials flow or token exchange.

    This endpoint is used for three purposes -

    1. To exchange client credentials (client ID and secret) for an access token This uses the client credentials flow.
      2. @@ -2648,897 +2648,897 @@

      featureConfiguratio

      For example, a catalog client may be configured with client credentials from the OAuth2 Authorization flow. This client would exchange its client ID and secret for an access token using the client credentials request with this endpoint (1). Subsequent requests would then use that access token.

      Some clients may also handle sessions that have additional user context. These clients would use the token exchange flow to exchange a user token (the "subject" token) from the session for a more specific access token for that user, using the catalog's access token as the "actor" token (2). The user ID token is the "subject" token and can be any token type allowed by the OAuth2 token exchange flow, including a unsecured JWT token with a sub claim. This request should use the catalog's bearer token in the "Authorization" header.

      Clients may also use the token exchange flow to refresh a token that is about to expire by sending a token exchange request (3). The request's "subject" token should be the expiring token. This request should use the subject token in the "Authorization" header.

      -

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_BearerAuth
    header Parameters
    Authorization
    string
    Request Body schema: application/x-www-form-urlencoded
    required
    Any of
    grant_type
    required
    string
    Value: "client_credentials"
    scope
    string
    client_id
    required
    string
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_BearerAuth
    header Parameters
    Authorization
    string
    Request Body schema: application/x-www-form-urlencoded
    required
    Any of
    grant_type
    required
    string
    Value: "client_credentials"
    scope
    string
    client_id
    required
    string

    Client ID

    +" class="sc-euGpHm sc-exayXG fwfkcU jYGAQp">

    Client ID

    This can be sent in the request body, but OAuth2 recommends sending it in a Basic Authorization header.

    -
    client_secret
    required
    string
    		client_secret
    required
    string

    Client secret

    +" class="sc-euGpHm sc-exayXG fwfkcU jYGAQp">

    Client secret

    This can be sent in the request body, but OAuth2 recommends sending it in a Basic Authorization header.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "access_token": "string",
    • "token_type": "bearer",
    • "expires_in": 0,
    • "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
    • "refresh_token": "string",
    • "scope": "string"
    }

    Catalog API

    List namespaces, optionally providing a parent namespace to list underneath

    List all namespaces at a certain level, optionally starting from a given parent namespace. If table accounting.tax.paid.info exists, using 'SELECT NAMESPACE IN accounting' would translate into GET /namespaces?parent=accounting and must return a namespace, ["accounting", "tax"] only. Using 'SELECT NAMESPACE IN accounting.tax' would translate into GET /namespaces?parent=accounting%1Ftax and must return a namespace, ["accounting", "tax", "paid"]. If parent is not provided, all top-level namespaces should be listed.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    query Parameters
    pageToken
    string or null (Apache_Iceberg_REST_Catalog_API_PageToken)
    Responses

    Response samples

    Content type
    application/json
    {
    • "access_token": "string",
    • "token_type": "bearer",
    • "expires_in": 0,
    • "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
    • "refresh_token": "string",
    • "scope": "string"
    }

    Catalog API

    List namespaces, optionally providing a parent namespace to list underneath

    List all namespaces at a certain level, optionally starting from a given parent namespace. If table accounting.tax.paid.info exists, using 'SELECT NAMESPACE IN accounting' would translate into GET /namespaces?parent=accounting and must return a namespace, ["accounting", "tax"] only. Using 'SELECT NAMESPACE IN accounting.tax' would translate into GET /namespaces?parent=accounting%1Ftax and must return a namespace, ["accounting", "tax", "paid"]. If parent is not provided, all top-level namespaces should be listed.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    query Parameters
    pageToken
    string or null (Apache_Iceberg_REST_Catalog_API_PageToken)

    An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter pageToken to the server. +" class="sc-euGpHm sc-exayXG fwfkcU jYGAQp">

    An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter pageToken to the server. Servers that support pagination should identify the pageToken parameter and return a next-page-token in the response if there are more results available. After the initial request, the value of next-page-token from each response must be used as the pageToken parameter value for the next request. The server must return null value for the next-page-token in the last response. Servers that support pagination must return all results in a single response with the value of next-page-token set to null if the query parameter pageToken is not set in the request. Servers that do not support pagination should ignore the pageToken parameter and return all results in a single response. The next-page-token must be omitted from the response. Clients must interpret either null or missing response value of next-page-token as the end of the listing results.

    -
    pageSize
    integer >= 1

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    -
    parent
    string
    Example: parent=accounting%1Ftax

    An optional namespace, underneath which to list namespaces. If not provided or empty, all top-level namespaces should be listed. If parent is a multipart namespace, the parts must be separated by the unit separator (0x1F) byte.

    -

    Responses

    		pageSize
    integer >= 1

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    +
    parent
    string
    Example: parent=accounting%1Ftax

    An optional namespace, underneath which to list namespaces. If not provided or empty, all top-level namespaces should be listed. If parent is a multipart namespace, the parts must be separated by the unit separator (0x1F) byte.

    +

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "namespaces": [
      ]
    }

    Create a namespace

    Create a namespace, with an optional set of properties. The server might also add properties, such as last_modified_time etc.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    Request Body schema: application/json
    required
    namespace
    required
    Array of strings (Apache_Iceberg_REST_Catalog_API_Namespace)

    Reference to one or more levels of a namespace

    -
    object
    Default: {}

    Configured string to string map of properties for the namespace

    -

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "namespaces": [
      ]
    }

    Create a namespace

    Create a namespace, with an optional set of properties. The server might also add properties, such as last_modified_time etc.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    Request Body schema: application/json
    required
    namespace
    required
    Array of strings (Apache_Iceberg_REST_Catalog_API_Namespace)

    Reference to one or more levels of a namespace

    +
    object
    Default: {}

    Configured string to string map of properties for the namespace

    +

    Responses

    Request samples

    Content type
    application/json
    {
    • "namespace": [
      ],
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "namespace": [
      ],
    • "properties": {
      }
    }

    Load the metadata properties for a namespace

    Return all stored metadata properties for a given namespace

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "namespace": [
      ],
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "namespace": [
      ],
    • "properties": {
      }
    }

    Load the metadata properties for a namespace

    Return all stored metadata properties for a given namespace

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "namespace": [
      ],
    • "properties": {
      }
    }

    Check if a namespace exists

    Check if a namespace exists. The response does not contain a body.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "namespace": [
      ],
    • "properties": {
      }
    }

    Check if a namespace exists

    Check if a namespace exists. The response does not contain a body.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Drop a namespace from the catalog. Namespace must be empty.

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Drop a namespace from the catalog. Namespace must be empty.

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Set or remove properties on a namespace

    5XX

    A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

    +

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Set or remove properties on a namespace

    Set and/or remove properties on a namespace. The request body specifies a list of properties to remove and a map of key value pairs to update. +" class="sc-euGpHm sc-exayXG fwfkcU kqJXdD">

    Set and/or remove properties on a namespace. The request body specifies a list of properties to remove and a map of key value pairs to update. Properties that are not in the request are not modified or removed by this call. Server implementations are not required to support namespace properties.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    Request Body schema: application/json
    required
    removals
    Array of strings unique
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "removals": [
      ],
    • "updates": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "updated": [
      ],
    • "removed": [
      ],
    • "missing": [
      ]
    }

    List all table identifiers underneath a given namespace

    Return all table identifiers under this namespace

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    query Parameters
    pageToken
    string or null (Apache_Iceberg_REST_Catalog_API_PageToken)
    5XX

    A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

    +

    Request samples

    Content type
    application/json
    {
    • "removals": [
      ],
    • "updates": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "updated": [
      ],
    • "removed": [
      ],
    • "missing": [
      ]
    }

    List all table identifiers underneath a given namespace

    Return all table identifiers under this namespace

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    query Parameters
    pageToken
    string or null (Apache_Iceberg_REST_Catalog_API_PageToken)

    An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter pageToken to the server. +" class="sc-euGpHm sc-exayXG fwfkcU jYGAQp">

    An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter pageToken to the server. Servers that support pagination should identify the pageToken parameter and return a next-page-token in the response if there are more results available. After the initial request, the value of next-page-token from each response must be used as the pageToken parameter value for the next request. The server must return null value for the next-page-token in the last response. Servers that support pagination must return all results in a single response with the value of next-page-token set to null if the query parameter pageToken is not set in the request. Servers that do not support pagination should ignore the pageToken parameter and return all results in a single response. The next-page-token must be omitted from the response. Clients must interpret either null or missing response value of next-page-token as the end of the listing results.

    -
    pageSize
    integer >= 1

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    -

    Responses

    		pageSize
    integer >= 1

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    +

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "identifiers": [
      ]
    }

    Create a table in the given namespace

    5XX

    A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

    +

    Response samples

    Content type
    application/json
    Example
    {
    • "identifiers": [
      ]
    }

    Create a table in the given namespace

    Create a table or start a create transaction, like atomic CTAS.

    +" class="sc-euGpHm sc-exayXG fwfkcU kqJXdD">

    Create a table or start a create transaction, like atomic CTAS.

    If stage-create is false, the table is created immediately.

    If stage-create is true, the table is not created, but table metadata is initialized and returned. The service should prepare as needed for a commit to the table commit endpoint to complete the create transaction. The client uses the returned metadata to begin a transaction. To commit the transaction, the client sends all create and subsequent changes to the table commit route. Changes from the table create operation include changes like AddSchemaUpdate and SetCurrentSchemaUpdate that set the initial table state.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    header Parameters
    X-Iceberg-Access-Delegation
    string
    Enum: "vended-credentials" "remote-signing"
    Example: vended-credentials,remote-signing
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    header Parameters
    X-Iceberg-Access-Delegation
    string
    Enum: "vended-credentials" "remote-signing"
    Example: vended-credentials,remote-signing

    Optional signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms.

    +" class="sc-euGpHm sc-exayXG fwfkcU jYGAQp">

    Optional signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms.

    Specific properties and handling for vended-credentials is documented in the LoadTableResult schema section of this spec document.

    The protocol and specification for remote-signing is documented in the s3-signer-open-api.yaml OpenApi spec in the aws module.

    -
    Request Body schema: application/json
    required
    name
    required
    string
    location
    string
    required
    object (Apache_Iceberg_REST_Catalog_API_Schema)
    object (Apache_Iceberg_REST_Catalog_API_PartitionSpec)
    object (Apache_Iceberg_REST_Catalog_API_SortOrder)
    stage-create
    boolean
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "location": "string",
    • "schema": {
      },
    • "partition-spec": {
      },
    • "write-order": {
      },
    • "stage-create": true,
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Register a table in the given namespace using given metadata file location

    Register a table using given metadata file location.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    Request Body schema: application/json
    required
    name
    required
    string
    metadata-location
    required
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "location": "string",
    • "schema": {
      },
    • "partition-spec": {
      },
    • "write-order": {
      },
    • "stage-create": true,
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Register a table in the given namespace using given metadata file location

    Register a table using given metadata file location.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    Request Body schema: application/json
    required
    name
    required
    string
    metadata-location
    required
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "metadata-location": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Load a table from the catalog

    5XX

    A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

    +

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "metadata-location": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Load a table from the catalog

    Load a table from the catalog.

    +" class="sc-euGpHm sc-exayXG fwfkcU kqJXdD">

    Load a table from the catalog.

    The response contains both configuration and table metadata. The configuration, if non-empty is used as additional configuration for the table that overrides catalog configuration. For example, this configuration may change the FileIO implementation to be used for the table.

    The response also contains the table's full metadata, matching the table metadata JSON file.

    The catalog configuration may contain credentials that should be used for subsequent requests for the table. The configuration key "token" is used to pass an access token to be used as a bearer token for table requests. Otherwise, a token may be passed using a RFC 8693 token type as a configuration key. For example, "urn:ietf:params:oauth:token-type:jwt=".

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    table
    required
    string
    Example: sales

    A table name

    -
    query Parameters
    snapshots
    string
    Enum: "all" "refs"
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    table
    required
    string
    Example: sales

    A table name

    +
    query Parameters
    snapshots
    string
    Enum: "all" "refs"

    The snapshots to return in the body of the metadata. Setting the value to all would return the full set of snapshots currently valid for the table. Setting the value to refs would load all snapshots referenced by branches or tags. +" class="sc-euGpHm sc-exayXG fwfkcU jYGAQp">

    The snapshots to return in the body of the metadata. Setting the value to all would return the full set of snapshots currently valid for the table. Setting the value to refs would load all snapshots referenced by branches or tags. Default if no param is provided is all.

    -
    header Parameters
    X-Iceberg-Access-Delegation
    string
    Enum: "vended-credentials" "remote-signing"
    Example: vended-credentials,remote-signing
    header Parameters
    X-Iceberg-Access-Delegation
    string
    Enum: "vended-credentials" "remote-signing"
    Example: vended-credentials,remote-signing

    Optional signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms.

    +" class="sc-euGpHm sc-exayXG fwfkcU jYGAQp">

    Optional signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms.

    Specific properties and handling for vended-credentials is documented in the LoadTableResult schema section of this spec document.

    The protocol and specification for remote-signing is documented in the s3-signer-open-api.yaml OpenApi spec in the aws module.

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Commit updates to a table

    5XX

    A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

    +

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Commit updates to a table

    Commit updates to a table.

    +" class="sc-euGpHm sc-exayXG fwfkcU kqJXdD">

    Commit updates to a table.

    Commits have two parts, requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, assert-ref-snapshot-id will check that a named ref's snapshot ID has a certain value.

    Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id.

    Create table transactions that are started by createTable with stage-create set to true are committed using this route. Transactions should include all changes to the table, including table initialization, like AddSchemaUpdate and SetCurrentSchemaUpdate. The assert-create requirement is used to ensure that the table was not created concurrently.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    table
    required
    string
    Example: sales

    A table name

    -
    Request Body schema: application/json
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)
    required
    Array of objects (Apache_Iceberg_REST_Catalog_API_TableRequirement)
    required
    Array of Apache_Iceberg_REST_Catalog_API_AssignUUIDUpdate (object) or Apache_Iceberg_REST_Catalog_API_UpgradeFormatVersionUpdate (object) or Apache_Iceberg_REST_Catalog_API_AddSchemaUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetCurrentSchemaUpdate (object) or Apache_Iceberg_REST_Catalog_API_AddPartitionSpecUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetDefaultSpecUpdate (object) or Apache_Iceberg_REST_Catalog_API_AddSortOrderUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetDefaultSortOrderUpdate (object) or Apache_Iceberg_REST_Catalog_API_AddSnapshotUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetSnapshotRefUpdate (object) or Apache_Iceberg_REST_Catalog_API_RemoveSnapshotsUpdate (object) or Apache_Iceberg_REST_Catalog_API_RemoveSnapshotRefUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetLocationUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetPropertiesUpdate (object) or Apache_Iceberg_REST_Catalog_API_RemovePropertiesUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetStatisticsUpdate (object) or Apache_Iceberg_REST_Catalog_API_RemoveStatisticsUpdate (object) (Apache_Iceberg_REST_Catalog_API_TableUpdate)

    Responses

    Request samples

    Content type
    application/json
    {
    • "identifier": {
      },
    • "requirements": [
      ],
    • "updates": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      }
    }

    Drop a table from the catalog

    Remove a table from the catalog

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    table
    required
    string
    Example: sales

    A table name

    -
    query Parameters
    purgeRequested
    boolean
    Default: false

    Whether the user requested to purge the underlying table's data and metadata

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "identifier": {
      },
    • "requirements": [
      ],
    • "updates": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      }
    }

    Drop a table from the catalog

    Remove a table from the catalog

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    table
    required
    string
    Example: sales

    A table name

    +
    query Parameters
    purgeRequested
    boolean
    Default: false

    Whether the user requested to purge the underlying table's data and metadata

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Check if a table exists

    Check if a table exists within a given namespace. The response does not contain a body.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    table
    required
    string
    Example: sales

    A table name

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Check if a table exists

    Check if a table exists within a given namespace. The response does not contain a body.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    table
    required
    string
    Example: sales

    A table name

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Rename a table from its current name to a new name

    Rename a table from one identifier to another. It's valid to move a table across namespaces, but the server implementation is not required to support it.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    Request Body schema: application/json
    required

    Current table identifier to rename and new table identifier to rename to

    -
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Rename a table from its current name to a new name

    Rename a table from one identifier to another. It's valid to move a table across namespaces, but the server implementation is not required to support it.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    Request Body schema: application/json
    required

    Current table identifier to rename and new table identifier to rename to

    +
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)

    Responses

    Request samples

    Content type
    application/json
    {
    • "source": {
      },
    • "destination": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Send a metrics report to this endpoint to be processed by the backend

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    table
    required
    string
    Example: sales

    A table name

    -
    Request Body schema: application/json
    required

    The request containing the metrics report to be sent

    -
    Any of
    table-name
    required
    string
    snapshot-id
    required
    integer <int64>
    required
    Apache_Iceberg_REST_Catalog_API_AndOrExpression (object) or Apache_Iceberg_REST_Catalog_API_NotExpression (object) or Apache_Iceberg_REST_Catalog_API_SetExpression (object) or Apache_Iceberg_REST_Catalog_API_LiteralExpression (object) or Apache_Iceberg_REST_Catalog_API_UnaryExpression (object) (Apache_Iceberg_REST_Catalog_API_Expression)
    schema-id
    required
    integer
    projected-field-ids
    required
    Array of integers
    projected-field-names
    required
    Array of strings
    required
    object (Apache_Iceberg_REST_Catalog_API_Metrics)
    object
    report-type
    required
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "source": {
      },
    • "destination": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Send a metrics report to this endpoint to be processed by the backend

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    table
    required
    string
    Example: sales

    A table name

    +
    Request Body schema: application/json
    required

    The request containing the metrics report to be sent

    +
    Any of
    table-name
    required
    string
    snapshot-id
    required
    integer <int64>
    required
    Apache_Iceberg_REST_Catalog_API_AndOrExpression (object) or Apache_Iceberg_REST_Catalog_API_NotExpression (object) or Apache_Iceberg_REST_Catalog_API_SetExpression (object) or Apache_Iceberg_REST_Catalog_API_LiteralExpression (object) or Apache_Iceberg_REST_Catalog_API_UnaryExpression (object) (Apache_Iceberg_REST_Catalog_API_Expression)
    schema-id
    required
    integer
    projected-field-ids
    required
    Array of integers
    projected-field-names
    required
    Array of strings
    required
    object (Apache_Iceberg_REST_Catalog_API_Metrics)
    object
    report-type
    required
    string

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "table-name": "string",
    • "snapshot-id": 0,
    • "filter": {
      },
    • "schema-id": 0,
    • "projected-field-ids": [
      ],
    • "projected-field-names": [
      ],
    • "metrics": {
      },
    • "metadata": {
      },
    • "report-type": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Sends a notification to the table

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    table
    required
    string
    Example: sales

    A table name

    -
    Request Body schema: application/json
    required

    The request containing the notification to be sent

    -
    notification-type
    required
    string (Apache_Iceberg_REST_Catalog_API_NotificationType)
    Enum: "UNKNOWN" "CREATE" "UPDATE" "DROP"
    object (Apache_Iceberg_REST_Catalog_API_TableUpdateNotification)

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "table-name": "string",
    • "snapshot-id": 0,
    • "filter": {
      },
    • "schema-id": 0,
    • "projected-field-ids": [
      ],
    • "projected-field-names": [
      ],
    • "metrics": {
      },
    • "metadata": {
      },
    • "report-type": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Sends a notification to the table

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    table
    required
    string
    Example: sales

    A table name

    +
    Request Body schema: application/json
    required

    The request containing the notification to be sent

    +
    notification-type
    required
    string (Apache_Iceberg_REST_Catalog_API_NotificationType)
    Enum: "UNKNOWN" "CREATE" "UPDATE" "DROP"
    object (Apache_Iceberg_REST_Catalog_API_TableUpdateNotification)

    Responses

    Request samples

    Content type
    application/json
    {
    • "notification-type": "UNKNOWN",
    • "payload": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Commit updates to multiple tables in an atomic operation

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    Request Body schema: application/json
    required
    5XX

    A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

    +

    Request samples

    Content type
    application/json
    {
    • "notification-type": "UNKNOWN",
    • "payload": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Commit updates to multiple tables in an atomic operation

    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    Request Body schema: application/json
    required

    Commit updates to multiple tables in an atomic operation

    +" class="sc-euGpHm sc-exayXG fwfkcU kqJXdD">

    Commit updates to multiple tables in an atomic operation

    A commit for a single table consists of a table identifier with requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, assert-ref-snapshot-id will check that a named ref's snapshot ID has a certain value.

    Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id.

    -
    required
    Array of objects (Apache_Iceberg_REST_Catalog_API_CommitTableRequest)

    Responses

    required
    Array of objects (Apache_Iceberg_REST_Catalog_API_CommitTableRequest)

    Responses

    Request samples

    Content type
    application/json
    {
    • "table-changes": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    List all view identifiers underneath a given namespace

    Return all view identifiers under this namespace

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    query Parameters
    pageToken
    string or null (Apache_Iceberg_REST_Catalog_API_PageToken)
    504

    A server-side gateway timeout occurred; the commit state is unknown.

    +

    Request samples

    Content type
    application/json
    {
    • "table-changes": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    List all view identifiers underneath a given namespace

    Return all view identifiers under this namespace

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    query Parameters
    pageToken
    string or null (Apache_Iceberg_REST_Catalog_API_PageToken)

    An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter pageToken to the server. +" class="sc-euGpHm sc-exayXG fwfkcU jYGAQp">

    An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter pageToken to the server. Servers that support pagination should identify the pageToken parameter and return a next-page-token in the response if there are more results available. After the initial request, the value of next-page-token from each response must be used as the pageToken parameter value for the next request. The server must return null value for the next-page-token in the last response. Servers that support pagination must return all results in a single response with the value of next-page-token set to null if the query parameter pageToken is not set in the request. Servers that do not support pagination should ignore the pageToken parameter and return all results in a single response. The next-page-token must be omitted from the response. Clients must interpret either null or missing response value of next-page-token as the end of the listing results.

    -
    pageSize
    integer >= 1

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    -

    Responses

    		pageSize
    integer >= 1

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    +

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "identifiers": [
      ]
    }

    Create a view in the given namespace

    Create a view in the given namespace.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    Request Body schema: application/json
    required
    name
    required
    string
    location
    string
    required
    object (Apache_Iceberg_REST_Catalog_API_Schema)
    required
    object (Apache_Iceberg_REST_Catalog_API_ViewVersion)
    required
    object

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "identifiers": [
      ]
    }

    Create a view in the given namespace

    Create a view in the given namespace.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    Request Body schema: application/json
    required
    name
    required
    string
    location
    string
    required
    object (Apache_Iceberg_REST_Catalog_API_Schema)
    required
    object (Apache_Iceberg_REST_Catalog_API_ViewVersion)
    required
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "location": "string",
    • "schema": {
      },
    • "view-version": {
      },
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Load a view from the catalog

    5XX

    A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

    +

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "location": "string",
    • "schema": {
      },
    • "view-version": {
      },
    • "properties": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Load a view from the catalog

    Load a view from the catalog.

    +" class="sc-euGpHm sc-exayXG fwfkcU kqJXdD">

    Load a view from the catalog.

    The response contains both configuration and view metadata. The configuration, if non-empty is used as additional configuration for the view that overrides catalog configuration.

    The response also contains the view's full metadata, matching the view metadata JSON file.

    The catalog configuration may contain credentials that should be used for subsequent requests for the view. The configuration key "token" is used to pass an access token to be used as a bearer token for view requests. Otherwise, a token may be passed using a RFC 8693 token type as a configuration key. For example, "urn:ietf:params:oauth:token-type:jwt=".

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    view
    required
    string
    Example: sales

    A view name

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Replace a view

    Commit updates to a view.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    view
    required
    string
    Example: sales

    A view name

    -
    Request Body schema: application/json
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)
    Array of objects (Apache_Iceberg_REST_Catalog_API_ViewRequirement)
    required
    Array of Apache_Iceberg_REST_Catalog_API_AssignUUIDUpdate (object) or Apache_Iceberg_REST_Catalog_API_UpgradeFormatVersionUpdate (object) or Apache_Iceberg_REST_Catalog_API_AddSchemaUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetLocationUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetPropertiesUpdate (object) or Apache_Iceberg_REST_Catalog_API_RemovePropertiesUpdate (object) or Apache_Iceberg_REST_Catalog_API_AddViewVersionUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetCurrentViewVersionUpdate (object) (Apache_Iceberg_REST_Catalog_API_ViewUpdate)

    Responses

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Replace a view

    Commit updates to a view.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    view
    required
    string
    Example: sales

    A view name

    +
    Request Body schema: application/json
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)
    Array of objects (Apache_Iceberg_REST_Catalog_API_ViewRequirement)
    required
    Array of Apache_Iceberg_REST_Catalog_API_AssignUUIDUpdate (object) or Apache_Iceberg_REST_Catalog_API_UpgradeFormatVersionUpdate (object) or Apache_Iceberg_REST_Catalog_API_AddSchemaUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetLocationUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetPropertiesUpdate (object) or Apache_Iceberg_REST_Catalog_API_RemovePropertiesUpdate (object) or Apache_Iceberg_REST_Catalog_API_AddViewVersionUpdate (object) or Apache_Iceberg_REST_Catalog_API_SetCurrentViewVersionUpdate (object) (Apache_Iceberg_REST_Catalog_API_ViewUpdate)

    Responses

    Request samples

    Content type
    application/json
    {
    • "identifier": {
      },
    • "requirements": [
      ],
    • "updates": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Drop a view from the catalog

    Remove a view from the catalog

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    view
    required
    string
    Example: sales

    A view name

    -

    Responses

    Request samples

    Content type
    application/json
    {
    • "identifier": {
      },
    • "requirements": [
      ],
    • "updates": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "metadata-location": "string",
    • "metadata": {
      },
    • "config": {
      }
    }

    Drop a view from the catalog

    Remove a view from the catalog

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    view
    required
    string
    Example: sales

    A view name

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Check if a view exists

    Check if a view exists within a given namespace. This request does not return a response body.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    -
    view
    required
    string
    Example: sales

    A view name

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Check if a view exists

    Check if a view exists within a given namespace. This request does not return a response body.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    namespace
    required
    string
    Examples:
    • accounting -
    • accounting%1Ftax -

    A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

    +
    view
    required
    string
    Example: sales

    A view name

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Rename a view from its current name to a new name

    Rename a view from one identifier to another. It's valid to move a view across namespaces, but the server implementation is not required to support it.

    -
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    -
    Request Body schema: application/json
    required

    Current view identifier to rename and new view identifier to rename to

    -
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Rename a view from its current name to a new name

    Rename a view from one identifier to another. It's valid to move a view across namespaces, but the server implementation is not required to support it.

    +
    Authorizations:
    Apache_Iceberg_REST_Catalog_API_OAuth2Apache_Iceberg_REST_Catalog_API_BearerAuth
    path Parameters
    prefix
    required
    string

    An optional prefix in the path

    +
    Request Body schema: application/json
    required

    Current view identifier to rename and new view identifier to rename to

    +
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)
    required
    object (Apache_Iceberg_REST_Catalog_API_TableIdentifier)

    Responses

    Request samples

    Content type
    application/json
    {
    • "source": {
      },
    • "destination": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }
    +

    Request samples

    Content type
    application/json
    {
    • "source": {
      },
    • "destination": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }