diff --git a/docs/command-line-interface.md b/docs/command-line-interface.md index 23fcdc3d29..8d543e431c 100644 --- a/docs/command-line-interface.md +++ b/docs/command-line-interface.md @@ -797,7 +797,7 @@ polaris namespaces list --catalog my_catalog --parent a.b ### Privileges -The `privileges` command is used to grant various privileges to a catalog role, or to revoke those privileges. Privileges can be on the level of a catalog, a namespace, a table, or a view. For more information on privileges, please refer to the [docs](./entities.md#privilege). +The `privileges` command is used to grant various privileges to a catalog role, or to revoke those privileges. Privileges can be on the level of a catalog, a namespace, a table, or a view. For more information on privileges, please refer to the [docs](https://polaris.io/#tag/Polaris-Catalog-Entities/Privilege). Note that when using the `privileges` command, the user specifies the relevant catalog and catalog role before selecting a subcommand. diff --git a/docs/entities.md b/docs/entities.md index ae346c903a..118000dcb4 100644 --- a/docs/entities.md +++ b/docs/entities.md @@ -20,13 +20,13 @@ This page documents various entities that can be managed in Polaris. A catalog is a top-level entity in Polaris that may contain other entities like [namespaces](#namespace) and [tables](#table). These map directly to [Apache Iceberg catalogs](https://iceberg.apache.org/concepts/catalog/). -For information on managing catalogs with the REST API or for more information on what data can be associated with a catalog, see [the API docs](../regtests/client/python/docs/CreateCatalogRequest.md). +For information on managing catalogs with the REST API or for more information on what data can be associated with a catalog, see [the API docs](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/CreateCatalogRequest.md). ### 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](../regtests/client/python/docs/StorageConfigInfo.md). +For details on how to use Storage Types in the REST API, see [the API docs](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/StorageConfigInfo.md). ## Namespace @@ -34,32 +34,32 @@ A namespace is a logical entity that resides within a [catalog](#catalog) and ca 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](../regtests/client/python/docs/CreateNamespaceRequest.md). +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](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/CreateNamespaceRequest.md). ## Table Polaris tables are entities that map to [Apache Iceberg tables](https://iceberg.apache.org/docs/nightly/configuration/). -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](../regtests/client/python/docs/CreateTableRequest.md). +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](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/CreateTableRequest.md). ## View Polaris views are entities that map to [Apache Iceberg views](https://iceberg.apache.org/view-spec/). -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](../regtests/client/python/docs/CreateViewRequest.md). +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](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/CreateViewRequest.md). ## Principal Polaris principals are unique identities that can be used to represent users or services. Each principal may have one or more [principal roles](#principal-role) 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](../regtests/client/python/docs/CreatePrincipalRequest.md). +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](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/CreatePrincipalRequest.md). ## Principal Role Polaris principal roles are labels that may be granted to [principals](#principal). 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](../regtests/client/python/docs/CreatePrincipalRoleRequest.md). +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](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/CreatePrincipalRoleRequest.md). ## Catalog Role @@ -75,7 +75,7 @@ Polaris privileges are granted to [catalog roles](#catalog-role) in order to gra A privilege can be scoped to any entity inside a catalog, including the catalog itself. For a list of supported privileges for each privilege class, see the API docs: -* [Table Privileges](../regtests/client/python/docs/TablePrivilege.md) -* [View Privileges](../regtests/client/python/docs/ViewPrivilege.md) -* [Namespace Privileges](../regtests/client/python/docs/NamespacePrivilege.md) -* [Catalog Privileges](../regtests/client/python/docs/CatalogPrivilege.md) +* [Table Privileges](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/TablePrivilege.md) +* [View Privileges](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/ViewPrivilege.md) +* [Namespace Privileges](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/NamespacePrivilege.md) +* [Catalog Privileges](https://github.com/polaris-catalog/polaris/blob/main/regtests/client/python/docs/CatalogPrivilege.md) diff --git a/docs/index.html b/docs/index.html index ca2c54008b..6298076830 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/polaris-catalog/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

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 <pre><code class="language-shell"><span class="token builtin class-name">export</span> <span class="token assign-left variable">CLIENT_ID</span><span class="token operator">=</span><span class="token operator">&lt;</span>client-id<span class="token operator">></span> <span class="token builtin class-name">export</span> <span class="token assign-left variable">CLIENT_SECRET</span><span class="token operator">=</span><span class="token operator">&lt;</span>client-secret<span class="token operator">></span> </code></pre> -">

