diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml index d3bb9ab3b..de458aba0 100644 --- a/.github/workflows/site.yml +++ b/.github/workflows/site.yml @@ -46,8 +46,9 @@ jobs: - name: Build Apache Site run: site/bin/create-static-site.sh - # TODO Do we want to deploy from 'asf-site' in the 'polaris-site' repo or in the 'polaris' repo? - # The former requires a secret + - name: Copy .asf.yaml + run: sudo cp .asf.yaml site/build/apache-site/ + - name: Deploy Static Site to GitHub if: github.event_name == 'push' && github.repository == 'apache/polaris' uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4 diff --git a/site/content/_index.adoc b/site/content/_index.adoc index d9dec6d2c..5c99c5b58 100644 --- a/site/content/_index.adoc +++ b/site/content/_index.adoc @@ -26,7 +26,7 @@ cascade: Apache Polaris is an open-source, fully-featured catalog for Apache Iceberg™. It implements Iceberg's REST API, enabling seamless multi-engine interoperability across a wide range of platforms, including Apache Doris™, Apache Flink®, Apache Spark™, StarRocks, and Trino. {{< /blocks/cover >}} -image::images/Polaris-Catalog-BLOG-symmetrical-subhead.png[Polaris Catalog] +image::img/Polaris-Catalog-BLOG-symmetrical-subhead.png[Polaris Catalog] {{< blocks/section color="dark" type="row" >}} {{% blocks/feature icon="fa-lightbulb" title="Join the community!" url="https://polaris-catalog.zulipchat.com/" url_text="Chat with us" %}} @@ -42,7 +42,7 @@ For announcement and discussions about the project. {{< blocks/section color="dark" >}}

- +

Apache Polaris™ is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. diff --git a/site/content/in-dev/unreleased/openapi/polaris-management-service.yml b/site/content/in-dev/unreleased/openapi/polaris-management-service.yml deleted file mode 100644 index 03068c60a..000000000 --- a/site/content/in-dev/unreleased/openapi/polaris-management-service.yml +++ /dev/null @@ -1,1345 +0,0 @@ -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at - -# http://www.apache.org/licenses/LICENSE-2.0 - -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - - -openapi: 3.0.3 -info: - title: Polaris Management Service - version: 0.0.1 - description: - Defines the management APIs for using Polaris to create and manage Iceberg catalogs and their principals -servers: - - url: "{scheme}://{host}/api/management/v1" - description: Server URL when the port can be inferred from the scheme - variables: - scheme: - description: The scheme of the URI, either http or https. - default: https - host: - description: The host address for the specified server - default: localhost -# All routes are currently configured using an Authorization header. -security: - - OAuth2: [] - -paths: - /catalogs: - get: - operationId: listCatalogs - description: List all catalogs in this polaris service - responses: - 200: - description: List of catalogs in the polaris service - content: - application/json: - schema: - $ref: "#/components/schemas/Catalogs" - 403: - description: "The caller does not have permission to list catalog details" - post: - operationId: createCatalog - description: Add a new Catalog - requestBody: - description: The Catalog to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateCatalogRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The caller does not have permission to create a catalog" - 404: - description: "The catalog does not exist" - 409: - description: "A catalog with the specified name already exists" - - /catalogs/{catalogName}: - parameters: - - name: catalogName - in: path - description: The name of the catalog - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: getCatalog - description: Get the details of a catalog - responses: - 200: - description: The catalog details - content: - application/json: - schema: - $ref: "#/components/schemas/Catalog" - 403: - description: "The caller does not have permission to read catalog details" - 404: - description: "The catalog does not exist" - - put: - operationId: updateCatalog - description: Update an existing catalog - requestBody: - description: The catalog details to use in the update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateCatalogRequest" - responses: - 200: - description: The catalog details - content: - application/json: - schema: - $ref: "#/components/schemas/Catalog" - 403: - description: "The caller does not have permission to update catalog details" - 404: - description: "The catalog does not exist" - 409: - description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" - - delete: - operationId: deleteCatalog - description: Delete an existing catalog. The catalog must be empty. - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to delete a catalog" - 404: - description: "The catalog does not exist" - - /principals: - get: - operationId: listPrincipals - description: List the principals for the current catalog - responses: - 200: - description: List of principals for this catalog - content: - application/json: - schema: - $ref: "#/components/schemas/Principals" - 403: - description: "The caller does not have permission to list catalog admins" - 404: - description: "The catalog does not exist" - - post: - operationId: createPrincipal - description: Create a principal - requestBody: - description: The principal to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreatePrincipalRequest" - responses: - 201: - description: "Successful response" - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalWithCredentials" - 403: - description: "The caller does not have permission to add a principal" - - /principals/{principalName}: - parameters: - - name: principalName - in: path - description: The principal name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: getPrincipal - description: Get the principal details - responses: - 200: - description: The requested principal - content: - application/json: - schema: - $ref: "#/components/schemas/Principal" - 403: - description: "The caller does not have permission to get principal details" - 404: - description: "The catalog or principal does not exist" - - put: - operationId: updatePrincipal - description: Update an existing principal - requestBody: - description: The principal details to use in the update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdatePrincipalRequest" - responses: - 200: - description: The updated principal - content: - application/json: - schema: - $ref: "#/components/schemas/Principal" - 403: - description: "The caller does not have permission to update principal details" - 404: - description: "The principal does not exist" - 409: - description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" - - delete: - operationId: deletePrincipal - description: Remove a principal from polaris - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to delete a principal" - 404: - description: "The principal does not exist" - - /principals/{principalName}/rotate: - parameters: - - name: principalName - in: path - description: The user name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - post: - operationId: rotateCredentials - description: 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. - responses: - 200: - description: The principal details along with the newly rotated credentials - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalWithCredentials" - 403: - description: "The caller does not have permission to rotate credentials" - 404: - description: "The principal does not exist" - - /principals/{principalName}/principal-roles: - parameters: - - name: principalName - in: path - description: The name of the target principal - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listPrincipalRolesAssigned - description: List the roles assigned to the principal - responses: - 200: - description: List of roles assigned to this principal - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRoles" - 403: - description: "The caller does not have permission to list roles" - 404: - description: "The principal or catalog does not exist" - - put: - operationId: assignPrincipalRole - description: Add a role to the principal - requestBody: - description: The principal role to assign - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GrantPrincipalRoleRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The caller does not have permission to add assign a role to the principal" - 404: - description: "The catalog, the principal, or the role does not exist" - - /principals/{principalName}/principal-roles/{principalRoleName}: - parameters: - - name: principalName - in: path - description: The name of the target principal - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: principalRoleName - in: path - description: The name of the role - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - delete: - operationId: revokePrincipalRole - description: Remove a role from a catalog principal - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to remove a role from the principal" - 404: - description: "The catalog or principal does not exist" - - /principal-roles: - get: - operationId: listPrincipalRoles - description: List the principal roles - responses: - 200: - description: List of principal roles - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRoles" - 403: - description: "The caller does not have permission to list principal roles" - 404: - description: "The catalog does not exist" - - post: - operationId: createPrincipalRole - description: Create a principal role - requestBody: - description: The principal to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreatePrincipalRoleRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The caller does not have permission to add a principal role" - - /principal-roles/{principalRoleName}: - parameters: - - name: principalRoleName - in: path - description: The principal role name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: getPrincipalRole - description: Get the principal role details - responses: - 200: - description: The requested principal role - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRole" - 403: - description: "The caller does not have permission to get principal role details" - 404: - description: "The principal role does not exist" - - put: - operationId: updatePrincipalRole - description: Update an existing principalRole - requestBody: - description: The principalRole details to use in the update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdatePrincipalRoleRequest" - responses: - 200: - description: The updated principal role - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRole" - 403: - description: "The caller does not have permission to update principal role details" - 404: - description: "The principal role does not exist" - 409: - description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" - - delete: - operationId: deletePrincipalRole - description: Remove a principal role from polaris - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to delete a principal role" - 404: - description: "The principal role does not exist" - - /principal-roles/{principalRoleName}/principals: - parameters: - - name: principalRoleName - in: path - description: The principal role name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listAssigneePrincipalsForPrincipalRole - description: List the Principals to whom the target principal role has been assigned - responses: - 200: - description: List the Principals to whom the target principal role has been assigned - content: - application/json: - schema: - $ref: "#/components/schemas/Principals" - 403: - description: "The caller does not have permission to list principals" - 404: - description: "The principal role does not exist" - - /principal-roles/{principalRoleName}/catalog-roles/{catalogName}: - parameters: - - name: principalRoleName - in: path - description: The principal role name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogName - in: path - required: true - description: The name of the catalog where the catalogRoles reside - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listCatalogRolesForPrincipalRole - description: Get the catalog roles mapped to the principal role - responses: - 200: - description: The list of catalog roles mapped to the principal role - content: - application/json: - schema: - $ref: "#/components/schemas/CatalogRoles" - 403: - description: "The caller does not have permission to list catalog roles" - 404: - description: "The principal role does not exist" - - put: - operationId: assignCatalogRoleToPrincipalRole - description: Assign a catalog role to a principal role - requestBody: - description: The principal to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GrantCatalogRoleRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The caller does not have permission to assign a catalog role" - - /principal-roles/{principalRoleName}/catalog-roles/{catalogName}/{catalogRoleName}: - parameters: - - name: principalRoleName - in: path - description: The principal role name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogName - in: path - description: The name of the catalog that contains the role to revoke - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogRoleName - in: path - description: The name of the catalog role that should be revoked - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - delete: - operationId: revokeCatalogRoleFromPrincipalRole - description: Remove a catalog role from a principal role - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to revoke a catalog role" - 404: - description: "The principal role does not exist" - - /catalogs/{catalogName}/catalog-roles: - parameters: - - name: catalogName - in: path - description: The catalog for which we are reading/updating roles - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listCatalogRoles - description: List existing roles in the catalog - responses: - 200: - description: The list of roles that exist in this catalog - content: - application/json: - schema: - $ref: "#/components/schemas/CatalogRoles" - post: - operationId: createCatalogRole - description: Create a new role in the catalog - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/CreateCatalogRoleRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The principal is not authorized to create roles" - 404: - description: "The catalog does not exist" - - /catalogs/{catalogName}/catalog-roles/{catalogRoleName}: - parameters: - - name: catalogName - in: path - description: The catalog for which we are retrieving roles - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogRoleName - in: path - description: The name of the role - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: getCatalogRole - description: Get the details of an existing role - responses: - 200: - description: The specified role details - content: - application/json: - schema: - $ref: "#/components/schemas/CatalogRole" - 403: - description: "The principal is not authorized to read role data" - 404: - description: "The catalog or the role does not exist" - - put: - operationId: updateCatalogRole - description: Update an existing role in the catalog - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateCatalogRoleRequest" - responses: - 200: - description: The specified role details - content: - application/json: - schema: - $ref: "#/components/schemas/CatalogRole" - 403: - description: "The principal is not authorized to update roles" - 404: - description: "The catalog or the role does not exist" - 409: - description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" - - delete: - operationId: deleteCatalogRole - description: Delete an existing role from the catalog. All associated grants will also be deleted - responses: - 204: - description: "Success, no content" - 403: - description: "The principal is not authorized to delete roles" - 404: - description: "The catalog or the role does not exist" - - /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/principal-roles: - parameters: - - name: catalogName - in: path - required: true - description: The name of the catalog where the catalog role resides - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogRoleName - in: path - required: true - description: The name of the catalog role - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listAssigneePrincipalRolesForCatalogRole - description: List the PrincipalRoles to which the target catalog role has been assigned - responses: - 200: - description: List the PrincipalRoles to which the target catalog role has been assigned - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRoles" - 403: - description: "The caller does not have permission to list principal roles" - 404: - description: "The catalog or catalog role does not exist" - - /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants: - parameters: - - name: catalogName - in: path - required: true - description: The name of the catalog where the role will receive the grant - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogRoleName - in: path - required: true - description: The name of the role receiving the grant (must exist) - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listGrantsForCatalogRole - description: List the grants the catalog role holds - responses: - 200: - description: List of all grants given to the role in this catalog - content: - application/json: - schema: - $ref: "#/components/schemas/GrantResources" - put: - operationId: addGrantToCatalogRole - description: Add a new grant to the catalog role - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/AddGrantRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The principal is not authorized to create grants" - 404: - description: "The catalog or the role does not exist" - post: - operationId: revokeGrantFromCatalogRole - description: - 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. - parameters: - - name: cascade - in: query - schema: - type: boolean - default: false - description: If true, the grant revocation cascades to all subresources. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/RevokeGrantRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The principal is not authorized to create grants" - 404: - description: "The catalog or the role does not exist" - -components: - securitySchemes: - OAuth2: - type: oauth2 - description: Uses OAuth 2 with client credentials flow - flows: - implicit: - authorizationUrl: "{scheme}://{host}/api/v1/oauth/tokens" - scopes: {} - - schemas: - Catalogs: - type: object - description: A list of Catalog objects - properties: - catalogs: - type: array - items: - $ref: "#/components/schemas/Catalog" - required: - - catalogs - - CreateCatalogRequest: - type: object - description: Request to create a new catalog - properties: - catalog: - $ref: "#/components/schemas/Catalog" - required: - - catalog - - Catalog: - type: object - description: A catalog object. A catalog may be internal or external. External 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 - properties: - type: - type: string - enum: - - INTERNAL - - EXTERNAL - description: the type of catalog - internal or external - default: INTERNAL - name: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - description: The name of the catalog - properties: - type: object - properties: - default-base-location: - type: string - additionalProperties: - type: string - required: - - default-base-location - createTimestamp: - type: integer - format: "int64" - description: The creation time represented as unix epoch timestamp in milliseconds - lastUpdateTimestamp: - type: integer - format: "int64" - description: The last update time represented as unix epoch timestamp in milliseconds - entityVersion: - type: integer - description: The version of the catalog object used to determine if the catalog metadata has changed - storageConfigInfo: - $ref: "#/components/schemas/StorageConfigInfo" - required: - - name - - type - - storageConfigInfo - - properties - discriminator: - propertyName: type - mapping: - INTERNAL: "#/components/schemas/PolarisCatalog" - EXTERNAL: "#/components/schemas/ExternalCatalog" - - - PolarisCatalog: - type: object - allOf: - - $ref: "#/components/schemas/Catalog" - description: The base catalog type - this contains all the fields necessary to construct an INTERNAL catalog - - ExternalCatalog: - description: An externally managed catalog - type: object - allOf: - - $ref: "#/components/schemas/Catalog" - - type: object - properties: - remoteUrl: - type: string - description: URL to the remote catalog API - - StorageConfigInfo: - type: object - description: A storage configuration used by catalogs - properties: - storageType: - type: string - enum: - - S3 - - GCS - - AZURE - - FILE - description: The cloud provider type this storage is built on. FILE is supported for testing purposes only - allowedLocations: - type: array - items: - type: string - example: "For AWS [s3://bucketname/prefix/], for AZURE [abfss://container@storageaccount.blob.core.windows.net/prefix/], for GCP [gs://bucketname/prefix/]" - required: - - storageType - discriminator: - propertyName: storageType - mapping: - S3: "#/components/schemas/AwsStorageConfigInfo" - AZURE: "#/components/schemas/AzureStorageConfigInfo" - GCS: "#/components/schemas/GcpStorageConfigInfo" - FILE: "#/components/schemas/FileStorageConfigInfo" - - AwsStorageConfigInfo: - type: object - description: aws storage configuration info - allOf: - - $ref: '#/components/schemas/StorageConfigInfo' - properties: - roleArn: - type: string - description: the aws role arn that grants privileges on the S3 buckets - example: "arn:aws:iam::123456789001:principal/abc1-b-self1234" - externalId: - type: string - description: an optional external id used to establish a trust relationship with AWS in the trust policy - userArn: - type: string - description: the aws user arn used to assume the aws role - example: "arn:aws:iam::123456789001:user/abc1-b-self1234" - required: - - roleArn - - AzureStorageConfigInfo: - type: object - description: azure storage configuration info - allOf: - - $ref: '#/components/schemas/StorageConfigInfo' - properties: - tenantId: - type: string - description: the tenant id that the storage accounts belong to - multiTenantAppName: - type: string - description: the name of the azure client application - consentUrl: - type: string - description: URL to the Azure permissions request page - required: - - tenantId - - GcpStorageConfigInfo: - type: object - description: gcp storage configuration info - allOf: - - $ref: '#/components/schemas/StorageConfigInfo' - properties: - gcsServiceAccount: - type: string - description: a Google cloud storage service account - - FileStorageConfigInfo: - type: object - description: gcp storage configuration info - allOf: - - $ref: '#/components/schemas/StorageConfigInfo' - - UpdateCatalogRequest: - description: Updates to apply to a Catalog - type: object - properties: - currentEntityVersion: - type: integer - description: 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. - properties: - type: object - additionalProperties: - type: string - storageConfigInfo: - $ref: "#/components/schemas/StorageConfigInfo" - - Principals: - description: A list of Principals - type: object - properties: - principals: - type: array - items: - $ref: "#/components/schemas/Principal" - required: - - principals - - PrincipalWithCredentials: - description: A user with its client id and secret. This type is returned when a new principal is created or when its - credentials are rotated - type: object - properties: - principal: - $ref: "#/components/schemas/Principal" - credentials: - type: object - properties: - clientId: - type: string - clientSecret: - type: string - format: password - required: - - principal - - credentials - - CreatePrincipalRequest: - type: object - properties: - principal: - $ref: '#/components/schemas/Principal' - credentialRotationRequired: - type: boolean - description: If true, the initial credentials can only be used to call rotateCredentials - - Principal: - description: A Polaris principal. - type: object - properties: - name: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - clientId: - type: string - description: The output-only OAuth clientId associated with this principal if applicable - properties: - type: object - additionalProperties: - type: string - createTimestamp: - type: integer - format: "int64" - lastUpdateTimestamp: - type: integer - format: "int64" - entityVersion: - type: integer - description: The version of the principal object used to determine if the principal metadata has changed - required: - - name - - UpdatePrincipalRequest: - description: Updates to apply to a Principal - type: object - properties: - currentEntityVersion: - type: integer - description: 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. - properties: - type: object - additionalProperties: - type: string - required: - - currentEntityVersion - - properties - - PrincipalRoles: - type: object - properties: - roles: - type: array - items: - $ref: "#/components/schemas/PrincipalRole" - required: - - roles - - GrantPrincipalRoleRequest: - type: object - properties: - principalRole: - $ref: '#/components/schemas/PrincipalRole' - - CreatePrincipalRoleRequest: - type: object - properties: - principalRole: - $ref: '#/components/schemas/PrincipalRole' - - PrincipalRole: - type: object - properties: - name: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - description: The name of the role - properties: - type: object - additionalProperties: - type: string - createTimestamp: - type: integer - format: "int64" - lastUpdateTimestamp: - type: integer - format: "int64" - entityVersion: - type: integer - description: The version of the principal role object used to determine if the principal role metadata has changed - required: - - name - - UpdatePrincipalRoleRequest: - description: Updates to apply to a Principal Role - type: object - properties: - currentEntityVersion: - type: integer - description: 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. - properties: - type: object - additionalProperties: - type: string - required: - - currentEntityVersion - - properties - - CatalogRoles: - type: object - properties: - roles: - type: array - items: - $ref: "#/components/schemas/CatalogRole" - description: The list of catalog roles - required: - - roles - - GrantCatalogRoleRequest: - type: object - properties: - catalogRole: - $ref: '#/components/schemas/CatalogRole' - - CreateCatalogRoleRequest: - type: object - properties: - catalogRole: - $ref: '#/components/schemas/CatalogRole' - - CatalogRole: - type: object - properties: - name: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - description: The name of the role - properties: - type: object - additionalProperties: - type: string - createTimestamp: - type: integer - format: "int64" - lastUpdateTimestamp: - type: integer - format: "int64" - entityVersion: - type: integer - description: The version of the catalog role object used to determine if the catalog role metadata has changed - required: - - name - - UpdateCatalogRoleRequest: - description: Updates to apply to a Catalog Role - type: object - properties: - currentEntityVersion: - type: integer - description: 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. - properties: - type: object - additionalProperties: - type: string - required: - - currentEntityVersion - - properties - - ViewPrivilege: - type: string - enum: - - CATALOG_MANAGE_ACCESS - - VIEW_CREATE - - VIEW_DROP - - VIEW_LIST - - VIEW_READ_PROPERTIES - - VIEW_WRITE_PROPERTIES - - VIEW_FULL_METADATA - - TablePrivilege: - type: string - enum: - - CATALOG_MANAGE_ACCESS - - TABLE_DROP - - TABLE_LIST - - TABLE_READ_PROPERTIES - - VIEW_READ_PROPERTIES - - TABLE_WRITE_PROPERTIES - - TABLE_READ_DATA - - TABLE_WRITE_DATA - - TABLE_FULL_METADATA - - NamespacePrivilege: - type: string - enum: - - CATALOG_MANAGE_ACCESS - - CATALOG_MANAGE_CONTENT - - CATALOG_MANAGE_METADATA - - NAMESPACE_CREATE - - TABLE_CREATE - - VIEW_CREATE - - NAMESPACE_DROP - - TABLE_DROP - - VIEW_DROP - - NAMESPACE_LIST - - TABLE_LIST - - VIEW_LIST - - NAMESPACE_READ_PROPERTIES - - TABLE_READ_PROPERTIES - - VIEW_READ_PROPERTIES - - NAMESPACE_WRITE_PROPERTIES - - TABLE_WRITE_PROPERTIES - - VIEW_WRITE_PROPERTIES - - TABLE_READ_DATA - - TABLE_WRITE_DATA - - NAMESPACE_FULL_METADATA - - TABLE_FULL_METADATA - - VIEW_FULL_METADATA - - CatalogPrivilege: - type: string - enum: - - CATALOG_MANAGE_ACCESS - - CATALOG_MANAGE_CONTENT - - CATALOG_MANAGE_METADATA - - CATALOG_READ_PROPERTIES - - CATALOG_WRITE_PROPERTIES - - NAMESPACE_CREATE - - TABLE_CREATE - - VIEW_CREATE - - NAMESPACE_DROP - - TABLE_DROP - - VIEW_DROP - - NAMESPACE_LIST - - TABLE_LIST - - VIEW_LIST - - NAMESPACE_READ_PROPERTIES - - TABLE_READ_PROPERTIES - - VIEW_READ_PROPERTIES - - NAMESPACE_WRITE_PROPERTIES - - TABLE_WRITE_PROPERTIES - - VIEW_WRITE_PROPERTIES - - TABLE_READ_DATA - - TABLE_WRITE_DATA - - NAMESPACE_FULL_METADATA - - TABLE_FULL_METADATA - - VIEW_FULL_METADATA - - AddGrantRequest: - type: object - properties: - grant: - $ref: '#/components/schemas/GrantResource' - - RevokeGrantRequest: - type: object - properties: - grant: - $ref: '#/components/schemas/GrantResource' - - ViewGrant: - allOf: - - $ref: '#/components/schemas/GrantResource' - - type: object - properties: - namespace: - type: array - items: - type: string - viewName: - type: string - minLength: 1 - maxLength: 256 - privilege: - $ref: '#/components/schemas/ViewPrivilege' - required: - - namespace - - viewName - - privilege - - TableGrant: - allOf: - - $ref: '#/components/schemas/GrantResource' - - type: object - properties: - namespace: - type: array - items: - type: string - tableName: - type: string - minLength: 1 - maxLength: 256 - privilege: - $ref: '#/components/schemas/TablePrivilege' - required: - - namespace - - tableName - - privilege - - NamespaceGrant: - allOf: - - $ref: '#/components/schemas/GrantResource' - - type: object - properties: - namespace: - type: array - items: - type: string - privilege: - $ref: '#/components/schemas/NamespacePrivilege' - required: - - namespace - - privilege - - - CatalogGrant: - allOf: - - $ref: '#/components/schemas/GrantResource' - - type: object - properties: - privilege: - $ref: '#/components/schemas/CatalogPrivilege' - required: - - privilege - - GrantResource: - type: object - discriminator: - propertyName: type - mapping: - catalog: '#/components/schemas/CatalogGrant' - namespace: '#/components/schemas/NamespaceGrant' - table: '#/components/schemas/TableGrant' - view: '#/components/schemas/ViewGrant' - properties: - type: - type: string - enum: - - catalog - - namespace - - table - - view - required: - - type - - GrantResources: - type: object - properties: - grants: - type: array - items: - $ref: "#/components/schemas/GrantResource" - required: - - grants diff --git a/site/content/in-dev/unreleased/openapi/rest-catalog-open-api.yaml b/site/content/in-dev/unreleased/openapi/rest-catalog-open-api.yaml deleted file mode 100644 index 7cd966b91..000000000 --- a/site/content/in-dev/unreleased/openapi/rest-catalog-open-api.yaml +++ /dev/null @@ -1,4085 +0,0 @@ -# -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. -# - ---- -openapi: 3.0.3 -info: - title: Apache Iceberg REST Catalog API - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.0.1 - description: - Defines the specification for the first version of the REST Catalog API. - Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2. -servers: - - url: "{scheme}://{host}/{basePath}" - description: Server URL when the port can be inferred from the scheme - variables: - scheme: - description: The scheme of the URI, either http or https. - default: https - host: - description: The host address for the specified server - default: localhost - basePath: - description: Optional prefix to be appended to all routes - default: "" - - url: "{scheme}://{host}:{port}/{basePath}" - description: Generic base server URL, with all parts configurable - variables: - scheme: - description: The scheme of the URI, either http or https. - default: https - host: - description: The host address for the specified server - default: localhost - port: - description: The port used when addressing the host - default: "443" - basePath: - description: Optional prefix to be appended to all routes - default: "" -# All routes are currently configured using an Authorization header. -security: - - OAuth2: [catalog] - - BearerAuth: [] - -paths: - /v1/config: - - get: - tags: - - Configuration API - summary: List all catalog configuration settings - operationId: getConfig - parameters: - - name: warehouse - in: query - required: false - schema: - type: string - description: Warehouse location or identifier to request from the service - description: - " - 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 - - - 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 - " - responses: - 200: - description: Server specified configuration values. - content: - application/json: - schema: - $ref: '#/components/schemas/CatalogConfig' - example: { - "overrides": { - "warehouse": "s3://bucket/warehouse/" - }, - "defaults": { - "clients": "4" - } - } - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/oauth/tokens: - - post: - tags: - - OAuth2 API - summary: Get a token using an OAuth2 flow (DEPRECATED for REMOVAL) - deprecated: true - operationId: getToken - description: - The `oauth/tokens` endpoint is **DEPRECATED for REMOVAL**. It is _not_ recommended to - implement this endpoint, unless you are fully aware of the potential security implications. - - All clients are encouraged to explicitly set the configuration property `oauth2-server-uri` - to the correct OAuth endpoint. - - Deprecated since Iceberg (Java) 1.6.0. The endpoint and related types will be removed from - this spec in Iceberg (Java) 2.0. - - See [Security improvements in the Iceberg REST specification](https://github.com/apache/iceberg/issues/10537) - - - 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. To exchange a client token and an identity token for a more specific access token - This uses the token exchange flow. - - 3. To exchange an access token for one with the same claims and a refreshed expiration period - This uses the token exchange flow. - - - 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. - requestBody: - required: true - content: - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/OAuthTokenRequest' - responses: - 200: - $ref: '#/components/responses/OAuthTokenResponse' - 400: - $ref: '#/components/responses/OAuthErrorResponse' - 401: - $ref: '#/components/responses/OAuthErrorResponse' - 5XX: - $ref: '#/components/responses/OAuthErrorResponse' - - /v1/{prefix}/namespaces: - parameters: - - $ref: '#/components/parameters/prefix' - - get: - tags: - - Catalog API - summary: List namespaces, optionally providing a parent namespace to list underneath - description: - 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. - operationId: listNamespaces - parameters: - - $ref: '#/components/parameters/page-token' - - $ref: '#/components/parameters/page-size' - - name: parent - in: query - description: - 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. - required: false - allowEmptyValue: true - schema: - type: string - example: "accounting%1Ftax" - responses: - 200: - $ref: '#/components/responses/ListNamespacesResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - Namespace provided in the `parent` query parameter is not found. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NoSuchNamespaceExample: - $ref: '#/components/examples/NoSuchNamespaceError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - post: - tags: - - Catalog API - summary: Create a namespace - description: - Create a namespace, with an optional set of properties. - The server might also add properties, such as `last_modified_time` etc. - operationId: createNamespace - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateNamespaceRequest' - responses: - 200: - $ref: '#/components/responses/CreateNamespaceResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 406: - $ref: '#/components/responses/UnsupportedOperationResponse' - 409: - description: Conflict - The namespace already exists - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NamespaceAlreadyExists: - $ref: '#/components/examples/NamespaceAlreadyExistsError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/namespaces/{namespace}: - parameters: - - $ref: '#/components/parameters/prefix' - - $ref: '#/components/parameters/namespace' - - get: - tags: - - Catalog API - summary: Load the metadata properties for a namespace - operationId: loadNamespaceMetadata - description: Return all stored metadata properties for a given namespace - responses: - 200: - $ref: '#/components/responses/GetNamespaceResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - Namespace not found - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NoSuchNamespaceExample: - $ref: '#/components/examples/NoSuchNamespaceError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - head: - tags: - - Catalog API - summary: Check if a namespace exists - operationId: namespaceExists - description: - Check if a namespace exists. The response does not contain a body. - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - Namespace not found - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NoSuchNamespaceExample: - $ref: '#/components/examples/NoSuchNamespaceError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - delete: - tags: - - Catalog API - summary: Drop a namespace from the catalog. Namespace must be empty. - operationId: dropNamespace - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - Namespace to delete does not exist. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NoSuchNamespaceExample: - $ref: '#/components/examples/NoSuchNamespaceError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/namespaces/{namespace}/properties: - parameters: - - $ref: '#/components/parameters/prefix' - - $ref: '#/components/parameters/namespace' - - post: - tags: - - Catalog API - summary: Set or remove properties on a namespace - operationId: updateProperties - description: - 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. - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateNamespacePropertiesRequest' - examples: - UpdateAndRemoveProperties: - $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest' - responses: - 200: - $ref: '#/components/responses/UpdateNamespacePropertiesResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - Namespace not found - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NamespaceNotFound: - $ref: '#/components/examples/NoSuchNamespaceError' - 406: - $ref: '#/components/responses/UnsupportedOperationResponse' - 422: - description: Unprocessable Entity - A property key was included in both `removals` and `updates` - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - UnprocessableEntityDuplicateKey: - $ref: '#/components/examples/UnprocessableEntityDuplicateKey' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/namespaces/{namespace}/tables: - parameters: - - $ref: '#/components/parameters/prefix' - - $ref: '#/components/parameters/namespace' - - get: - tags: - - Catalog API - summary: List all table identifiers underneath a given namespace - description: Return all table identifiers under this namespace - operationId: listTables - parameters: - - $ref: '#/components/parameters/page-token' - - $ref: '#/components/parameters/page-size' - responses: - 200: - $ref: '#/components/responses/ListTablesResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - The namespace specified does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NamespaceNotFound: - $ref: '#/components/examples/NoSuchNamespaceError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - post: - tags: - - Catalog API - summary: Create a table in the given namespace - description: - 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. - operationId: createTable - parameters: - - $ref: '#/components/parameters/data-access' - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateTableRequest' - responses: - 200: - $ref: '#/components/responses/CreateTableResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - The namespace specified does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NamespaceNotFound: - $ref: '#/components/examples/NoSuchNamespaceError' - 409: - description: Conflict - The table already exists - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NamespaceAlreadyExists: - $ref: '#/components/examples/TableAlreadyExistsError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/namespaces/{namespace}/register: - parameters: - - $ref: '#/components/parameters/prefix' - - $ref: '#/components/parameters/namespace' - - post: - tags: - - Catalog API - summary: Register a table in the given namespace using given metadata file location - description: - Register a table using given metadata file location. - - operationId: registerTable - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/RegisterTableRequest' - responses: - 200: - $ref: '#/components/responses/LoadTableResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - The namespace specified does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NamespaceNotFound: - $ref: '#/components/examples/NoSuchNamespaceError' - 409: - description: Conflict - The table already exists - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - NamespaceAlreadyExists: - $ref: '#/components/examples/TableAlreadyExistsError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/namespaces/{namespace}/tables/{table}: - parameters: - - $ref: '#/components/parameters/prefix' - - $ref: '#/components/parameters/namespace' - - $ref: '#/components/parameters/table' - - get: - tags: - - Catalog API - summary: Load a table from the catalog - operationId: loadTable - description: - 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=". - parameters: - - $ref: '#/components/parameters/data-access' - - in: query - name: snapshots - description: - 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`. - required: false - schema: - type: string - enum: [ all, refs ] - responses: - 200: - $ref: '#/components/responses/LoadTableResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchTableException, table to load does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - TableToLoadDoesNotExist: - $ref: '#/components/examples/NoSuchTableError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - post: - tags: - - Catalog API - summary: Commit updates to a table - operationId: updateTable - description: - 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. - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CommitTableRequest' - responses: - 200: - $ref: '#/components/responses/CommitTableResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchTableException, table to load does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - TableToUpdateDoesNotExist: - $ref: '#/components/examples/NoSuchTableError' - 409: - description: - Conflict - CommitFailedException, one or more requirements failed. The client may retry. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 500: - description: - An unknown server-side problem occurred; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Internal Server Error", - "type": "CommitStateUnknownException", - "code": 500 - } - } - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 502: - description: - A gateway or proxy received an invalid response from the upstream server; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Invalid response from the upstream server", - "type": "CommitStateUnknownException", - "code": 502 - } - } - 504: - description: - A server-side gateway timeout occurred; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Gateway timed out during commit", - "type": "CommitStateUnknownException", - "code": 504 - } - } - 5XX: - description: - A server-side problem that might not be addressable on the client. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Bad Gateway", - "type": "InternalServerError", - "code": 502 - } - } - - delete: - tags: - - Catalog API - summary: Drop a table from the catalog - operationId: dropTable - description: Remove a table from the catalog - parameters: - - name: purgeRequested - in: query - required: false - description: Whether the user requested to purge the underlying table's data and metadata - schema: - type: boolean - default: false - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchTableException, Table to drop does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - TableToDeleteDoesNotExist: - $ref: '#/components/examples/NoSuchTableError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - head: - tags: - - Catalog API - summary: Check if a table exists - operationId: tableExists - description: - Check if a table exists within a given namespace. The response does not contain a body. - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchTableException, Table not found - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - TableToLoadDoesNotExist: - $ref: '#/components/examples/NoSuchTableError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/tables/rename: - parameters: - - $ref: '#/components/parameters/prefix' - - post: - tags: - - Catalog API - summary: Rename a table from its current name to a new name - description: - 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. - operationId: renameTable - requestBody: - description: Current table identifier to rename and new table identifier to rename to - content: - application/json: - schema: - $ref: '#/components/schemas/RenameTableRequest' - examples: - RenameTableSameNamespace: - $ref: '#/components/examples/RenameTableSameNamespace' - required: true - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - - NoSuchTableException, Table to rename does not exist - - NoSuchNamespaceException, The target namespace of the new table identifier does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - TableToRenameDoesNotExist: - $ref: '#/components/examples/NoSuchTableError' - NamespaceToRenameToDoesNotExist: - $ref: '#/components/examples/NoSuchNamespaceError' - 406: - $ref: '#/components/responses/UnsupportedOperationResponse' - 409: - description: Conflict - The target identifier to rename to already exists as a table or view - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: - $ref: '#/components/examples/TableAlreadyExistsError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics: - parameters: - - $ref: '#/components/parameters/prefix' - - $ref: '#/components/parameters/namespace' - - $ref: '#/components/parameters/table' - - post: - tags: - - Catalog API - summary: Send a metrics report to this endpoint to be processed by the backend - operationId: reportMetrics - requestBody: - description: The request containing the metrics report to be sent - content: - application/json: - schema: - $ref: '#/components/schemas/ReportMetricsRequest' - required: true - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchTableException, table to load does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - TableToLoadDoesNotExist: - $ref: '#/components/examples/NoSuchTableError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/transactions/commit: - parameters: - - $ref: '#/components/parameters/prefix' - - post: - tags: - - Catalog API - summary: Commit updates to multiple tables in an atomic operation - operationId: commitTransaction - requestBody: - description: - 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. - content: - application/json: - schema: - $ref: '#/components/schemas/CommitTransactionRequest' - required: true - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchTableException, table to load does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - examples: - TableToUpdateDoesNotExist: - $ref: '#/components/examples/NoSuchTableError' - 409: - description: - Conflict - CommitFailedException, one or more requirements failed. The client may retry. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 500: - description: - An unknown server-side problem occurred; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Internal Server Error", - "type": "CommitStateUnknownException", - "code": 500 - } - } - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 502: - description: - A gateway or proxy received an invalid response from the upstream server; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Invalid response from the upstream server", - "type": "CommitStateUnknownException", - "code": 502 - } - } - 504: - description: - A server-side gateway timeout occurred; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Gateway timed out during commit", - "type": "CommitStateUnknownException", - "code": 504 - } - } - 5XX: - description: - A server-side problem that might not be addressable on the client. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Bad Gateway", - "type": "InternalServerError", - "code": 502 - } - } - - /v1/{prefix}/namespaces/{namespace}/views: - parameters: - - $ref: '#/components/parameters/prefix' - - $ref: '#/components/parameters/namespace' - - get: - tags: - - Catalog API - summary: List all view identifiers underneath a given namespace - description: Return all view identifiers under this namespace - operationId: listViews - parameters: - - $ref: '#/components/parameters/page-token' - - $ref: '#/components/parameters/page-size' - responses: - 200: - $ref: '#/components/responses/ListTablesResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - The namespace specified does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - examples: - NamespaceNotFound: - $ref: '#/components/examples/NoSuchNamespaceError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - post: - tags: - - Catalog API - summary: Create a view in the given namespace - description: - Create a view in the given namespace. - operationId: createView - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateViewRequest' - responses: - 200: - $ref: '#/components/responses/LoadViewResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: Not Found - The namespace specified does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - examples: - NamespaceNotFound: - $ref: '#/components/examples/NoSuchNamespaceError' - 409: - description: Conflict - The view already exists - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - examples: - NamespaceAlreadyExists: - $ref: '#/components/examples/ViewAlreadyExistsError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/namespaces/{namespace}/views/{view}: - parameters: - - $ref: '#/components/parameters/prefix' - - $ref: '#/components/parameters/namespace' - - $ref: '#/components/parameters/view' - - get: - tags: - - Catalog API - summary: Load a view from the catalog - operationId: loadView - description: - 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=". - responses: - 200: - $ref: '#/components/responses/LoadViewResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchViewException, view to load does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - examples: - ViewToLoadDoesNotExist: - $ref: '#/components/examples/NoSuchViewError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - post: - tags: - - Catalog API - summary: Replace a view - operationId: replaceView - description: - Commit updates to a view. - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CommitViewRequest' - responses: - 200: - $ref: '#/components/responses/LoadViewResponse' - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchViewException, view to load does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - examples: - ViewToUpdateDoesNotExist: - $ref: '#/components/examples/NoSuchViewError' - 409: - description: - Conflict - CommitFailedException. The client may retry. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 500: - description: - An unknown server-side problem occurred; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - example: { - "error": { - "message": "Internal Server Error", - "type": "CommitStateUnknownException", - "code": 500 - } - } - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 502: - description: - A gateway or proxy received an invalid response from the upstream server; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - example: { - "error": { - "message": "Invalid response from the upstream server", - "type": "CommitStateUnknownException", - "code": 502 - } - } - 504: - description: - A server-side gateway timeout occurred; the commit state is unknown. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - example: { - "error": { - "message": "Gateway timed out during commit", - "type": "CommitStateUnknownException", - "code": 504 - } - } - 5XX: - description: - A server-side problem that might not be addressable on the client. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - example: { - "error": { - "message": "Bad Gateway", - "type": "InternalServerError", - "code": 502 - } - } - - delete: - tags: - - Catalog API - summary: Drop a view from the catalog - operationId: dropView - description: Remove a view from the catalog - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - NoSuchViewException, view to drop does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - examples: - ViewToDeleteDoesNotExist: - $ref: '#/components/examples/NoSuchViewError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - head: - tags: - - Catalog API - summary: Check if a view exists - operationId: viewExists - description: - Check if a view exists within a given namespace. This request does not return a response body. - responses: - 204: - description: Success, no content - 400: - description: Bad Request - 401: - description: Unauthorized - 404: - description: Not Found - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - /v1/{prefix}/views/rename: - parameters: - - $ref: '#/components/parameters/prefix' - - post: - tags: - - Catalog API - summary: Rename a view from its current name to a new name - description: - 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. - operationId: renameView - requestBody: - description: Current view identifier to rename and new view identifier to rename to - content: - application/json: - schema: - $ref: '#/components/schemas/RenameTableRequest' - examples: - RenameViewSameNamespace: - $ref: '#/components/examples/RenameViewSameNamespace' - required: true - responses: - 204: - description: Success, no content - 400: - $ref: '#/components/responses/BadRequestErrorResponse' - 401: - $ref: '#/components/responses/UnauthorizedResponse' - 403: - $ref: '#/components/responses/ForbiddenResponse' - 404: - description: - Not Found - - NoSuchViewException, view to rename does not exist - - NoSuchNamespaceException, The target namespace of the new identifier does not exist - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - examples: - ViewToRenameDoesNotExist: - $ref: '#/components/examples/NoSuchViewError' - NamespaceToRenameToDoesNotExist: - $ref: '#/components/examples/NoSuchNamespaceError' - 406: - $ref: '#/components/responses/UnsupportedOperationResponse' - 409: - description: Conflict - The target identifier to rename to already exists as a table or view - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - example: - $ref: '#/components/examples/ViewAlreadyExistsError' - 419: - $ref: '#/components/responses/AuthenticationTimeoutResponse' - 503: - $ref: '#/components/responses/ServiceUnavailableResponse' - 5XX: - $ref: '#/components/responses/ServerErrorResponse' - - -components: - ####################################################### - # Common Parameter Definitions Used In Several Routes # - ####################################################### - parameters: - namespace: - name: namespace - in: path - required: true - description: - A namespace identifier as a single string. - Multipart namespace parts should be separated by the unit separator (`0x1F`) byte. - schema: - type: string - examples: - singlepart_namespace: - value: "accounting" - multipart_namespace: - value: "accounting%1Ftax" - - prefix: - name: prefix - in: path - schema: - type: string - required: true - description: An optional prefix in the path - - table: - name: table - in: path - description: A table name - required: true - schema: - type: string - example: "sales" - - view: - name: view - in: path - description: A view name - required: true - schema: - type: string - example: "sales" - - data-access: - name: X-Iceberg-Access-Delegation - in: header - description: > - 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. - - required: false - schema: - type: string - enum: - - vended-credentials - - remote-signing - style: simple - explode: false - example: "vended-credentials,remote-signing" - - page-token: - name: pageToken - in: query - required: false - allowEmptyValue: true - schema: - $ref: '#/components/schemas/PageToken' - - page-size: - name: pageSize - in: query - description: - 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`. - required: false - schema: - type: integer - minimum: 1 - - ############################## - # Application Schema Objects # - ############################## - schemas: - - ErrorModel: - type: object - description: JSON error payload returned in a response with further details on the error - required: - - message - - type - - code - properties: - message: - type: string - description: Human-readable error message - type: - type: string - description: Internal type definition of the error - example: NoSuchNamespaceException - code: - type: integer - minimum: 400 - maximum: 600 - description: HTTP response code - example: 404 - stack: - type: array - items: - type: string - - CatalogConfig: - type: object - description: Server-provided configuration for the catalog. - required: - - defaults - - overrides - properties: - overrides: - type: object - additionalProperties: - type: string - description: - Properties that should be used to override client configuration; applied after defaults and client configuration. - defaults: - type: object - additionalProperties: - type: string - description: - Properties that should be used as default configuration; applied before client configuration. - - CreateNamespaceRequest: - type: object - required: - - namespace - properties: - namespace: - $ref: '#/components/schemas/Namespace' - properties: - type: object - description: Configured string to string map of properties for the namespace - example: { "owner": "Hank Bendickson" } - default: { } - additionalProperties: - type: string - - UpdateNamespacePropertiesRequest: - type: object - properties: - removals: - type: array - uniqueItems: true - items: - type: string - example: [ "department", "access_group" ] - updates: - type: object - example: { "owner": "Hank Bendickson" } - additionalProperties: - type: string - - RenameTableRequest: - type: object - required: - - source - - destination - properties: - source: - $ref: '#/components/schemas/TableIdentifier' - destination: - $ref: '#/components/schemas/TableIdentifier' - - Namespace: - description: Reference to one or more levels of a namespace - type: array - items: - type: string - example: [ "accounting", "tax" ] - - PageToken: - description: - 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. - - type: string - nullable: true - - TableIdentifier: - type: object - required: - - namespace - - name - properties: - namespace: - $ref: '#/components/schemas/Namespace' - name: - type: string - nullable: false - - PrimitiveType: - type: string - example: - - "long" - - "string" - - "fixed[16]" - - "decimal(10,2)" - - StructField: - type: object - required: - - id - - name - - type - - required - properties: - id: - type: integer - name: - type: string - type: - $ref: '#/components/schemas/Type' - required: - type: boolean - doc: - type: string - - StructType: - type: object - required: - - type - - fields - properties: - type: - type: string - enum: ["struct"] - fields: - type: array - items: - $ref: '#/components/schemas/StructField' - - ListType: - type: object - required: - - type - - element-id - - element - - element-required - properties: - type: - type: string - enum: ["list"] - element-id: - type: integer - element: - $ref: '#/components/schemas/Type' - element-required: - type: boolean - - MapType: - type: object - required: - - type - - key-id - - key - - value-id - - value - - value-required - properties: - type: - type: string - enum: ["map"] - key-id: - type: integer - key: - $ref: '#/components/schemas/Type' - value-id: - type: integer - value: - $ref: '#/components/schemas/Type' - value-required: - type: boolean - - Type: - oneOf: - - $ref: '#/components/schemas/PrimitiveType' - - $ref: '#/components/schemas/StructType' - - $ref: '#/components/schemas/ListType' - - $ref: '#/components/schemas/MapType' - - Schema: - allOf: - - $ref: '#/components/schemas/StructType' - - type: object - properties: - schema-id: - type: integer - readOnly: true - identifier-field-ids: - type: array - items: - type: integer - - Expression: - oneOf: - - $ref: '#/components/schemas/AndOrExpression' - - $ref: '#/components/schemas/NotExpression' - - $ref: '#/components/schemas/SetExpression' - - $ref: '#/components/schemas/LiteralExpression' - - $ref: '#/components/schemas/UnaryExpression' - - ExpressionType: - type: string - example: - - "eq" - - "and" - - "or" - - "not" - - "in" - - "not-in" - - "lt" - - "lt-eq" - - "gt" - - "gt-eq" - - "not-eq" - - "starts-with" - - "not-starts-with" - - "is-null" - - "not-null" - - "is-nan" - - "not-nan" - - AndOrExpression: - type: object - required: - - type - - left - - right - properties: - type: - $ref: '#/components/schemas/ExpressionType' - enum: ["and", "or"] - left: - $ref: '#/components/schemas/Expression' - right: - $ref: '#/components/schemas/Expression' - - NotExpression: - type: object - required: - - type - - child - properties: - type: - $ref: '#/components/schemas/ExpressionType' - enum: ["not"] - child: - $ref: '#/components/schemas/Expression' - - UnaryExpression: - type: object - required: - - type - - term - - value - properties: - type: - $ref: '#/components/schemas/ExpressionType' - enum: ["is-null", "not-null", "is-nan", "not-nan"] - term: - $ref: '#/components/schemas/Term' - value: - type: object - - LiteralExpression: - type: object - required: - - type - - term - - value - properties: - type: - $ref: '#/components/schemas/ExpressionType' - enum: ["lt", "lt-eq", "gt", "gt-eq", "eq", "not-eq", "starts-with", "not-starts-with"] - term: - $ref: '#/components/schemas/Term' - value: - type: object - - SetExpression: - type: object - required: - - type - - term - - values - properties: - type: - $ref: '#/components/schemas/ExpressionType' - enum: ["in", "not-in"] - term: - $ref: '#/components/schemas/Term' - values: - type: array - items: - type: object - - Term: - oneOf: - - $ref: '#/components/schemas/Reference' - - $ref: '#/components/schemas/TransformTerm' - - Reference: - type: string - example: - - "column-name" - - TransformTerm: - type: object - required: - - type - - transform - - term - properties: - type: - type: string - enum: ["transform"] - transform: - $ref: '#/components/schemas/Transform' - term: - $ref: '#/components/schemas/Reference' - - Transform: - type: string - example: - - "identity" - - "year" - - "month" - - "day" - - "hour" - - "bucket[256]" - - "truncate[16]" - - PartitionField: - type: object - required: - - source-id - - transform - - name - properties: - field-id: - type: integer - source-id: - type: integer - name: - type: string - transform: - $ref: '#/components/schemas/Transform' - - PartitionSpec: - type: object - required: - - fields - properties: - spec-id: - type: integer - readOnly: true - fields: - type: array - items: - $ref: '#/components/schemas/PartitionField' - - SortDirection: - type: string - enum: ["asc", "desc"] - - NullOrder: - type: string - enum: ["nulls-first", "nulls-last"] - - SortField: - type: object - required: - - source-id - - transform - - direction - - null-order - properties: - source-id: - type: integer - transform: - $ref: '#/components/schemas/Transform' - direction: - $ref: '#/components/schemas/SortDirection' - null-order: - $ref: '#/components/schemas/NullOrder' - - SortOrder: - type: object - required: - - order-id - - fields - properties: - order-id: - type: integer - readOnly: true - fields: - type: array - items: - $ref: '#/components/schemas/SortField' - - Snapshot: - type: object - required: - - snapshot-id - - timestamp-ms - - manifest-list - - summary - properties: - snapshot-id: - type: integer - format: int64 - parent-snapshot-id: - type: integer - format: int64 - sequence-number: - type: integer - format: int64 - timestamp-ms: - type: integer - format: int64 - manifest-list: - type: string - description: Location of the snapshot's manifest list file - summary: - type: object - required: - - operation - properties: - operation: - type: string - enum: ["append", "replace", "overwrite", "delete"] - additionalProperties: - type: string - schema-id: - type: integer - - SnapshotReference: - type: object - required: - - type - - snapshot-id - properties: - type: - type: string - enum: ["tag", "branch"] - snapshot-id: - type: integer - format: int64 - max-ref-age-ms: - type: integer - format: int64 - max-snapshot-age-ms: - type: integer - format: int64 - min-snapshots-to-keep: - type: integer - - SnapshotReferences: - type: object - additionalProperties: - $ref: '#/components/schemas/SnapshotReference' - - SnapshotLog: - type: array - items: - type: object - required: - - snapshot-id - - timestamp-ms - properties: - snapshot-id: - type: integer - format: int64 - timestamp-ms: - type: integer - format: int64 - - MetadataLog: - type: array - items: - type: object - required: - - metadata-file - - timestamp-ms - properties: - metadata-file: - type: string - timestamp-ms: - type: integer - format: int64 - - TableMetadata: - type: object - required: - - format-version - - table-uuid - properties: - format-version: - type: integer - minimum: 1 - maximum: 2 - table-uuid: - type: string - location: - type: string - last-updated-ms: - type: integer - format: int64 - properties: - type: object - additionalProperties: - type: string - # schema tracking - schemas: - type: array - items: - $ref: '#/components/schemas/Schema' - current-schema-id: - type: integer - last-column-id: - type: integer - # partition spec tracking - partition-specs: - type: array - items: - $ref: '#/components/schemas/PartitionSpec' - default-spec-id: - type: integer - last-partition-id: - type: integer - # sort order tracking - sort-orders: - type: array - items: - $ref: '#/components/schemas/SortOrder' - default-sort-order-id: - type: integer - # snapshot tracking - snapshots: - type: array - items: - $ref: '#/components/schemas/Snapshot' - refs: - $ref: '#/components/schemas/SnapshotReferences' - current-snapshot-id: - type: integer - format: int64 - last-sequence-number: - type: integer - format: int64 - # logs - snapshot-log: - $ref: '#/components/schemas/SnapshotLog' - metadata-log: - $ref: '#/components/schemas/MetadataLog' - # statistics - statistics: - type: array - items: - $ref: '#/components/schemas/StatisticsFile' - partition-statistics: - type: array - items: - $ref: '#/components/schemas/PartitionStatisticsFile' - - SQLViewRepresentation: - type: object - required: - - type - - sql - - dialect - properties: - type: - type: string - sql: - type: string - dialect: - type: string - - ViewRepresentation: - oneOf: - - $ref: '#/components/schemas/SQLViewRepresentation' - - ViewHistoryEntry: - type: object - required: - - version-id - - timestamp-ms - properties: - version-id: - type: integer - timestamp-ms: - type: integer - format: int64 - - ViewVersion: - type: object - required: - - version-id - - timestamp-ms - - schema-id - - summary - - representations - - default-namespace - properties: - version-id: - type: integer - timestamp-ms: - type: integer - format: int64 - schema-id: - type: integer - description: Schema ID to set as current, or -1 to set last added schema - summary: - type: object - additionalProperties: - type: string - representations: - type: array - items: - $ref: '#/components/schemas/ViewRepresentation' - default-catalog: - type: string - default-namespace: - $ref: '#/components/schemas/Namespace' - - ViewMetadata: - type: object - required: - - view-uuid - - format-version - - location - - current-version-id - - versions - - version-log - - schemas - properties: - view-uuid: - type: string - format-version: - type: integer - minimum: 1 - maximum: 1 - location: - type: string - current-version-id: - type: integer - versions: - type: array - items: - $ref: '#/components/schemas/ViewVersion' - version-log: - type: array - items: - $ref: '#/components/schemas/ViewHistoryEntry' - schemas: - type: array - items: - $ref: '#/components/schemas/Schema' - properties: - type: object - additionalProperties: - type: string - - BaseUpdate: - discriminator: - propertyName: action - mapping: - assign-uuid: '#/components/schemas/AssignUUIDUpdate' - upgrade-format-version: '#/components/schemas/UpgradeFormatVersionUpdate' - add-schema: '#/components/schemas/AddSchemaUpdate' - set-current-schema: '#/components/schemas/SetCurrentSchemaUpdate' - add-spec: '#/components/schemas/AddPartitionSpecUpdate' - set-default-spec: '#/components/schemas/SetDefaultSpecUpdate' - add-sort-order: '#/components/schemas/AddSortOrderUpdate' - set-default-sort-order: '#/components/schemas/SetDefaultSortOrderUpdate' - add-snapshot: '#/components/schemas/AddSnapshotUpdate' - set-snapshot-ref: '#/components/schemas/SetSnapshotRefUpdate' - remove-snapshots: '#/components/schemas/RemoveSnapshotsUpdate' - remove-snapshot-ref: '#/components/schemas/RemoveSnapshotRefUpdate' - set-location: '#/components/schemas/SetLocationUpdate' - set-properties: '#/components/schemas/SetPropertiesUpdate' - remove-properties: '#/components/schemas/RemovePropertiesUpdate' - add-view-version: '#/components/schemas/AddViewVersionUpdate' - set-current-view-version: '#/components/schemas/SetCurrentViewVersionUpdate' - set-statistics: '#/components/schemas/SetStatisticsUpdate' - remove-statistics: '#/components/schemas/RemoveStatisticsUpdate' - set-partition-statistics: '#/components/schemas/SetPartitionStatisticsUpdate' - remove-partition-statistics: '#/components/schemas/RemovePartitionStatisticsUpdate' - type: object - required: - - action - properties: - action: - type: string - - AssignUUIDUpdate: - description: Assigning a UUID to a table/view should only be done when creating the table/view. It is not safe to re-assign the UUID if a table/view already has a UUID assigned - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - uuid - properties: - action: - type: string - enum: ["assign-uuid"] - uuid: - type: string - - UpgradeFormatVersionUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - format-version - properties: - action: - type: string - enum: ["upgrade-format-version"] - format-version: - type: integer - - AddSchemaUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - schema - properties: - action: - type: string - enum: ["add-schema"] - schema: - $ref: '#/components/schemas/Schema' - last-column-id: - type: integer - description: The highest assigned column ID for the table. This is used to ensure columns are always assigned an unused ID when evolving schemas. When omitted, it will be computed on the server side. - - SetCurrentSchemaUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - schema-id - properties: - action: - type: string - enum: ["set-current-schema"] - schema-id: - type: integer - description: Schema ID to set as current, or -1 to set last added schema - - AddPartitionSpecUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - spec - properties: - action: - type: string - enum: ["add-spec"] - spec: - $ref: '#/components/schemas/PartitionSpec' - - SetDefaultSpecUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - spec-id - properties: - action: - type: string - enum: [ "set-default-spec" ] - spec-id: - type: integer - description: Partition spec ID to set as the default, or -1 to set last added spec - - AddSortOrderUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - sort-order - properties: - action: - type: string - enum: [ "add-sort-order" ] - sort-order: - $ref: '#/components/schemas/SortOrder' - - SetDefaultSortOrderUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - sort-order-id - properties: - action: - type: string - enum: [ "set-default-sort-order" ] - sort-order-id: - type: integer - description: Sort order ID to set as the default, or -1 to set last added sort order - - AddSnapshotUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - snapshot - properties: - action: - type: string - enum: [ "add-snapshot" ] - snapshot: - $ref: '#/components/schemas/Snapshot' - - SetSnapshotRefUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - - $ref: '#/components/schemas/SnapshotReference' - required: - - action - - ref-name - properties: - action: - type: string - enum: [ "set-snapshot-ref" ] - ref-name: - type: string - - RemoveSnapshotsUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - snapshot-ids - properties: - action: - type: string - enum: [ "remove-snapshots" ] - snapshot-ids: - type: array - items: - type: integer - format: int64 - - RemoveSnapshotRefUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - ref-name - properties: - action: - type: string - enum: [ "remove-snapshot-ref" ] - ref-name: - type: string - - SetLocationUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - location - properties: - action: - type: string - enum: [ "set-location" ] - location: - type: string - - SetPropertiesUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - updates - properties: - action: - type: string - enum: [ "set-properties" ] - updates: - type: object - additionalProperties: - type: string - - RemovePropertiesUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - removals - properties: - action: - type: string - enum: [ "remove-properties" ] - removals: - type: array - items: - type: string - - AddViewVersionUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - view-version - properties: - action: - type: string - enum: [ "add-view-version" ] - view-version: - $ref: '#/components/schemas/ViewVersion' - - SetCurrentViewVersionUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - view-version-id - properties: - action: - type: string - enum: [ "set-current-view-version" ] - view-version-id: - type: integer - description: The view version id to set as current, or -1 to set last added view version id - - SetStatisticsUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - snapshot-id - - statistics - properties: - action: - type: string - enum: [ "set-statistics" ] - snapshot-id: - type: integer - format: int64 - statistics: - $ref: '#/components/schemas/StatisticsFile' - - RemoveStatisticsUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - snapshot-id - properties: - action: - type: string - enum: [ "remove-statistics" ] - snapshot-id: - type: integer - format: int64 - - SetPartitionStatisticsUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - partition-statistics - properties: - action: - type: string - enum: [ "set-partition-statistics" ] - partition-statistics: - $ref: '#/components/schemas/PartitionStatisticsFile' - - RemovePartitionStatisticsUpdate: - allOf: - - $ref: '#/components/schemas/BaseUpdate' - required: - - action - - snapshot-id - properties: - action: - type: string - enum: [ "remove-partition-statistics" ] - snapshot-id: - type: integer - format: int64 - - TableUpdate: - anyOf: - - $ref: '#/components/schemas/AssignUUIDUpdate' - - $ref: '#/components/schemas/UpgradeFormatVersionUpdate' - - $ref: '#/components/schemas/AddSchemaUpdate' - - $ref: '#/components/schemas/SetCurrentSchemaUpdate' - - $ref: '#/components/schemas/AddPartitionSpecUpdate' - - $ref: '#/components/schemas/SetDefaultSpecUpdate' - - $ref: '#/components/schemas/AddSortOrderUpdate' - - $ref: '#/components/schemas/SetDefaultSortOrderUpdate' - - $ref: '#/components/schemas/AddSnapshotUpdate' - - $ref: '#/components/schemas/SetSnapshotRefUpdate' - - $ref: '#/components/schemas/RemoveSnapshotsUpdate' - - $ref: '#/components/schemas/RemoveSnapshotRefUpdate' - - $ref: '#/components/schemas/SetLocationUpdate' - - $ref: '#/components/schemas/SetPropertiesUpdate' - - $ref: '#/components/schemas/RemovePropertiesUpdate' - - $ref: '#/components/schemas/SetStatisticsUpdate' - - $ref: '#/components/schemas/RemoveStatisticsUpdate' - - ViewUpdate: - anyOf: - - $ref: '#/components/schemas/AssignUUIDUpdate' - - $ref: '#/components/schemas/UpgradeFormatVersionUpdate' - - $ref: '#/components/schemas/AddSchemaUpdate' - - $ref: '#/components/schemas/SetLocationUpdate' - - $ref: '#/components/schemas/SetPropertiesUpdate' - - $ref: '#/components/schemas/RemovePropertiesUpdate' - - $ref: '#/components/schemas/AddViewVersionUpdate' - - $ref: '#/components/schemas/SetCurrentViewVersionUpdate' - - TableRequirement: - type: object - discriminator: - propertyName: type - mapping: - assert-create: '#/components/schemas/AssertCreate' - assert-table-uuid: '#/components/schemas/AssertTableUUID' - assert-ref-snapshot-id: '#/components/schemas/AssertRefSnapshotId' - assert-last-assigned-field-id: '#/components/schemas/AssertLastAssignedFieldId' - assert-current-schema-id: '#/components/schemas/AssertCurrentSchemaId' - assert-last-assigned-partition-id: '#/components/schemas/AssertLastAssignedPartitionId' - assert-default-spec-id: '#/components/schemas/AssertDefaultSpecId' - assert-default-sort-order-id: '#/components/schemas/AssertDefaultSortOrderId' - oneOf: - - $ref: '#/components/schemas/AssertCreate' - - $ref: '#/components/schemas/AssertTableUUID' - - $ref: '#/components/schemas/AssertRefSnapshotId' - - $ref: '#/components/schemas/AssertLastAssignedFieldId' - - $ref: '#/components/schemas/AssertCurrentSchemaId' - - $ref: '#/components/schemas/AssertLastAssignedPartitionId' - - $ref: '#/components/schemas/AssertDefaultSpecId' - - $ref: '#/components/schemas/AssertDefaultSortOrderId' - - AssertCreate: - type: object - description: The table must not already exist; used for create transactions - required: - - type - properties: - type: - type: string - enum: ["assert-create"] - - AssertTableUUID: - description: The table UUID must match the requirement's `uuid` - required: - - type - - uuid - properties: - type: - type: string - enum: ["assert-table-uuid"] - uuid: - type: string - - AssertRefSnapshotId: - description: - The table branch or tag identified by the requirement's `ref` must reference the requirement's `snapshot-id`; - if `snapshot-id` is `null` or missing, the ref must not already exist - required: - - type - - ref - - snapshot-id - properties: - type: - type: string - enum: [ "assert-ref-snapshot-id" ] - ref: - type: string - snapshot-id: - type: integer - format: int64 - - AssertLastAssignedFieldId: - description: - The table's last assigned column id must match the requirement's `last-assigned-field-id` - required: - - type - - last-assigned-field-id - properties: - type: - type: string - enum: [ "assert-last-assigned-field-id" ] - last-assigned-field-id: - type: integer - - AssertCurrentSchemaId: - description: - The table's current schema id must match the requirement's `current-schema-id` - required: - - type - - current-schema-id - properties: - type: - type: string - enum: [ "assert-current-schema-id" ] - current-schema-id: - type: integer - - AssertLastAssignedPartitionId: - description: - The table's last assigned partition id must match the requirement's `last-assigned-partition-id` - required: - - type - - last-assigned-partition-id - properties: - type: - type: string - enum: [ "assert-last-assigned-partition-id" ] - last-assigned-partition-id: - type: integer - - AssertDefaultSpecId: - description: - The table's default spec id must match the requirement's `default-spec-id` - required: - - type - - default-spec-id - properties: - type: - type: string - enum: [ "assert-default-spec-id" ] - default-spec-id: - type: integer - - AssertDefaultSortOrderId: - description: - The table's default sort order id must match the requirement's `default-sort-order-id` - required: - - type - - default-sort-order-id - properties: - type: - type: string - enum: [ "assert-default-sort-order-id" ] - default-sort-order-id: - type: integer - - ViewRequirement: - type: object - discriminator: - propertyName: type - mapping: - assert-view-uuid: '#/components/schemas/AssertViewUUID' - oneOf: - - $ref: '#/components/schemas/AssertViewUUID' - - AssertViewUUID: - description: The view UUID must match the requirement's `uuid` - required: - - type - - uuid - properties: - type: - type: string - enum: [ "assert-view-uuid" ] - uuid: - type: string - - LoadTableResult: - description: | - Result used when a table is successfully loaded. - - - The table metadata JSON is returned in the `metadata` field. The corresponding file location of table metadata should be returned in the `metadata-location` field, unless the metadata is not yet committed. For example, a create transaction may return metadata that is staged but not committed. - Clients can check whether metadata has changed by comparing metadata locations after the table has been created. - - - The `config` map returns table-specific configuration for the table's resources, including its HTTP client and FileIO. For example, config may contain a specific FileIO implementation class for the table depending on its underlying storage. - - - The following configurations should be respected by clients: - - ## General Configurations - - - `token`: Authorization bearer token to use for table requests if OAuth2 security is enabled - - ## AWS Configurations - - The following configurations should be respected when working with tables stored in AWS S3 - - `client.region`: region to configure client for making requests to AWS - - `s3.access-key-id`: id for for credentials that provide access to the data in S3 - - `s3.secret-access-key`: secret for credentials that provide access to data in S3 - - `s3.session-token`: if present, this value should be used for as the session token - - `s3.remote-signing-enabled`: if `true` remote signing should be performed as described in the `s3-signer-open-api.yaml` specification - type: object - required: - - metadata - properties: - metadata-location: - type: string - description: May be null if the table is staged as part of a transaction - metadata: - $ref: '#/components/schemas/TableMetadata' - config: - type: object - additionalProperties: - type: string - - CommitTableRequest: - type: object - required: - - requirements - - updates - properties: - identifier: - description: Table identifier to update; must be present for CommitTransactionRequest - $ref: '#/components/schemas/TableIdentifier' - requirements: - type: array - items: - $ref: '#/components/schemas/TableRequirement' - updates: - type: array - items: - $ref: '#/components/schemas/TableUpdate' - - CommitViewRequest: - type: object - required: - - updates - properties: - identifier: - description: View identifier to update - $ref: '#/components/schemas/TableIdentifier' - requirements: - type: array - items: - $ref: '#/components/schemas/ViewRequirement' - updates: - type: array - items: - $ref: '#/components/schemas/ViewUpdate' - - CommitTransactionRequest: - type: object - required: - - table-changes - properties: - table-changes: - type: array - items: - description: Table commit request; must provide an `identifier` - $ref: '#/components/schemas/CommitTableRequest' - - CreateTableRequest: - type: object - required: - - name - - schema - properties: - name: - type: string - location: - type: string - schema: - $ref: '#/components/schemas/Schema' - partition-spec: - $ref: '#/components/schemas/PartitionSpec' - write-order: - $ref: '#/components/schemas/SortOrder' - stage-create: - type: boolean - properties: - type: object - additionalProperties: - type: string - - RegisterTableRequest: - type: object - required: - - name - - metadata-location - properties: - name: - type: string - metadata-location: - type: string - - CreateViewRequest: - type: object - required: - - name - - schema - - view-version - - properties - properties: - name: - type: string - location: - type: string - schema: - $ref: '#/components/schemas/Schema' - view-version: - $ref: '#/components/schemas/ViewVersion' - description: The view version to create, will replace the schema-id sent within the view-version with the id assigned to the provided schema - properties: - type: object - additionalProperties: - type: string - - LoadViewResult: - description: | - Result used when a view is successfully loaded. - - - The view metadata JSON is returned in the `metadata` field. The corresponding file location of view metadata is returned in the `metadata-location` field. - Clients can check whether metadata has changed by comparing metadata locations after the view has been created. - - The `config` map returns view-specific configuration for the view's resources. - - The following configurations should be respected by clients: - - ## General Configurations - - - `token`: Authorization bearer token to use for view requests if OAuth2 security is enabled - - type: object - required: - - metadata-location - - metadata - properties: - metadata-location: - type: string - metadata: - $ref: '#/components/schemas/ViewMetadata' - config: - type: object - additionalProperties: - type: string - - TokenType: - type: string - enum: - - urn:ietf:params:oauth:token-type:access_token - - urn:ietf:params:oauth:token-type:refresh_token - - urn:ietf:params:oauth:token-type:id_token - - urn:ietf:params:oauth:token-type:saml1 - - urn:ietf:params:oauth:token-type:saml2 - - urn:ietf:params:oauth:token-type:jwt - description: - Token type identifier, from RFC 8693 Section 3 - - - See https://datatracker.ietf.org/doc/html/rfc8693#section-3 - - OAuthClientCredentialsRequest: - deprecated: true - description: - The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this - spec, see description of the endpoint. - - - OAuth2 client credentials request - - - See https://datatracker.ietf.org/doc/html/rfc6749#section-4.4 - type: object - required: - - grant_type - - client_id - - client_secret - properties: - grant_type: - type: string - enum: - - client_credentials - scope: - type: string - client_id: - type: string - description: - Client ID - - - This can be sent in the request body, but OAuth2 recommends sending it in - a Basic Authorization header. - client_secret: - type: string - description: - Client secret - - - This can be sent in the request body, but OAuth2 recommends sending it in - a Basic Authorization header. - - OAuthTokenExchangeRequest: - deprecated: true - description: - The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this - spec, see description of the endpoint. - - - OAuth2 token exchange request - - - See https://datatracker.ietf.org/doc/html/rfc8693 - type: object - required: - - grant_type - - subject_token - - subject_token_type - properties: - grant_type: - type: string - enum: - - urn:ietf:params:oauth:grant-type:token-exchange - scope: - type: string - requested_token_type: - $ref: '#/components/schemas/TokenType' - subject_token: - type: string - description: Subject token for token exchange request - subject_token_type: - $ref: '#/components/schemas/TokenType' - actor_token: - type: string - description: Actor token for token exchange request - actor_token_type: - $ref: '#/components/schemas/TokenType' - - OAuthTokenRequest: - deprecated: true - description: - The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this - spec, see description of the endpoint. - anyOf: - - $ref: '#/components/schemas/OAuthClientCredentialsRequest' - - $ref: '#/components/schemas/OAuthTokenExchangeRequest' - - CounterResult: - type: object - required: - - unit - - value - properties: - unit: - type: string - value: - type: integer - format: int64 - - TimerResult: - type: object - required: - - time-unit - - count - - total-duration - properties: - time-unit: - type: string - count: - type: integer - format: int64 - total-duration: - type: integer - format: int64 - - MetricResult: - anyOf: - - $ref: '#/components/schemas/CounterResult' - - $ref: '#/components/schemas/TimerResult' - - Metrics: - type: object - additionalProperties: - $ref: '#/components/schemas/MetricResult' - example: - "metrics": { - "total-planning-duration": { - "count": 1, - "time-unit": "nanoseconds", - "total-duration": 2644235116 - }, - "result-data-files": { - "unit": "count", - "value": 1, - }, - "result-delete-files": { - "unit": "count", - "value": 0, - }, - "total-data-manifests": { - "unit": "count", - "value": 1, - }, - "total-delete-manifests": { - "unit": "count", - "value": 0, - }, - "scanned-data-manifests": { - "unit": "count", - "value": 1, - }, - "skipped-data-manifests": { - "unit": "count", - "value": 0, - }, - "total-file-size-bytes": { - "unit": "bytes", - "value": 10, - }, - "total-delete-file-size-bytes": { - "unit": "bytes", - "value": 0, - } - } - - ReportMetricsRequest: - anyOf: - - $ref: '#/components/schemas/ScanReport' - - $ref: '#/components/schemas/CommitReport' - required: - - report-type - properties: - report-type: - type: string - - ScanReport: - type: object - required: - - table-name - - snapshot-id - - filter - - schema-id - - projected-field-ids - - projected-field-names - - metrics - properties: - table-name: - type: string - snapshot-id: - type: integer - format: int64 - filter: - $ref: '#/components/schemas/Expression' - schema-id: - type: integer - projected-field-ids: - type: array - items: - type: integer - projected-field-names: - type: array - items: - type: string - metrics: - $ref: '#/components/schemas/Metrics' - metadata: - type: object - additionalProperties: - type: string - - CommitReport: - type: object - required: - - table-name - - snapshot-id - - sequence-number - - operation - - metrics - properties: - table-name: - type: string - snapshot-id: - type: integer - format: int64 - sequence-number: - type: integer - format: int64 - operation: - type: string - metrics: - $ref: '#/components/schemas/Metrics' - metadata: - type: object - additionalProperties: - type: string - - OAuthError: - deprecated: true - description: - The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this - spec, see description of the endpoint. - type: object - required: - - error - properties: - error: - type: string - enum: - - invalid_request - - invalid_client - - invalid_grant - - unauthorized_client - - unsupported_grant_type - - invalid_scope - error_description: - type: string - error_uri: - type: string - - OAuthTokenResponse: - deprecated: true - description: - The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this - spec, see description of the endpoint. - type: object - required: - - access_token - - token_type - properties: - access_token: - type: string - description: - The access token, for client credentials or token exchange - token_type: - type: string - enum: - - bearer - - mac - - N_A - description: - Access token type for client credentials or token exchange - - - See https://datatracker.ietf.org/doc/html/rfc6749#section-7.1 - expires_in: - type: integer - description: - Lifetime of the access token in seconds for client credentials or token exchange - issued_token_type: - $ref: '#/components/schemas/TokenType' - refresh_token: - type: string - description: Refresh token for client credentials or token exchange - scope: - type: string - description: Authorization scope for client credentials or token exchange - - IcebergErrorResponse: - description: JSON wrapper for all error responses (non-2xx) - type: object - required: - - error - properties: - error: - $ref: '#/components/schemas/ErrorModel' - additionalProperties: false - example: - { - "error": { - "message": "The server does not support this operation", - "type": "UnsupportedOperationException", - "code": 406 - } - } - - CreateNamespaceResponse: - type: object - required: - - namespace - properties: - namespace: - $ref: '#/components/schemas/Namespace' - properties: - type: object - additionalProperties: - type: string - description: - Properties stored on the namespace, if supported by the server. - example: { "owner": "Ralph", "created_at": "1452120468" } - default: { } - - GetNamespaceResponse: - type: object - required: - - namespace - properties: - namespace: - $ref: '#/components/schemas/Namespace' - properties: - type: object - description: - Properties stored on the namespace, if supported by the server. - If the server does not support namespace properties, it should return null for this field. - If namespace properties are supported, but none are set, it should return an empty object. - additionalProperties: - type: string - example: { "owner": "Ralph", 'transient_lastDdlTime': '1452120468' } - default: { } - nullable: true - - ListTablesResponse: - type: object - properties: - next-page-token: - $ref: '#/components/schemas/PageToken' - identifiers: - type: array - uniqueItems: true - items: - $ref: '#/components/schemas/TableIdentifier' - - ListNamespacesResponse: - type: object - properties: - next-page-token: - $ref: '#/components/schemas/PageToken' - namespaces: - type: array - uniqueItems: true - items: - $ref: '#/components/schemas/Namespace' - - UpdateNamespacePropertiesResponse: - type: object - required: - - updated - - removed - properties: - updated: - description: List of property keys that were added or updated - type: array - uniqueItems: true - items: - type: string - removed: - description: List of properties that were removed - type: array - items: - type: string - missing: - type: array - items: - type: string - description: - List of properties requested for removal that were not found - in the namespace's properties. Represents a partial success response. - Server's do not need to implement this. - nullable: true - - CommitTableResponse: - type: object - required: - - metadata-location - - metadata - properties: - metadata-location: - type: string - metadata: - $ref: '#/components/schemas/TableMetadata' - - StatisticsFile: - type: object - required: - - snapshot-id - - statistics-path - - file-size-in-bytes - - file-footer-size-in-bytes - - blob-metadata - properties: - snapshot-id: - type: integer - format: int64 - statistics-path: - type: string - file-size-in-bytes: - type: integer - format: int64 - file-footer-size-in-bytes: - type: integer - format: int64 - blob-metadata: - type: array - items: - $ref: '#/components/schemas/BlobMetadata' - - BlobMetadata: - type: object - required: - - type - - snapshot-id - - sequence-number - - fields - properties: - type: - type: string - snapshot-id: - type: integer - format: int64 - sequence-number: - type: integer - format: int64 - fields: - type: array - items: - type: integer - properties: - type: object - additionalProperties: - type: string - - PartitionStatisticsFile: - type: object - required: - - snapshot-id - - statistics-path - - file-size-in-bytes - properties: - snapshot-id: - type: integer - format: int64 - statistics-path: - type: string - file-size-in-bytes: - type: integer - format: int64 - - BooleanTypeValue: - type: boolean - example: true - - IntegerTypeValue: - type: integer - example: 42 - - LongTypeValue: - type: integer - format: int64 - example: 9223372036854775807 - - FloatTypeValue: - type: number - format: float - example: 3.14 - - DoubleTypeValue: - type: number - format: double - example: 123.456 - - DecimalTypeValue: - type: string - description: - "Decimal type values are serialized as strings. Decimals with a positive scale serialize as numeric plain - text, while decimals with a negative scale use scientific notation and the exponent will be equal to the - negated scale. For instance, a decimal with a positive scale is '123.4500', with zero scale is '2', - and with a negative scale is '2E+20'" - example: "123.4500" - - StringTypeValue: - type: string - example: "hello" - - UUIDTypeValue: - type: string - format: uuid - pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' - maxLength: 36 - minLength: 36 - description: - "UUID type values are serialized as a 36-character lowercase string in standard UUID format as specified - by RFC-4122" - example: "eb26bdb1-a1d8-4aa6-990e-da940875492c" - - DateTypeValue: - type: string - format: date - description: - "Date type values follow the 'YYYY-MM-DD' ISO-8601 standard date format" - example: "2007-12-03" - - TimeTypeValue: - type: string - description: - "Time type values follow the 'HH:MM:SS.ssssss' ISO-8601 format with microsecond precision" - example: "22:31:08.123456" - - TimestampTypeValue: - type: string - description: - "Timestamp type values follow the 'YYYY-MM-DDTHH:MM:SS.ssssss' ISO-8601 format with microsecond precision" - example: "2007-12-03T10:15:30.123456" - - TimestampTzTypeValue: - type: string - description: - "TimestampTz type values follow the 'YYYY-MM-DDTHH:MM:SS.ssssss+00:00' ISO-8601 format with microsecond precision, - and a timezone offset (+00:00 for UTC)" - example: "2007-12-03T10:15:30.123456+00:00" - - TimestampNanoTypeValue: - type: string - description: - "Timestamp_ns type values follow the 'YYYY-MM-DDTHH:MM:SS.sssssssss' ISO-8601 format with nanosecond precision" - example: "2007-12-03T10:15:30.123456789" - - TimestampTzNanoTypeValue: - type: string - description: - "Timestamp_ns type values follow the 'YYYY-MM-DDTHH:MM:SS.sssssssss+00:00' ISO-8601 format with nanosecond - precision, and a timezone offset (+00:00 for UTC)" - example: "2007-12-03T10:15:30.123456789+00:00" - - FixedTypeValue: - type: string - description: - "Fixed length type values are stored and serialized as an uppercase hexadecimal string - preserving the fixed length" - example: "78797A" - - BinaryTypeValue: - type: string - description: - "Binary type values are stored and serialized as an uppercase hexadecimal string" - example: "78797A" - - CountMap: - type: object - properties: - keys: - type: array - items: - $ref: '#/components/schemas/IntegerTypeValue' - description: "List of integer column ids for each corresponding value" - values: - type: array - items: - $ref: '#/components/schemas/LongTypeValue' - description: "List of Long values, matched to 'keys' by index" - example: - { - "keys": [ 1, 2 ], - "values": [ 100,200 ] - } - - ValueMap: - type: object - properties: - keys: - type: array - items: - $ref: '#/components/schemas/IntegerTypeValue' - description: "List of integer column ids for each corresponding value" - values: - type: array - items: - $ref: '#/components/schemas/PrimitiveTypeValue' - description: "List of primitive type values, matched to 'keys' by index" - example: - { - "keys": [ 1, 2 ], - "values": [ 100, "test" ] - } - - PrimitiveTypeValue: - oneOf: - - $ref: '#/components/schemas/BooleanTypeValue' - - $ref: '#/components/schemas/IntegerTypeValue' - - $ref: '#/components/schemas/LongTypeValue' - - $ref: '#/components/schemas/FloatTypeValue' - - $ref: '#/components/schemas/DoubleTypeValue' - - $ref: '#/components/schemas/DecimalTypeValue' - - $ref: '#/components/schemas/StringTypeValue' - - $ref: '#/components/schemas/UUIDTypeValue' - - $ref: '#/components/schemas/DateTypeValue' - - $ref: '#/components/schemas/TimeTypeValue' - - $ref: '#/components/schemas/TimestampTypeValue' - - $ref: '#/components/schemas/TimestampTzTypeValue' - - $ref: '#/components/schemas/TimestampNanoTypeValue' - - $ref: '#/components/schemas/TimestampTzNanoTypeValue' - - $ref: '#/components/schemas/FixedTypeValue' - - $ref: '#/components/schemas/BinaryTypeValue' - - FileFormat: - type: string - enum: - - avro - - orc - - parquet - - ContentFile: - discriminator: - propertyName: content - mapping: - data: '#/components/schemas/DataFile' - position-deletes: '#/components/schemas/PositionDeleteFile' - equality-deletes: '#/components/schemas/EqualityDeleteFile' - type: object - required: - - spec-id - - content - - file-path - - file-format - - file-size-in-bytes - - record-count - properties: - content: - type: string - file-path: - type: string - file-format: - $ref: '#/components/schemas/FileFormat' - spec-id: - type: integer - partition: - type: array - items: - $ref: '#/components/schemas/PrimitiveTypeValue' - description: - "A list of partition field values ordered based on the fields of the partition spec specified by the - `spec-id`" - example: [1, "bar"] - file-size-in-bytes: - type: integer - format: int64 - description: "Total file size in bytes" - record-count: - type: integer - format: int64 - description: "Number of records in the file" - key-metadata: - allOf: - - $ref: '#/components/schemas/BinaryTypeValue' - description: "Encryption key metadata blob" - split-offsets: - type: array - items: - type: integer - format: int64 - description: "List of splittable offsets" - sort-order-id: - type: integer - - DataFile: - allOf: - - $ref: '#/components/schemas/ContentFile' - type: object - required: - - content - properties: - content: - type: string - enum: [ "data" ] - column-sizes: - allOf: - - $ref: '#/components/schemas/CountMap' - description: "Map of column id to total count, including null and NaN" - value-counts: - allOf: - - $ref: '#/components/schemas/CountMap' - description: "Map of column id to null value count" - null-value-counts: - allOf: - - $ref: '#/components/schemas/CountMap' - description: "Map of column id to null value count" - nan-value-counts: - allOf: - - $ref: '#/components/schemas/CountMap' - description: "Map of column id to number of NaN values in the column" - lower-bounds: - allOf: - - $ref: '#/components/schemas/ValueMap' - description: "Map of column id to lower bound primitive type values" - upper-bounds: - allOf: - - $ref: '#/components/schemas/ValueMap' - description: "Map of column id to upper bound primitive type values" - - PositionDeleteFile: - allOf: - - $ref: '#/components/schemas/ContentFile' - required: - - content - properties: - content: - type: string - enum: [ "position-deletes" ] - - EqualityDeleteFile: - allOf: - - $ref: '#/components/schemas/ContentFile' - required: - - content - properties: - content: - type: string - enum: [ "equality-deletes" ] - equality-ids: - type: array - items: - type: integer - description: "List of equality field IDs" - - ############################# - # Reusable Response Objects # - ############################# - responses: - - OAuthTokenResponse: - description: OAuth2 token response for client credentials or token exchange - content: - application/json: - schema: - $ref: '#/components/schemas/OAuthTokenResponse' - - OAuthErrorResponse: - description: OAuth2 error response - content: - application/json: - schema: - $ref: '#/components/schemas/OAuthError' - - BadRequestErrorResponse: - description: - Indicates a bad request error. It could be caused by an unexpected request - body format or other forms of request validation failure, such as invalid json. - Usually serves application/json content, although in some cases simple text/plain content might - be returned by the server's middleware. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Malformed request", - "type": "BadRequestException", - "code": 400 - } - } - - # Note that this is a representative example response for use as a shorthand in the spec. - # The fields `message` and `type` as indicated here are not presently prescriptive. - UnauthorizedResponse: - description: - Unauthorized. Authentication is required and has failed or has not yet been provided. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Not authorized to make this request", - "type": "NotAuthorizedException", - "code": 401 - } - } - - # Note that this is a representative example response for use as a shorthand in the spec. - # The fields `message` and `type` as indicated here are not presently prescriptive. - ForbiddenResponse: - description: Forbidden. Authenticated user does not have the necessary permissions. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Not authorized to make this request", - "type": "NotAuthorizedException", - "code": 403 - } - } - - # Note that this is a representative example response for use as a shorthand in the spec. - # The fields `message` and `type` as indicated here are not presently prescriptive. - UnsupportedOperationResponse: - description: Not Acceptable / Unsupported Operation. The server does not support this operation. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorModel' - example: { - "error": { - "message": "The server does not support this operation", - "type": "UnsupportedOperationException", - "code": 406 - } - } - - IcebergErrorResponse: - description: JSON wrapper for all error responses (non-2xx) - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "The server does not support this operation", - "type": "UnsupportedOperationException", - "code": 406 - } } - - CreateNamespaceResponse: - description: - Represents a successful call to create a namespace. - Returns the namespace created, as well as any properties that were stored for the namespace, - including those the server might have added. Implementations are not required to support namespace - properties. - content: - application/json: - schema: - $ref: '#/components/schemas/CreateNamespaceResponse' - example: { - "namespace": ["accounting", "tax"], - "properties": { "owner": "Ralph", "created_at": "1452120468" } - } - - GetNamespaceResponse: - description: - Returns a namespace, as well as any properties stored on the namespace if namespace properties - are supported by the server. - content: - application/json: - schema: - $ref: '#/components/schemas/GetNamespaceResponse' - - ListTablesResponse: - description: A list of table identifiers - content: - application/json: - schema: - $ref: '#/components/schemas/ListTablesResponse' - examples: - ListTablesResponseNonEmpty: - $ref: '#/components/examples/ListTablesNonEmptyExample' - ListTablesResponseEmpty: - $ref: '#/components/examples/ListTablesEmptyExample' - - ListNamespacesResponse: - description: A list of namespaces - content: - application/json: - schema: - $ref: '#/components/schemas/ListNamespacesResponse' - examples: - NonEmptyResponse: - $ref: '#/components/examples/ListNamespacesNonEmptyExample' - EmptyResponse: - $ref: '#/components/examples/ListNamespacesEmptyExample' - - AuthenticationTimeoutResponse: - description: - Credentials have timed out. If possible, the client should refresh credentials and retry. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Credentials have timed out", - "type": "AuthenticationTimeoutException", - "code": 419 - } - } - - ServiceUnavailableResponse: - description: - The service is not ready to handle the request. The client should wait and retry. - - - The service may additionally send a Retry-After header to indicate when to retry. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Slow down", - "type": "SlowDownException", - "code": 503 - } - } - - ServerErrorResponse: - description: - 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. - content: - application/json: - schema: - $ref: '#/components/schemas/IcebergErrorResponse' - example: { - "error": { - "message": "Internal Server Error", - "type": "InternalServerError", - "code": 500 - } - } - - UpdateNamespacePropertiesResponse: - description: JSON data response for a synchronous update properties request. - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateNamespacePropertiesResponse' - example: { - "updated": [ "owner" ], - "removed": [ "foo" ], - "missing": [ "bar" ] - } - - CreateTableResponse: - description: Table metadata result after creating a table - content: - application/json: - schema: - $ref: '#/components/schemas/LoadTableResult' - - LoadTableResponse: - description: Table metadata result when loading a table - content: - application/json: - schema: - $ref: '#/components/schemas/LoadTableResult' - - LoadViewResponse: - description: View metadata result when loading a view - content: - application/json: - schema: - $ref: '#/components/schemas/LoadViewResult' - - CommitTableResponse: - description: - Response used when a table is successfully updated. - - The table metadata JSON is returned in the metadata field. The corresponding file location of table metadata must be returned in the metadata-location field. Clients can check whether metadata has changed by comparing metadata locations. - content: - application/json: - schema: - $ref: '#/components/schemas/CommitTableResponse' - - ####################################### - # Common examples of different values # - ####################################### - examples: - - ListTablesEmptyExample: - summary: An empty list for a namespace with no tables - value: { - "identifiers": [ ] - } - - ListNamespacesEmptyExample: - summary: An empty list of namespaces - value: { - "namespaces": [ ] - } - - ListNamespacesNonEmptyExample: - summary: A non-empty list of namespaces - value: { - "namespaces": [ - ["accounting", "tax"], - ["accounting", "credits"] - ] - } - - ListTablesNonEmptyExample: - summary: A non-empty list of table identifiers - value: { - "identifiers": [ - { "namespace": ["accounting", "tax"], "name": "paid" }, - { "namespace": ["accounting", "tax"], "name": "owed" } - ] - } - - MultipartNamespaceAsPathVariable: - summary: A multi-part namespace, as represented in a path parameter - value: "accounting%1Ftax" - - NamespaceAsPathVariable: - summary: A single part namespace, as represented in a path paremeter - value: "accounting" - - NamespaceAlreadyExistsError: - summary: The requested namespace already exists - value: { - "error": { - "message": "The given namespace already exists", - "type": "AlreadyExistsException", - "code": 409 - } - } - - NoSuchTableError: - summary: The requested table does not exist - value: { - "error": { - "message": "The given table does not exist", - "type": "NoSuchTableException", - "code": 404 - } - } - - NoSuchViewError: - summary: The requested view does not exist - value: { - "error": { - "message": "The given view does not exist", - "type": "NoSuchViewException", - "code": 404 - } - } - - NoSuchNamespaceError: - summary: The requested namespace does not exist - value: { - "error": { - "message": "The given namespace does not exist", - "type": "NoSuchNamespaceException", - "code": 404 - } - } - - RenameTableSameNamespace: - summary: Rename a table in the same namespace - value: { - "source": { "namespace": ["accounting", "tax"], "name": "paid" }, - "destination": { "namespace": ["accounting", "tax"], "name": "owed" } - } - - RenameViewSameNamespace: - summary: Rename a view in the same namespace - value: { - "source": { "namespace": [ "accounting", "tax" ], "name": "paid-view" }, - "destination": { "namespace": [ "accounting", "tax" ], "name": "owed-view" } - } - - TableAlreadyExistsError: - summary: The requested table identifier already exists - value: { - "error": { - "message": "The given table already exists", - "type": "AlreadyExistsException", - "code": 409 - } - } - - ViewAlreadyExistsError: - summary: The requested view identifier already exists - value: { - "error": { - "message": "The given view already exists", - "type": "AlreadyExistsException", - "code": 409 - } - } - - # This is an example response and is not meant to be prescriptive regarding the message or type. - UnprocessableEntityDuplicateKey: - summary: - The request body either has the same key multiple times in what should be a map with unique keys - or the request body has keys in two or more fields which should be disjoint sets. - value: { - "error": { - "message": "The request cannot be processed as there is a key present multiple times", - "type": "UnprocessableEntityException", - "code": 422 - } - } - - UpdateAndRemoveNamespacePropertiesRequest: - summary: An update namespace properties request with both properties to remove and properties to upsert. - value: { - "removals": [ "foo", "bar" ], - "updates": { "owner": "Raoul" } - } - - securitySchemes: - OAuth2: - type: oauth2 - description: - This scheme is used for OAuth2 authorization. - - - For unauthorized requests, services should return an appropriate 401 or - 403 response. Implementations must not return altered success (200) - responses when a request is unauthenticated or unauthorized. - - If a separate authorization server is used, substitute the tokenUrl with - the full token path of the external authorization server, and use the - resulting token to access the resources defined in the spec. - flows: - clientCredentials: - tokenUrl: /v1/oauth/tokens - scopes: - catalog: Allows interacting with the Config and Catalog APIs - BearerAuth: - type: http - scheme: bearer \ No newline at end of file diff --git a/site/layouts/partials/favicons.html b/site/layouts/partials/favicons.html new file mode 100644 index 000000000..dc89bbb13 --- /dev/null +++ b/site/layouts/partials/favicons.html @@ -0,0 +1,26 @@ + + + + + + + \ No newline at end of file diff --git a/site/static/favicons/android-chrome-192x192.png b/site/static/favicons/android-chrome-192x192.png new file mode 100644 index 000000000..8f63927ac Binary files /dev/null and b/site/static/favicons/android-chrome-192x192.png differ diff --git a/site/static/favicons/android-chrome-512x512.png b/site/static/favicons/android-chrome-512x512.png new file mode 100644 index 000000000..2436a6fba Binary files /dev/null and b/site/static/favicons/android-chrome-512x512.png differ diff --git a/site/static/favicons/android-chrome-maskable-192x192.png b/site/static/favicons/android-chrome-maskable-192x192.png new file mode 100644 index 000000000..8f63927ac Binary files /dev/null and b/site/static/favicons/android-chrome-maskable-192x192.png differ diff --git a/site/static/favicons/android-chrome-maskable-512x512.png b/site/static/favicons/android-chrome-maskable-512x512.png new file mode 100644 index 000000000..2436a6fba Binary files /dev/null and b/site/static/favicons/android-chrome-maskable-512x512.png differ diff --git a/site/static/favicons/apple-touch-icon.png b/site/static/favicons/apple-touch-icon.png new file mode 100644 index 000000000..fe48ffe3f Binary files /dev/null and b/site/static/favicons/apple-touch-icon.png differ diff --git a/site/static/favicons/favicon.ico b/site/static/favicons/favicon.ico new file mode 100644 index 000000000..6ca7eef00 Binary files /dev/null and b/site/static/favicons/favicon.ico differ diff --git a/site/static/favicons/favicon.svg b/site/static/favicons/favicon.svg new file mode 100644 index 000000000..bd0a9346c --- /dev/null +++ b/site/static/favicons/favicon.svg @@ -0,0 +1,4 @@ + + + + diff --git a/site/static/images/polaris-brandmark.png b/site/static/images/polaris-brandmark.png deleted file mode 100644 index 6573f7a61..000000000 Binary files a/site/static/images/polaris-brandmark.png and /dev/null differ diff --git a/site/static/images/Polaris-Catalog-BLOG-symmetrical-subhead.png b/site/static/img/Polaris-Catalog-BLOG-symmetrical-subhead.png similarity index 100% rename from site/static/images/Polaris-Catalog-BLOG-symmetrical-subhead.png rename to site/static/img/Polaris-Catalog-BLOG-symmetrical-subhead.png diff --git a/site/static/images/apache-incubator.svg b/site/static/img/apache-incubator.svg similarity index 100% rename from site/static/images/apache-incubator.svg rename to site/static/img/apache-incubator.svg diff --git a/site/static/openapi/polaris-management-service.yml b/site/static/openapi/polaris-management-service.yml deleted file mode 100644 index a11f9e04e..000000000 --- a/site/static/openapi/polaris-management-service.yml +++ /dev/null @@ -1,1346 +0,0 @@ -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at - -# http://www.apache.org/licenses/LICENSE-2.0 - -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - - -openapi: 3.0.3 -info: - title: Polaris Management Service - version: 0.0.1 - description: - Defines the management APIs for using Polaris to create and manage Iceberg catalogs and their principals -servers: - - url: "{scheme}://{host}/api/management/v1" - description: Server URL when the port can be inferred from the scheme - variables: - scheme: - description: The scheme of the URI, either http or https. - default: https - host: - description: The host address for the specified server - default: localhost -# All routes are currently configured using an Authorization header. -security: - - OAuth2: [] - -paths: - /catalogs: - get: - operationId: listCatalogs - description: List all catalogs in this polaris service - responses: - 200: - description: List of catalogs in the polaris service - content: - application/json: - schema: - $ref: "#/components/schemas/Catalogs" - 403: - description: "The caller does not have permission to list catalog details" - post: - operationId: createCatalog - description: Add a new Catalog - requestBody: - description: The Catalog to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateCatalogRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The caller does not have permission to create a catalog" - 404: - description: "The catalog does not exist" - 409: - description: "A catalog with the specified name already exists" - - /catalogs/{catalogName}: - parameters: - - name: catalogName - in: path - description: The name of the catalog - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: getCatalog - description: Get the details of a catalog - responses: - 200: - description: The catalog details - content: - application/json: - schema: - $ref: "#/components/schemas/Catalog" - 403: - description: "The caller does not have permission to read catalog details" - 404: - description: "The catalog does not exist" - - put: - operationId: updateCatalog - description: Update an existing catalog - requestBody: - description: The catalog details to use in the update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateCatalogRequest" - responses: - 200: - description: The catalog details - content: - application/json: - schema: - $ref: "#/components/schemas/Catalog" - 403: - description: "The caller does not have permission to update catalog details" - 404: - description: "The catalog does not exist" - 409: - description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" - - delete: - operationId: deleteCatalog - description: 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. - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to delete a catalog" - 404: - description: "The catalog does not exist" - - /principals: - get: - operationId: listPrincipals - description: List the principals for the current catalog - responses: - 200: - description: List of principals for this catalog - content: - application/json: - schema: - $ref: "#/components/schemas/Principals" - 403: - description: "The caller does not have permission to list catalog admins" - 404: - description: "The catalog does not exist" - - post: - operationId: createPrincipal - description: Create a principal - requestBody: - description: The principal to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreatePrincipalRequest" - responses: - 201: - description: "Successful response" - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalWithCredentials" - 403: - description: "The caller does not have permission to add a principal" - - /principals/{principalName}: - parameters: - - name: principalName - in: path - description: The principal name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: getPrincipal - description: Get the principal details - responses: - 200: - description: The requested principal - content: - application/json: - schema: - $ref: "#/components/schemas/Principal" - 403: - description: "The caller does not have permission to get principal details" - 404: - description: "The catalog or principal does not exist" - - put: - operationId: updatePrincipal - description: Update an existing principal - requestBody: - description: The principal details to use in the update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdatePrincipalRequest" - responses: - 200: - description: The updated principal - content: - application/json: - schema: - $ref: "#/components/schemas/Principal" - 403: - description: "The caller does not have permission to update principal details" - 404: - description: "The principal does not exist" - 409: - description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" - - delete: - operationId: deletePrincipal - description: Remove a principal from polaris - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to delete a principal" - 404: - description: "The principal does not exist" - - /principals/{principalName}/rotate: - parameters: - - name: principalName - in: path - description: The user name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - post: - operationId: rotateCredentials - description: 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. - responses: - 200: - description: The principal details along with the newly rotated credentials - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalWithCredentials" - 403: - description: "The caller does not have permission to rotate credentials" - 404: - description: "The principal does not exist" - - /principals/{principalName}/principal-roles: - parameters: - - name: principalName - in: path - description: The name of the target principal - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listPrincipalRolesAssigned - description: List the roles assigned to the principal - responses: - 200: - description: List of roles assigned to this principal - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRoles" - 403: - description: "The caller does not have permission to list roles" - 404: - description: "The principal or catalog does not exist" - - put: - operationId: assignPrincipalRole - description: Add a role to the principal - requestBody: - description: The principal role to assign - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GrantPrincipalRoleRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The caller does not have permission to add assign a role to the principal" - 404: - description: "The catalog, the principal, or the role does not exist" - - /principals/{principalName}/principal-roles/{principalRoleName}: - parameters: - - name: principalName - in: path - description: The name of the target principal - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: principalRoleName - in: path - description: The name of the role - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - delete: - operationId: revokePrincipalRole - description: Remove a role from a catalog principal - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to remove a role from the principal" - 404: - description: "The catalog or principal does not exist" - - /principal-roles: - get: - operationId: listPrincipalRoles - description: List the principal roles - responses: - 200: - description: List of principal roles - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRoles" - 403: - description: "The caller does not have permission to list principal roles" - 404: - description: "The catalog does not exist" - - post: - operationId: createPrincipalRole - description: Create a principal role - requestBody: - description: The principal to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreatePrincipalRoleRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The caller does not have permission to add a principal role" - - /principal-roles/{principalRoleName}: - parameters: - - name: principalRoleName - in: path - description: The principal role name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: getPrincipalRole - description: Get the principal role details - responses: - 200: - description: The requested principal role - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRole" - 403: - description: "The caller does not have permission to get principal role details" - 404: - description: "The principal role does not exist" - - put: - operationId: updatePrincipalRole - description: Update an existing principalRole - requestBody: - description: The principalRole details to use in the update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdatePrincipalRoleRequest" - responses: - 200: - description: The updated principal role - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRole" - 403: - description: "The caller does not have permission to update principal role details" - 404: - description: "The principal role does not exist" - 409: - description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" - - delete: - operationId: deletePrincipalRole - description: Remove a principal role from polaris - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to delete a principal role" - 404: - description: "The principal role does not exist" - - /principal-roles/{principalRoleName}/principals: - parameters: - - name: principalRoleName - in: path - description: The principal role name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listAssigneePrincipalsForPrincipalRole - description: List the Principals to whom the target principal role has been assigned - responses: - 200: - description: List the Principals to whom the target principal role has been assigned - content: - application/json: - schema: - $ref: "#/components/schemas/Principals" - 403: - description: "The caller does not have permission to list principals" - 404: - description: "The principal role does not exist" - - /principal-roles/{principalRoleName}/catalog-roles/{catalogName}: - parameters: - - name: principalRoleName - in: path - description: The principal role name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogName - in: path - required: true - description: The name of the catalog where the catalogRoles reside - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listCatalogRolesForPrincipalRole - description: Get the catalog roles mapped to the principal role - responses: - 200: - description: The list of catalog roles mapped to the principal role - content: - application/json: - schema: - $ref: "#/components/schemas/CatalogRoles" - 403: - description: "The caller does not have permission to list catalog roles" - 404: - description: "The principal role does not exist" - - put: - operationId: assignCatalogRoleToPrincipalRole - description: Assign a catalog role to a principal role - requestBody: - description: The principal to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GrantCatalogRoleRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The caller does not have permission to assign a catalog role" - - /principal-roles/{principalRoleName}/catalog-roles/{catalogName}/{catalogRoleName}: - parameters: - - name: principalRoleName - in: path - description: The principal role name - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogName - in: path - description: The name of the catalog that contains the role to revoke - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogRoleName - in: path - description: The name of the catalog role that should be revoked - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - delete: - operationId: revokeCatalogRoleFromPrincipalRole - description: Remove a catalog role from a principal role - responses: - 204: - description: "Success, no content" - 403: - description: "The caller does not have permission to revoke a catalog role" - 404: - description: "The principal role does not exist" - - /catalogs/{catalogName}/catalog-roles: - parameters: - - name: catalogName - in: path - description: The catalog for which we are reading/updating roles - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listCatalogRoles - description: List existing roles in the catalog - responses: - 200: - description: The list of roles that exist in this catalog - content: - application/json: - schema: - $ref: "#/components/schemas/CatalogRoles" - post: - operationId: createCatalogRole - description: Create a new role in the catalog - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/CreateCatalogRoleRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The principal is not authorized to create roles" - 404: - description: "The catalog does not exist" - - /catalogs/{catalogName}/catalog-roles/{catalogRoleName}: - parameters: - - name: catalogName - in: path - description: The catalog for which we are retrieving roles - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogRoleName - in: path - description: The name of the role - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: getCatalogRole - description: Get the details of an existing role - responses: - 200: - description: The specified role details - content: - application/json: - schema: - $ref: "#/components/schemas/CatalogRole" - 403: - description: "The principal is not authorized to read role data" - 404: - description: "The catalog or the role does not exist" - - put: - operationId: updateCatalogRole - description: Update an existing role in the catalog - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateCatalogRoleRequest" - responses: - 200: - description: The specified role details - content: - application/json: - schema: - $ref: "#/components/schemas/CatalogRole" - 403: - description: "The principal is not authorized to update roles" - 404: - description: "The catalog or the role does not exist" - 409: - description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" - - delete: - operationId: deleteCatalogRole - description: Delete an existing role from the catalog. All associated grants will also be deleted - responses: - 204: - description: "Success, no content" - 403: - description: "The principal is not authorized to delete roles" - 404: - description: "The catalog or the role does not exist" - - /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/principal-roles: - parameters: - - name: catalogName - in: path - required: true - description: The name of the catalog where the catalog role resides - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogRoleName - in: path - required: true - description: The name of the catalog role - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listAssigneePrincipalRolesForCatalogRole - description: List the PrincipalRoles to which the target catalog role has been assigned - responses: - 200: - description: List the PrincipalRoles to which the target catalog role has been assigned - content: - application/json: - schema: - $ref: "#/components/schemas/PrincipalRoles" - 403: - description: "The caller does not have permission to list principal roles" - 404: - description: "The catalog or catalog role does not exist" - - /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants: - parameters: - - name: catalogName - in: path - required: true - description: The name of the catalog where the role will receive the grant - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - - name: catalogRoleName - in: path - required: true - description: The name of the role receiving the grant (must exist) - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - get: - operationId: listGrantsForCatalogRole - description: List the grants the catalog role holds - responses: - 200: - description: List of all grants given to the role in this catalog - content: - application/json: - schema: - $ref: "#/components/schemas/GrantResources" - put: - operationId: addGrantToCatalogRole - description: Add a new grant to the catalog role - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/AddGrantRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The principal is not authorized to create grants" - 404: - description: "The catalog or the role does not exist" - post: - operationId: revokeGrantFromCatalogRole - description: - 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. - parameters: - - name: cascade - in: query - schema: - type: boolean - default: false - description: If true, the grant revocation cascades to all subresources. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/RevokeGrantRequest" - responses: - 201: - description: "Successful response" - 403: - description: "The principal is not authorized to create grants" - 404: - description: "The catalog or the role does not exist" - -components: - securitySchemes: - OAuth2: - type: oauth2 - description: Uses OAuth 2 with client credentials flow - flows: - implicit: - authorizationUrl: "{scheme}://{host}/api/v1/oauth/tokens" - scopes: {} - - schemas: - Catalogs: - type: object - description: A list of Catalog objects - properties: - catalogs: - type: array - items: - $ref: "#/components/schemas/Catalog" - required: - - catalogs - - CreateCatalogRequest: - type: object - description: Request to create a new catalog - properties: - catalog: - $ref: "#/components/schemas/Catalog" - required: - - catalog - - Catalog: - type: object - description: 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 - properties: - type: - type: string - enum: - - INTERNAL - - EXTERNAL - description: the type of catalog - internal or external - default: INTERNAL - name: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - description: The name of the catalog - properties: - type: object - properties: - default-base-location: - type: string - additionalProperties: - type: string - required: - - default-base-location - createTimestamp: - type: integer - format: "int64" - description: The creation time represented as unix epoch timestamp in milliseconds - lastUpdateTimestamp: - type: integer - format: "int64" - description: The last update time represented as unix epoch timestamp in milliseconds - entityVersion: - type: integer - description: The version of the catalog object used to determine if the catalog metadata has changed - storageConfigInfo: - $ref: "#/components/schemas/StorageConfigInfo" - required: - - name - - type - - storageConfigInfo - - properties - discriminator: - propertyName: type - mapping: - INTERNAL: "#/components/schemas/PolarisCatalog" - EXTERNAL: "#/components/schemas/ExternalCatalog" - - - PolarisCatalog: - type: object - allOf: - - $ref: "#/components/schemas/Catalog" - description: The base catalog type - this contains all the fields necessary to construct an INTERNAL catalog - - ExternalCatalog: - description: An externally managed catalog - type: object - allOf: - - $ref: "#/components/schemas/Catalog" - - type: object - properties: - remoteUrl: - type: string - description: URL to the remote catalog API - - StorageConfigInfo: - type: object - description: A storage configuration used by catalogs - properties: - storageType: - type: string - enum: - - S3 - - GCS - - AZURE - - FILE - description: The cloud provider type this storage is built on. FILE is supported for testing purposes only - allowedLocations: - type: array - items: - type: string - example: "For AWS [s3://bucketname/prefix/], for AZURE [abfss://container@storageaccount.blob.core.windows.net/prefix/], for GCP [gs://bucketname/prefix/]" - required: - - storageType - discriminator: - propertyName: storageType - mapping: - S3: "#/components/schemas/AwsStorageConfigInfo" - AZURE: "#/components/schemas/AzureStorageConfigInfo" - GCS: "#/components/schemas/GcpStorageConfigInfo" - FILE: "#/components/schemas/FileStorageConfigInfo" - - AwsStorageConfigInfo: - type: object - description: aws storage configuration info - allOf: - - $ref: '#/components/schemas/StorageConfigInfo' - properties: - roleArn: - type: string - description: the aws role arn that grants privileges on the S3 buckets - example: "arn:aws:iam::123456789001:principal/abc1-b-self1234" - externalId: - type: string - description: an optional external id used to establish a trust relationship with AWS in the trust policy - userArn: - type: string - description: the aws user arn used to assume the aws role - example: "arn:aws:iam::123456789001:user/abc1-b-self1234" - required: - - roleArn - - AzureStorageConfigInfo: - type: object - description: azure storage configuration info - allOf: - - $ref: '#/components/schemas/StorageConfigInfo' - properties: - tenantId: - type: string - description: the tenant id that the storage accounts belong to - multiTenantAppName: - type: string - description: the name of the azure client application - consentUrl: - type: string - description: URL to the Azure permissions request page - required: - - tenantId - - GcpStorageConfigInfo: - type: object - description: gcp storage configuration info - allOf: - - $ref: '#/components/schemas/StorageConfigInfo' - properties: - gcsServiceAccount: - type: string - description: a Google cloud storage service account - - FileStorageConfigInfo: - type: object - description: gcp storage configuration info - allOf: - - $ref: '#/components/schemas/StorageConfigInfo' - - UpdateCatalogRequest: - description: Updates to apply to a Catalog - type: object - properties: - currentEntityVersion: - type: integer - description: 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. - properties: - type: object - additionalProperties: - type: string - storageConfigInfo: - $ref: "#/components/schemas/StorageConfigInfo" - - Principals: - description: A list of Principals - type: object - properties: - principals: - type: array - items: - $ref: "#/components/schemas/Principal" - required: - - principals - - PrincipalWithCredentials: - description: A user with its client id and secret. This type is returned when a new principal is created or when its - credentials are rotated - type: object - properties: - principal: - $ref: "#/components/schemas/Principal" - credentials: - type: object - properties: - clientId: - type: string - clientSecret: - type: string - format: password - required: - - principal - - credentials - - CreatePrincipalRequest: - type: object - properties: - principal: - $ref: '#/components/schemas/Principal' - credentialRotationRequired: - type: boolean - description: If true, the initial credentials can only be used to call rotateCredentials - - Principal: - description: A Polaris principal. - type: object - properties: - name: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - clientId: - type: string - description: The output-only OAuth clientId associated with this principal if applicable - properties: - type: object - additionalProperties: - type: string - createTimestamp: - type: integer - format: "int64" - lastUpdateTimestamp: - type: integer - format: "int64" - entityVersion: - type: integer - description: The version of the principal object used to determine if the principal metadata has changed - required: - - name - - UpdatePrincipalRequest: - description: Updates to apply to a Principal - type: object - properties: - currentEntityVersion: - type: integer - description: 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. - properties: - type: object - additionalProperties: - type: string - required: - - currentEntityVersion - - properties - - PrincipalRoles: - type: object - properties: - roles: - type: array - items: - $ref: "#/components/schemas/PrincipalRole" - required: - - roles - - GrantPrincipalRoleRequest: - type: object - properties: - principalRole: - $ref: '#/components/schemas/PrincipalRole' - - CreatePrincipalRoleRequest: - type: object - properties: - principalRole: - $ref: '#/components/schemas/PrincipalRole' - - PrincipalRole: - type: object - properties: - name: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - description: The name of the role - properties: - type: object - additionalProperties: - type: string - createTimestamp: - type: integer - format: "int64" - lastUpdateTimestamp: - type: integer - format: "int64" - entityVersion: - type: integer - description: The version of the principal role object used to determine if the principal role metadata has changed - required: - - name - - UpdatePrincipalRoleRequest: - description: Updates to apply to a Principal Role - type: object - properties: - currentEntityVersion: - type: integer - description: 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. - properties: - type: object - additionalProperties: - type: string - required: - - currentEntityVersion - - properties - - CatalogRoles: - type: object - properties: - roles: - type: array - items: - $ref: "#/components/schemas/CatalogRole" - description: The list of catalog roles - required: - - roles - - GrantCatalogRoleRequest: - type: object - properties: - catalogRole: - $ref: '#/components/schemas/CatalogRole' - - CreateCatalogRoleRequest: - type: object - properties: - catalogRole: - $ref: '#/components/schemas/CatalogRole' - - CatalogRole: - type: object - properties: - name: - type: string - minLength: 1 - maxLength: 256 - pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' - description: The name of the role - properties: - type: object - additionalProperties: - type: string - createTimestamp: - type: integer - format: "int64" - lastUpdateTimestamp: - type: integer - format: "int64" - entityVersion: - type: integer - description: The version of the catalog role object used to determine if the catalog role metadata has changed - required: - - name - - UpdateCatalogRoleRequest: - description: Updates to apply to a Catalog Role - type: object - properties: - currentEntityVersion: - type: integer - description: 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. - properties: - type: object - additionalProperties: - type: string - required: - - currentEntityVersion - - properties - - ViewPrivilege: - type: string - enum: - - CATALOG_MANAGE_ACCESS - - VIEW_CREATE - - VIEW_DROP - - VIEW_LIST - - VIEW_READ_PROPERTIES - - VIEW_WRITE_PROPERTIES - - VIEW_FULL_METADATA - - TablePrivilege: - type: string - enum: - - CATALOG_MANAGE_ACCESS - - TABLE_DROP - - TABLE_LIST - - TABLE_READ_PROPERTIES - - VIEW_READ_PROPERTIES - - TABLE_WRITE_PROPERTIES - - TABLE_READ_DATA - - TABLE_WRITE_DATA - - TABLE_FULL_METADATA - - NamespacePrivilege: - type: string - enum: - - CATALOG_MANAGE_ACCESS - - CATALOG_MANAGE_CONTENT - - CATALOG_MANAGE_METADATA - - NAMESPACE_CREATE - - TABLE_CREATE - - VIEW_CREATE - - NAMESPACE_DROP - - TABLE_DROP - - VIEW_DROP - - NAMESPACE_LIST - - TABLE_LIST - - VIEW_LIST - - NAMESPACE_READ_PROPERTIES - - TABLE_READ_PROPERTIES - - VIEW_READ_PROPERTIES - - NAMESPACE_WRITE_PROPERTIES - - TABLE_WRITE_PROPERTIES - - VIEW_WRITE_PROPERTIES - - TABLE_READ_DATA - - TABLE_WRITE_DATA - - NAMESPACE_FULL_METADATA - - TABLE_FULL_METADATA - - VIEW_FULL_METADATA - - CatalogPrivilege: - type: string - enum: - - CATALOG_MANAGE_ACCESS - - CATALOG_MANAGE_CONTENT - - CATALOG_MANAGE_METADATA - - CATALOG_READ_PROPERTIES - - CATALOG_WRITE_PROPERTIES - - NAMESPACE_CREATE - - TABLE_CREATE - - VIEW_CREATE - - NAMESPACE_DROP - - TABLE_DROP - - VIEW_DROP - - NAMESPACE_LIST - - TABLE_LIST - - VIEW_LIST - - NAMESPACE_READ_PROPERTIES - - TABLE_READ_PROPERTIES - - VIEW_READ_PROPERTIES - - NAMESPACE_WRITE_PROPERTIES - - TABLE_WRITE_PROPERTIES - - VIEW_WRITE_PROPERTIES - - TABLE_READ_DATA - - TABLE_WRITE_DATA - - NAMESPACE_FULL_METADATA - - TABLE_FULL_METADATA - - VIEW_FULL_METADATA - - AddGrantRequest: - type: object - properties: - grant: - $ref: '#/components/schemas/GrantResource' - - RevokeGrantRequest: - type: object - properties: - grant: - $ref: '#/components/schemas/GrantResource' - - ViewGrant: - allOf: - - $ref: '#/components/schemas/GrantResource' - - type: object - properties: - namespace: - type: array - items: - type: string - viewName: - type: string - minLength: 1 - maxLength: 256 - privilege: - $ref: '#/components/schemas/ViewPrivilege' - required: - - namespace - - viewName - - privilege - - TableGrant: - allOf: - - $ref: '#/components/schemas/GrantResource' - - type: object - properties: - namespace: - type: array - items: - type: string - tableName: - type: string - minLength: 1 - maxLength: 256 - privilege: - $ref: '#/components/schemas/TablePrivilege' - required: - - namespace - - tableName - - privilege - - NamespaceGrant: - allOf: - - $ref: '#/components/schemas/GrantResource' - - type: object - properties: - namespace: - type: array - items: - type: string - privilege: - $ref: '#/components/schemas/NamespacePrivilege' - required: - - namespace - - privilege - - - CatalogGrant: - allOf: - - $ref: '#/components/schemas/GrantResource' - - type: object - properties: - privilege: - $ref: '#/components/schemas/CatalogPrivilege' - required: - - privilege - - GrantResource: - type: object - discriminator: - propertyName: type - mapping: - catalog: '#/components/schemas/CatalogGrant' - namespace: '#/components/schemas/NamespaceGrant' - table: '#/components/schemas/TableGrant' - view: '#/components/schemas/ViewGrant' - properties: - type: - type: string - enum: - - catalog - - namespace - - table - - view - required: - - type - - GrantResources: - type: object - properties: - grants: - type: array - items: - $ref: "#/components/schemas/GrantResource" - required: - - grants