For this tutorial, we'll launch an instance of Polaris that stores entities only in-memory. This means that any entities that you define will be destroyed when Polaris is shut down. It also means that Polaris will automatically bootstrap itself with root credentials. For more information on how to configure Polaris for production usage, see the docs.

+">

For this tutorial, we'll launch an instance of Polaris that stores entities only in-memory. This means that any entities that you define will be destroyed when Polaris is shut down. It also means that Polaris will automatically bootstrap itself with root credentials. For more information on how to configure Polaris for production usage, see the docs.

When Polaris is launched using in-memory mode the root principal credentials can be found in stdout on initial startup. For example:

realm: default-realm root principal credentials: <client-id>:<client-secret>
@@ -602,7 +602,7 @@

Building Polaris

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

Defining a Catalog

Defining a Catalog

Building Polaris </code></pre> <p>This will create a new catalog called <strong>quickstart_catalog</strong>.</p> <p>The <code>DEFAULT_BASE_LOCATION</code> you provide will be the default location that objects in this catalog should be stored in, and the <code>ROLE_ARN</code> you provide should be a <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html">Role ARN</a> with access to read and write data in that location. These credentials will be provided to engines reading data from the catalog once they have authenticated with Polaris using credentials that have access to those resources.</p> -<p>If you’re using a storage type other than S3, such as Azure, you’ll provide a different type of credential than a Role ARN. For more details on supported storage types, see the <a href="./entities.md#storage-type">docs</a>.</p> -<p>Additionally, if Polaris is running somewhere other than <code>localhost:8181</code>, you can specify the correct hostname and port by providing <code>--host</code> and <code>--port</code> flags. For the full set of options supported by the CLI, please refer to the <a href="./command-line-interface.md">docs</a>.</p> +<p>If you’re using a storage type other than S3, such as Azure, you’ll provide a different type of credential than a Role ARN. For more details on supported storage types, see the <a href="#storage-type">docs</a>.</p> +<p>Additionally, if Polaris is running somewhere other than <code>localhost:8181</code>, you can specify the correct hostname and port by providing <code>--host</code> and <code>--port</code> flags. For the full set of options supported by the CLI, please refer to the <a href="https://github.com/polaris-catalog/polaris/blob/main/docs/command-line-interface.md">docs</a>.</p> <h3 id="creating-a-principal-and-assigning-it-privileges">Creating a Principal and Assigning it Privileges</h3> -<p>With a catalog created, we can create a <a href="./entities.md#principal">principal</a> that has access to manage that catalog. For details on how to configure the Polaris CLI, see <a href="#defining-a-catalog">the section above</a> or refer to the <a href="./command-line-interface.md">docs</a>.</p> +<p>With a catalog created, we can create a <a href="#tag/Polaris-Catalog-Entities/Principal">principal</a> that has access to manage that catalog. For details on how to configure the Polaris CLI, see <a href="#defining-a-catalog">the section above</a> or refer to the <a href="https://github.com/polaris-catalog/polaris/blob/main/docs/command-line-interface.md">docs</a>.</p> <pre><code class="language-shell">./polaris <span class="token punctuation">\</span> --client-id <span class="token variable">${CLIENT_ID}</span> <span class="token punctuation">\</span> --client-secret <span class="token variable">${CLIENT_SECRET}</span> <span class="token punctuation">\</span> @@ -648,7 +648,7 @@

Building Polaris

<pre><code><span class="token punctuation">.</span><span class="token operator">/</span>polaris <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span> principals create example <span class="token punctuation">{</span><span class="token string">"clientId"</span><span class="token punctuation">:</span> <span class="token string">"XXXX"</span><span class="token punctuation">,</span> <span class="token string">"clientSecret"</span><span class="token punctuation">:</span> <span class="token string">"YYYY"</span><span class="token punctuation">}</span> </code></pre> -<p>Now, we grant the principal the <a href="./entities.md#principal-role">principal role</a> we created, and grant the <a href="./entities.md#catalog-role">catalog role</a> the principal role we created. For more information on these entities, please refer to the linked documentation.</p> +<p>Now, we grant the principal the <a href="#tag/Polaris-Catalog-Entities/Principal-Role">principal role</a> we created, and grant the <a href="#tag/Polaris-Catalog-Entities/Catalog-Role">catalog role</a> the principal role we created. For more information on these entities, please refer to the linked documentation.</p> <pre><code class="language-shell">./polaris <span class="token punctuation">\</span> --client-id <span class="token variable">${CLIENT_ID}</span> <span class="token punctuation">\</span> --client-secret <span class="token variable">${CLIENT_SECRET}</span> <span class="token punctuation">\</span> @@ -668,7 +668,7 @@

Building Polaris

</code></pre> <p>Now, we’ve linked our principal to the catalog via roles like so:</p> <p><img src="./img/quickstart/privilege-illustration-1.png" alt="Principal to Catalog" title="Principal to Catalog"></p> -<p>In order to give this principal the ability to interact with the catalog, we must assign some <a href="./entities.md#privilege">privileges</a>. For the time being, we will give this principal the ability to fully manage content in our new catalog. We can do this with the CLI like so:</p> +<p>In order to give this principal the ability to interact with the catalog, we must assign some <a href="#tag/Polaris-Catalog-Entities/Privilege">privileges</a>. For the time being, we will give this principal the ability to fully manage content in our new catalog. We can do this with the CLI like so:</p> <pre><code class="language-shell">./polaris <span class="token punctuation">\</span> --client-id <span class="token variable">${CLIENT_ID}</span> <span class="token punctuation">\</span> --client-secret <span class="token variable">${CLIENT_SECRET}</span> <span class="token punctuation">\</span> @@ -679,10 +679,10 @@

Building Polaris

--catalog-role quickstart_catalog_role <span class="token punctuation">\</span> CATALOG_MANAGE_CONTENT </code></pre> -<p>This grants the <a href="./entities.md#privilege">catalog privileges</a> <code>CATALOG_MANAGE_CONTENT</code> to our catalog role, linking everything together like so:</p> +<p>This grants the <a href="#tag/Polaris-Catalog-Entities/Privilege">catalog privileges</a> <code>CATALOG_MANAGE_CONTENT</code> to our catalog role, linking everything together like so:</p> <p><img src="./img/quickstart/privilege-illustration-2.png" alt="Principal to Catalog with Catalog Role" title="Principal to Catalog with Catalog Role"></p> <p><code>CATALOG_MANAGE_CONTENT</code> 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.</p> -">

In Polaris, the catalog is the top-level entity that objects like tables and views are organized under. With a Polaris service running, you can create a catalog like so:

+">

In Polaris, the catalog is the top-level entity that objects like tables and views are organized under. With a Polaris service running, you can create a catalog like so:

cd ~/polaris
 
 ./polaris \
@@ -697,10 +697,10 @@ 
Building Polaris

This will create a new catalog called quickstart_catalog.

The DEFAULT_BASE_LOCATION you provide will be the default location that objects in this catalog should be stored in, and the ROLE_ARN you provide should be a Role ARN with access to read and write data in that location. These credentials will be provided to engines reading data from the catalog once they have authenticated with Polaris using credentials that have access to those resources.

-

If you’re using a storage type other than S3, such as Azure, you’ll provide a different type of credential than a Role ARN. For more details on supported storage types, see the docs.

-

Additionally, if Polaris is running somewhere other than localhost:8181, you can specify the correct hostname and port by providing --host and --port flags. For the full set of options supported by the CLI, please refer to the docs.

+

If you’re using a storage type other than S3, such as Azure, you’ll provide a different type of credential than a Role ARN. For more details on supported storage types, see the docs.

+

Additionally, if Polaris is running somewhere other than localhost:8181, you can specify the correct hostname and port by providing --host and --port flags. For the full set of options supported by the CLI, please refer to the docs.

Creating a Principal and Assigning it Privileges

-

With a catalog created, we can create a principal that has access to manage that catalog. For details on how to configure the Polaris CLI, see the section above or refer to the docs.

+

With a catalog created, we can create a principal that has access to manage that catalog. For details on how to configure the Polaris CLI, see the section above or refer to the docs.

./polaris \
   --client-id ${CLIENT_ID} \
   --client-secret ${CLIENT_SECRET} \
@@ -728,7 +728,7 @@ 
Creating a Principal a
 
./polaris ... principals create example
 {"clientId": "XXXX", "clientSecret": "YYYY"}
 

-
Now, we grant the principal the principal role we created, and grant the catalog role the principal role we created. For more information on these entities, please refer to the linked documentation.

+
Now, we grant the principal the principal role we created, and grant the catalog role the principal role we created. For more information on these entities, please refer to the linked documentation.

 
./polaris \
   --client-id ${CLIENT_ID} \
   --client-secret ${CLIENT_SECRET} \
@@ -748,7 +748,7 @@ 
Creating a Principal a
 

 
Now, we’ve linked our principal to the catalog via roles like so:

 
Principal to Catalog

-
In order to give this principal the ability to interact with the catalog, we must assign some privileges. For the time being, we will give this principal the ability to fully manage content in our new catalog. We can do this with the CLI like so:

+
In order to give this principal the ability to interact with the catalog, we must assign some privileges. For the time being, we will give this principal the ability to fully manage content in our new catalog. We can do this with the CLI like so:

 
./polaris \
   --client-id ${CLIENT_ID} \
   --client-secret ${CLIENT_SECRET} \
@@ -759,10 +759,10 @@ 
Creating a Principal a
   --catalog-role quickstart_catalog_role \
   CATALOG_MANAGE_CONTENT
 

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

+
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

Connecting with Spark <p>A service connection represents a REST-compatible engine (such as Apache Spark&trade;, Apache Flink&reg;, or Trino) that can read from and write to Polaris Catalog. When creating a new service connection, the Polaris administrator grants the service principal that is created with the new service connection either a new or existing principal role. A principal role is a resource in Polaris that you can use to logically group Polaris -service principals together and grant privileges on securable objects. For more information, see <a href="access-control.md#principal-role" title="Principal role">Principal role</a>. Polaris Catalog uses a role-based access control (RBAC) model to grant service principals access to resources. For more information, -see <a href="access-control.md" title="Access control">Access control</a>. For a diagram of this model, see <a href="access-control.md#rbac-model" title="RBAC model">RBAC model</a>.</p> +service principals together and grant privileges on securable objects. For more information, see <a href="#tag/Access-Control/Principal-role" title="Principal role">Principal role</a>. Polaris Catalog uses a role-based access control (RBAC) model to grant service principals access to resources. For more information, +see <a href="#tag/Access-Control" title="Access control">Access control</a>. For a diagram of this model, see <a href="#tag/Access-Control/RBAC-model" title="RBAC model">RBAC model</a>.</p> <p>If the Polaris administrator grants the service principal for the new service connection a new principal role, the service principal doesn&#39;t have any privileges granted to it yet. When securing the catalog that the new service connection will connect to, the Polaris administrator grants privileges to catalog roles and then grants these catalog roles to the new principal role. As a result, the service -principal for the new service connection has these privileges. For more information about catalog roles, see <a href="access-control.md#catalog-role" title="Catalog role">Catalog role</a>.</p> +principal for the new service connection has these privileges. For more information about catalog roles, see <a href="#tag/Access-Control/Catalog-role" title="Catalog role">Catalog role</a>.</p> <p>If the Polaris administrator grants an existing principal role to the service principal for the new service connection, the service principal has the same privileges granted to the catalog roles that are granted to the existing principal role. If needed, the Polaris administrator can grant additional catalog roles to the existing principal role or remove catalog roles from it to adjust the privileges -bestowed to the service principal. For an example of how RBAC works in Polaris, see <a href="access-control.md#rbac-example" title="RBAC example">RBAC example</a>.</p> +bestowed to the service principal. For an example of how RBAC works in Polaris, see <a href="#tag/Access-Control/RBAC-example" title="RBAC example">RBAC example</a>.</p> <h3 id="storage-configuration">Storage configuration</h3> <p>A storage configuration stores a generated identity and access management (IAM) entity for your external cloud storage and is created when you create a catalog. The storage configuration is used to set the values to connect Polaris Catalog to your cloud storage. During the @@ -1052,7 +1052,7 @@

Connecting with Spark

</tr> </tbody></table> ">

This section introduces key concepts associated with using Polaris Catalog.

-

In the following diagram, a sample Polaris Catalog structure with nested namespaces is shown for Catalog1. No tables +

In the following diagram, a sample Polaris Catalog structure with nested namespaces is shown for Catalog1. No tables or namespaces have been created yet for Catalog2 or Catalog3.

Diagram that shows an example Polaris Catalog structure.

Catalog

@@ -1146,16 +1146,16 @@

Service connection

A service connection represents a REST-compatible engine (such as Apache Spark™, Apache Flink®, or Trino) that can read from and write to Polaris Catalog. When creating a new service connection, the Polaris administrator grants the service principal that is created with the new service connection either a new or existing principal role. A principal role is a resource in Polaris that you can use to logically group Polaris -service principals together and grant privileges on securable objects. For more information, see Principal role. Polaris Catalog uses a role-based access control (RBAC) model to grant service principals access to resources. For more information, -see Access control. For a diagram of this model, see RBAC model.

+service principals together and grant privileges on securable objects. For more information, see Principal role. Polaris Catalog uses a role-based access control (RBAC) model to grant service principals access to resources. For more information, +see Access control. For a diagram of this model, see RBAC model.

If the Polaris administrator grants the service principal for the new service connection a new principal role, the service principal doesn't have any privileges granted to it yet. When securing the catalog that the new service connection will connect to, the Polaris administrator grants privileges to catalog roles and then grants these catalog roles to the new principal role. As a result, the service -principal for the new service connection has these privileges. For more information about catalog roles, see Catalog role.

+principal for the new service connection has these privileges. For more information about catalog roles, see Catalog role.

If the Polaris administrator grants an existing principal role to the service principal for the new service connection, the service principal has the same privileges granted to the catalog roles that are granted to the existing principal role. If needed, the Polaris administrator can grant additional catalog roles to the existing principal role or remove catalog roles from it to adjust the privileges -bestowed to the service principal. For an example of how RBAC works in Polaris, see RBAC example.

+bestowed to the service principal. For an example of how RBAC works in Polaris, see RBAC example.

Storage configuration

A storage configuration stores a generated identity and access management (IAM) entity for your external cloud storage and is created when you create a catalog. The storage configuration is used to set the values to connect Polaris Catalog to your cloud storage. During the @@ -1182,7 +1182,7 @@

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

Storage configuration catalog resources and granted to principal roles.</p> </li> </ul> -<p>For more information, see <a href="access-control.md" title="Access control">Access control</a>.</p> +<p>For more information, see <a href="#tag/Access-Control" title="Access control">Access control</a>.</p> ">

This section describes security and access control.

Credential vending

To secure interactions with service connections, Polaris Catalog vends temporary storage credentials to the query engine during query @@ -1265,10 +1265,10 @@

Access control

catalog resources and granted to principal roles.

-

For more information, see Access control.

-

Legal Notices

Access control.

+

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

A catalog is a top-level entity in Polaris that may contain other entities like namespaces and tables. These map directly to Apache Iceberg catalogs.

-

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

+

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

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

the API docs.

+

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

the API docs.

+

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

the API docs.

+

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

the API docs.

+

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

the API docs.

+

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

the API docs.

+

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

Polaris privileges are granted to catalog roles in order to grant principals with a given principal role some degree of access to catalogs with a given catalog role. When a privilege is granted to a catalog role, any principal roles granted that catalog role receive the privilege. In turn, any principals who are granted that principal role receive it.

A privilege can be scoped to any entity inside a catalog, including the catalog itself.

For a list of supported privileges for each privilege class, see the API docs:

-

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

    callContextResolver & rea
  • 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 and RealmContextResolver).
    • -

    Metastore Management

    Metastore Management

    callContextResolver & rea <h3 id="bootstrapping">Bootstrapping</h3> <p>Before using Polaris when using a metastore manager other than <code>in-memory</code>, you must <strong>bootstrap</strong> the metastore manager. This is a manual operation that must be performed <strong>only once</strong> 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 <strong>purged</strong>.</p> <p>To bootstrap Polaris, run:</p> -<pre><code class="language-bash"><span class="token function">java</span> <span class="token parameter variable">-jar</span> /path/to/jar/polaris-service-1.0.0-all.jar bootstrap polaris-server.yml +<pre><code class="language-bash"><span class="token function">java</span> <span class="token parameter variable">-jar</span> /path/to/jar/polaris-service-all.jar bootstrap polaris-server.yml </code></pre> <p>Afterwards, Polaris can be launched normally:</p> -<pre><code class="language-bash"><span class="token function">java</span> <span class="token parameter variable">-jar</span> /path/to/jar/polaris-service-1.0.0-all.jar server polaris-server.yml +<pre><code class="language-bash"><span class="token function">java</span> <span class="token parameter variable">-jar</span> /path/to/jar/polaris-service-all.jar server polaris-server.yml </code></pre> ">

    [!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.

    @@ -2019,12 +2019,12 @@

    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": {
      }
    }