Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
---
openapi: 3.0.3
info:
title: Nessie API
description: |-
Transactional Catalog for Data Lakes
* Git-inspired data version control
* Cross-table transactions and visibility
* Works with Apache Iceberg tables
contact:
name: Project Nessie
url: https://projectnessie.org
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 0.97.0
servers:
- url: "{scheme}://{host}:{port}/{basePath}"
description: Nessie REST API endpoint.
variables:
scheme:
default: http
description: "The scheme of the URI, either http or https."
host:
default: localhost
description: The host address for the specified server
port:
default: "19120"
description: The port used when addressing the host
basePath:
default: ""
description: |
Nessie Core API base path.
When using the Swagger UI from Quarkus from the `/q/swagger-ui` URL, leave the `basePath` value empty.
Otherwise use `/api/` for `basePath`.
tags:
- name: v1
description: "End points from the legacy v1 API, deprecated"
- name: v2
description: End points from the Nessie v2 API
paths:
/v1/config:
get:
tags:
- v1
summary: List all configuration settings
operationId: getConfig
responses:
default:
description: Configuration settings
content:
application/json:
schema:
$ref: "#/components/schemas/NessieConfiguration_V1"
examples:
nessieConfigV1:
$ref: "#/components/examples/nessieConfigV1"
"401":
description: Invalid credentials provided
"400":
description: Unknown Error
/v1/contents:
post:
tags:
- v1
summary: Get multiple objects' content.
description: |-
Similar to 'getContent', but takes multiple 'ContentKey's and returns the content-values for the one or more content-keys in a named-reference (a branch or tag).
If the table-metadata is tracked globally (Iceberg), Nessie returns a 'Content' object, that contains the most up-to-date part for the globally tracked part (Iceberg: table-metadata) plus the per-Nessie-reference/hash specific part (Iceberg: snapshot-ID,schema-ID, partition-spec-ID, default-sort-order-ID).
operationId: getMultipleContents
parameters:
- name: hashOnRef
in: query
description: a particular hash on the given ref
schema:
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
- name: ref
in: query
description: Reference to use. Defaults to default branch if not provided.
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
requestBody:
description: Keys to retrieve.
content:
application/json:
schema:
$ref: "#/components/schemas/GetMultipleContentsRequest"
examples:
multiGetRequest:
$ref: "#/components/examples/multiGetRequest"
responses:
"200":
description: Retrieved successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/GetMultipleContentsResponse_V1"
examples:
multiGetResponse:
$ref: "#/components/examples/multiGetResponse"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or read object content
for a key
"404":
description: Provided ref doesn't exists
/v1/contents/{key}:
get:
tags:
- v1
summary: Get object content associated with a key.
description: |-
This operation returns the content-value for a content-key in a named-reference (a branch or tag).
If the table-metadata is tracked globally (Iceberg), Nessie returns a 'Content' object, that contains the most up-to-date part for the globally tracked part (Iceberg: table-metadata) plus the per-Nessie-reference/hash specific part (Iceberg: snapshot-id, schema-id, partition-spec-id, default-sort-order-id).
operationId: getContent
parameters:
- name: key
in: path
description: object name to search for
required: true
schema:
type: string
examples:
ContentKeyGet:
$ref: "#/components/examples/ContentKeyGet"
- name: hashOnRef
in: query
description: a particular hash on the given ref
schema:
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
- name: ref
in: query
description: Reference to use. Defaults to default branch if not provided.
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
responses:
"200":
description: Information for table
content:
application/json:
schema:
$ref: "#/components/schemas/Content_V1"
examples:
iceberg:
$ref: "#/components/examples/iceberg"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or read object content
for a key
"404":
description: Table not found on ref
/v1/diffs/{fromRefWithHash}...{toRefWithHash}:
get:
tags:
- v1
summary: Get a diff for two given references
description: "The URL pattern is basically 'from' and 'to' separated by '...'\
\ (three dots). 'from' and 'to' must start with a reference name, optionally\
\ followed by hash on that reference, the hash prefixed with the'*' character.\n\
\nExamples: \n diffs/main...myBranch\n diffs/main...myBranch\\*1234567890123456\n\
\ diffs/main\\*1234567890123456...myBranch\n diffs/main\\*1234567890123456...myBranch\\\
*1234567890123456\n"
operationId: getDiff
parameters:
- name: fromRefWithHash
in: path
description: The 'from' reference (and optional hash) to start the diff from
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
refForDiffWithHash:
$ref: "#/components/examples/refForDiffWithHash"
- name: toRefWithHash
in: path
description: The 'to' reference (and optional hash) to end the diff at.
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
refForDiffWithHash:
$ref: "#/components/examples/refForDiffWithHash"
responses:
"200":
description: Returned diff for the given references.
content:
application/json:
schema:
$ref: "#/components/schemas/DiffResponse_V1"
examples:
diffResponse:
$ref: "#/components/examples/diffResponse"
"400":
description: "Invalid input, fromRef/toRef name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given fromRef/toRef
"404":
description: fromRef/toRef not found
/v1/namespaces/namespace/{ref}/{name}:
get:
tags:
- v1
summary: Retrieves a Namespace
operationId: getNamespace
parameters:
- name: name
in: path
description: the name of the namespace
required: true
schema:
$ref: "#/components/schemas/Namespace"
examples:
namespaceName:
$ref: "#/components/examples/namespaceName"
- name: ref
in: path
description: name of ref to fetch
required: true
schema:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: hashOnRef
in: query
description: a particular hash on the given ref
schema:
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
responses:
"200":
description: Returned Namespace.
content:
application/json:
schema:
$ref: "#/components/schemas/Namespace_V1"
examples:
namespace:
$ref: "#/components/examples/namespace"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to retrieve namespace
"404":
description: Reference or Namespace not found
put:
tags:
- v1
summary: Creates a Namespace
operationId: createNamespace
parameters:
- name: name
in: path
description: the name of the namespace
required: true
schema:
$ref: "#/components/schemas/Namespace"
examples:
namespaceName:
$ref: "#/components/examples/namespaceName"
- name: ref
in: path
description: name of ref to fetch
required: true
schema:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: hashOnRef
in: query
description: a particular hash on the given ref
schema:
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Namespace"
responses:
"200":
description: Returned Namespace.
content:
application/json:
schema:
$ref: "#/components/schemas/Namespace_V1"
examples:
namespace:
$ref: "#/components/examples/namespace"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to create namespace
"404":
description: Reference not found
"409":
description: Namespace already exists
post:
tags:
- v1
operationId: updateProperties
parameters:
- name: name
in: path
description: the name of the namespace
required: true
schema:
$ref: "#/components/schemas/Namespace"
examples:
namespaceName:
$ref: "#/components/examples/namespaceName"
- name: ref
in: path
description: name of ref to fetch
required: true
schema:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: hashOnRef
in: query
description: a particular hash on the given ref
schema:
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
requestBody:
description: Namespace properties to update/delete.
content:
application/json:
schema:
$ref: "#/components/schemas/NamespaceUpdate"
examples:
namespaceUpdate:
$ref: "#/components/examples/namespaceUpdate"
responses:
"200":
description: Updates namespace properties for the given namespace.
"401":
description: Invalid credentials provided
"403":
description: Not allowed to update namespace properties
"404":
description: Reference or Namespace not found
delete:
tags:
- v1
summary: Deletes a Namespace
operationId: deleteNamespace
parameters:
- name: name
in: path
description: the name of the namespace
required: true
schema:
$ref: "#/components/schemas/Namespace"
examples:
namespaceName:
$ref: "#/components/examples/namespaceName"
- name: ref
in: path
description: name of ref to fetch
required: true
schema:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: hashOnRef
in: query
description: a particular hash on the given ref
schema:
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
responses:
"200":
description: Namespace successfully deleted.
"401":
description: Invalid credentials provided
"403":
description: Not allowed to delete namespace
"404":
description: Reference or Namespace not found
"409":
description: Namespace not empty
/v1/namespaces/{ref}:
get:
tags:
- v1
operationId: getNamespaces
parameters:
- name: ref
in: path
description: name of ref to fetch
required: true
schema:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: hashOnRef
in: query
description: a particular hash on the given ref
schema:
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
- name: name
in: query
description: the name of the namespace
schema:
$ref: "#/components/schemas/Namespace"
examples:
namespaceName:
$ref: "#/components/examples/namespaceName"
emptyNamespaceName:
$ref: "#/components/examples/emptyNamespaceName"
responses:
"200":
description: Returns Namespaces with a given prefix.
content:
application/json:
schema:
$ref: "#/components/schemas/GetNamespacesResponse_V1"
examples:
namespacesResponse:
$ref: "#/components/examples/namespacesResponse"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to retrieve namespaces
"404":
description: Reference not found
/v1/trees:
get:
tags:
- v1
summary: Get all references
operationId: getAllReferences
parameters:
- name: fetch
in: query
description: |-
Specify how much information to be returned. Will fetch additional metadata for references if set to 'ALL'.
A returned Branch instance will have the following information:
- numCommitsAhead (number of commits ahead of the default branch)
- numCommitsBehind (number of commits behind the default branch)
- commitMetaOfHEAD (the commit metadata of the HEAD commit)
- commonAncestorHash (the hash of the common ancestor in relation to the default branch).
- numTotalCommits (the total number of commits in this reference).
A returned Tag instance will only contain the 'commitMetaOfHEAD' and 'numTotalCommits' fields.
Note that computing & fetching additional metadata might be computationally expensive on the server-side, so this flag should be used with care.
schema:
$ref: "#/components/schemas/FetchOption"
- name: filter
in: query
description: |-
A Common Expression Language (CEL) expression. An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
Usable variables within the expression are:
- ref (Reference) describes the reference, with fields name (String), hash (String), metadata (ReferenceMetadata)
- metadata (ReferenceMetadata) shortcut to ref.metadata, never null, but possibly empty
- commit (CommitMeta) - shortcut to ref.metadata.commitMetaOfHEAD, never null, but possibly empty
- refType (String) - the reference type, either BRANCH or TAG
Note that the expression can only test attributes metadata and commit, if 'fetchOption' is set to 'ALL'.
schema:
type: string
examples:
expr_by_refType:
$ref: "#/components/examples/expr_by_refType"
expr_by_ref_name:
$ref: "#/components/examples/expr_by_ref_name"
expr_by_ref_commit:
$ref: "#/components/examples/expr_by_ref_commit"
- name: maxRecords
in: query
description: "maximum number of entries to return, just a hint for the server"
schema:
format: int32
type: integer
- name: pageToken
in: query
description: "paging continuation token, as returned in the previous value\
\ of the field 'token' in the corresponding 'EntriesResponse' or 'LogResponse'\
\ or 'ReferencesResponse' or 'RefLogResponse'."
schema:
type: string
responses:
"200":
description: Returned references.
content:
application/json:
schema:
$ref: "#/components/schemas/ReferencesResponse_V1"
examples:
referencesResponse:
$ref: "#/components/examples/referencesResponse"
referencesResponseWithMetadata:
$ref: "#/components/examples/referencesResponseWithMetadata"
"401":
description: Invalid credentials provided
/v1/trees/branch/{branchName}/commit:
post:
tags:
- v1
summary: Commit multiple operations against the given branch expecting that
branch to have the given hash as its latest commit. The hash in the successful
response contains the hash of the commit that contains the operations of the
invocation.
operationId: commitMultipleOperations
parameters:
- name: branchName
in: path
description: "Branch to change, defaults to default branch."
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: expectedHash
in: query
description: Expected hash of branch.
schema:
type: string
examples:
hash:
$ref: "#/components/examples/hash"
requestBody:
description: Operations
content:
application/json:
schema:
$ref: "#/components/schemas/Operations"
examples:
operations:
$ref: "#/components/examples/operations"
responses:
"200":
description: Updated successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/Branch_V1"
examples:
refObj:
$ref: "#/components/examples/refObj"
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or perform commits
"404":
description: Provided ref doesn't exists
"409":
description: Update conflict
/v1/trees/branch/{branchName}/merge:
post:
tags:
- v1
summary: Merge commits from 'mergeRef' onto 'branchName'.
description: "Merge items from an existing hash in 'mergeRef' into the requested\
\ branch. The merge is always a rebase + fast-forward merge and is only completed\
\ if the rebase is conflict free. The set of commits added to the branch will\
\ be all of those until we arrive at a common ancestor. Depending on the underlying\
\ implementation, the number of commits allowed as part of this operation\
\ may be limited."
operationId: mergeRefIntoBranch
parameters:
- name: branchName
in: path
description: Branch to merge into
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: expectedHash
in: query
description: Expected current HEAD of 'branchName'
required: true
schema:
type: string
examples:
hash:
$ref: "#/components/examples/hash"
requestBody:
description: "Merge operation that defines the source reference name and an\
\ optional hash. If 'fromHash' is not present, the current 'sourceRef's\
\ HEAD will be used."
content:
application/json:
schema:
$ref: "#/components/schemas/Merge"
examples:
merge:
$ref: "#/components/examples/merge"
responses:
"204":
description: "Merge operation completed. The actual merge might have failed\
\ and reported as successful=false, if the client asked to return a conflict\
\ as a result instead of returning an error."
content:
application/json:
schema:
$ref: "#/components/schemas/MergeResponse_V1"
examples:
mergeResponseSuccess:
$ref: "#/components/examples/mergeResponseSuccess"
mergeResponseFail:
$ref: "#/components/examples/mergeResponseFail"
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or merge commits
"404":
description: Ref doesn't exists
"409":
description: update conflict
/v1/trees/branch/{branchName}/transplant:
post:
tags:
- v1
summary: Transplant commits from 'transplant' onto 'branchName'
description: This is done as an atomic operation such that only the last of
the sequence is ever visible to concurrent readers/writers. The sequence to
transplant must be contiguous and in order.
operationId: transplantCommitsIntoBranch
parameters:
- name: branchName
in: path
description: Branch to transplant into
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: expectedHash
in: query
description: Expected hash of tag.
required: true
schema:
type: string
examples:
hash:
$ref: "#/components/examples/hash"
- name: message
in: query
description: commit message
schema:
type: string
examples:
commitMessage:
$ref: "#/components/examples/commitMessage"
requestBody:
description: Hashes to transplant
content:
application/json:
schema:
$ref: "#/components/schemas/Transplant"
examples:
transplant:
$ref: "#/components/examples/transplant"
responses:
"204":
description: "Transplant operation completed. The actual transplant might\
\ have failed and reported as successful=false, if the client asked to\
\ return a conflict as a result instead of returning an error. Note: the\
\ 'commonAncestor' field in a response will always be null for a transplant."
content:
application/json:
schema:
$ref: "#/components/schemas/MergeResponse_V1"
examples:
mergeResponseSuccess:
$ref: "#/components/examples/mergeResponseSuccess"
mergeResponseFail:
$ref: "#/components/examples/mergeResponseFail"
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or transplant commits
"404":
description: Ref doesn't exists
"409":
description: update conflict
/v1/trees/tree:
get:
tags:
- v1
summary: Get default branch for commits and reads
operationId: getDefaultBranch
responses:
"200":
description: Returns name and latest hash of the default branch.
content:
application/json:
schema:
$ref: "#/components/schemas/Branch_V1"
examples:
refObj:
$ref: "#/components/examples/refObj"
"401":
description: Invalid credentials provided
"404":
description: Default branch not found.
post:
tags:
- v1
summary: Create a new reference
description: |-
The type of 'refObj', which can be either a 'Branch' or 'Tag', determines the type of the reference to be created.
'Reference.name' defines the the name of the reference to be created,'Reference.hash' is the hash of the created reference, the HEAD of the created reference. 'sourceRefName' is the name of the reference which contains 'Reference.hash', and must be present if 'Reference.hash' is present.
Specifying no 'Reference.hash' means that the new reference will be created "at the beginning of time".
operationId: createReference
parameters:
- name: sourceRefName
in: query
description: Source named reference
schema:
type: string
requestBody:
description: Reference to create.
content:
application/json:
schema:
$ref: "#/components/schemas/Reference"
examples:
refObjNew:
$ref: "#/components/examples/refObjNew"
responses:
"200":
description: Created successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/Reference_V1"
examples:
refObjNew:
$ref: "#/components/examples/refObjNew"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to create reference
"409":
description: Reference already exists
/v1/trees/tree/{ref}:
get:
tags:
- v1
summary: Fetch details of a reference
operationId: getReferenceByName
parameters:
- name: ref
in: path
description: name of ref to fetch
required: true
schema:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: fetch
in: query
description: |-
Specify how much information to be returned. Will fetch additional metadata for references if set to 'ALL'.
A returned Branch instance will have the following information:
- numCommitsAhead (number of commits ahead of the default branch)
- numCommitsBehind (number of commits behind the default branch)
- commitMetaOfHEAD (the commit metadata of the HEAD commit)
- commonAncestorHash (the hash of the common ancestor in relation to the default branch).
- numTotalCommits (the total number of commits in this reference).
A returned Tag instance will only contain the 'commitMetaOfHEAD' and 'numTotalCommits' fields.
Note that computing & fetching additional metadata might be computationally expensive on the server-side, so this flag should be used with care.
schema:
$ref: "#/components/schemas/FetchOption"
responses:
"200":
description: Found and returned reference.
content:
application/json:
schema:
$ref: "#/components/schemas/Reference_V1"
examples:
refObj:
$ref: "#/components/examples/refObj"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference
"404":
description: Ref not found
/v1/trees/tree/{ref}/entries:
get:
tags:
- v1
summary: Fetch all entries for a given reference
description: "Retrieves objects for a ref, potentially truncated by the backend.\n\
\nRetrieves up to 'maxRecords' entries for the given named reference (tag\
\ or branch) or the given hash. The backend may respect the given 'max' records\
\ hint, but return less or more entries. Backends may also cap the returned\
\ entries at a hard-coded limit, the default REST server implementation has\
\ such a hard-coded limit.\n\nTo implement paging, check 'hasMore' in the\
\ response and, if 'true', pass the value returned as 'token' in the next\
\ invocation as the 'pageToken' parameter.\n\nThe content and meaning of the\
\ returned 'token' is \"private\" to the implementation,treat is as an opaque\
\ value.\n\nIt is wrong to assume that invoking this method with a very high\
\ 'maxRecords' value will return all commit log entries.\n\nThe 'filter' parameter\
\ allows for advanced filtering capabilities using the Common Expression Language\
\ (CEL).\nAn intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.\n\
\nThe 'namespaceDepth' parameter returns only the ContentKey components up\
\ to the depth of 'namespaceDepth'.\nFor example they key 'a.b.c.d' with a\
\ depth of 3 will return 'a.b.c'. The operation is guaranteed to not return\
\ \nduplicates and therefore will never page."
operationId: getEntries
parameters:
- name: ref
in: path
description: name of ref to fetch from
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: filter
in: query
description: |-
A Common Expression Language (CEL) expression. An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
Usable variables within the expression are 'entry.namespace' (string) & 'entry.contentType' (string)
schema:
type: string
examples:
expr_by_namespace:
$ref: "#/components/examples/expr_by_namespace"
expr_by_contentType:
$ref: "#/components/examples/expr_by_contentType"
expr_by_namespace_and_contentType:
$ref: "#/components/examples/expr_by_namespace_and_contentType"
- name: hashOnRef
in: query
description: a particular hash on the given ref
schema:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
- name: maxRecords
in: query
description: "maximum number of entries to return, just a hint for the server"
schema:
format: int32
type: integer
- name: namespaceDepth
in: query
description: |-
If set > 0 will filter the results to only return namespaces/tables to the depth of namespaceDepth. If not set or <=0 has no effect
Setting this parameter > 0 will turn off paging.
schema:
format: int32
type: integer
- name: pageToken
in: query
description: "paging continuation token, as returned in the previous value\
\ of the field 'token' in the corresponding 'EntriesResponse' or 'LogResponse'\
\ or 'ReferencesResponse' or 'RefLogResponse'."
schema:
type: string
responses:
default:
description: all objects for a reference
content:
application/json:
schema:
$ref: "#/components/schemas/EntriesResponse_V1"
examples:
entriesResponse:
$ref: "#/components/examples/entriesResponse"
"200":
description: Returned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/EntriesResponse_V1"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or fetch entries for
it
"404":
description: Ref not found
/v1/trees/tree/{ref}/log:
get:
tags:
- v1
summary: Get commit log for a reference
description: |
Retrieve the commit log for a ref, potentially truncated by the backend.
Retrieves up to 'maxRecords' commit-log-entries starting at the HEAD of the given named reference (tag or branch) or the given hash. The backend may respect the given 'max' records hint, but return less or more entries. Backends may also cap the returned entries at a hard-coded limit, the default REST server implementation has such a hard-coded limit.
To implement paging, check 'hasMore' in the response and, if 'true', pass the value returned as 'token' in the next invocation as the 'pageToken' parameter.
The content and meaning of the returned 'token' is "private" to the implementation,treat is as an opaque value.
It is wrong to assume that invoking this method with a very high 'maxRecords' value will return all commit log entries.
The 'filter' parameter allows for advanced filtering capabilities using the Common Expression Language (CEL).
An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
operationId: getCommitLog
parameters:
- name: ref
in: path
description: ref to show log from
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: endHash
in: query
description: "Hash on the given ref to end at (in chronological sense), the\
\ 'near' end of the commit log, returned 'early' in the result."
schema:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
- name: fetch
in: query
description: "Specify how much information to be returned. Will fetch additional\
\ metadata such as parent commit hash and operations in a commit, for each\
\ commit if set to 'ALL'."
schema:
$ref: "#/components/schemas/FetchOption"
- name: filter
in: query
description: |-
A Common Expression Language (CEL) expression. An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
Usable variables within the expression are:
- 'commit' with fields 'author' (string), 'committer' (string), 'commitTime' (timestamp), 'hash' (string), ',message' (string), 'properties' (map)
- 'operations' (list), each operation has the fields 'type' (string, either 'PUT' or 'DELETE'), 'key' (string, namespace + table name), 'keyElements' (list of strings), 'namespace' (string), 'namespaceElements' (list of strings) and 'name' (string, the "simple" table name)
Note that the expression can only test against 'operations', if 'fetch' is set to 'ALL'.
Hint: when filtering commits, you can determine whether commits are "missing" (filtered) by checking whether 'LogEntry.parentCommitHash' is different from the hash of the previous commit in the log response.
schema:
type: string
examples:
expr_by_commit_author:
$ref: "#/components/examples/expr_by_commit_author"
expr_by_commit_committer:
$ref: "#/components/examples/expr_by_commit_committer"
expr_by_commitTime:
$ref: "#/components/examples/expr_by_commitTime"
expr_by_commit_operations_table_name:
$ref: "#/components/examples/expr_by_commit_operations_table_name"
expr_by_commit_operations_type:
$ref: "#/components/examples/expr_by_commit_operations_type"
- name: maxRecords
in: query
description: "maximum number of entries to return, just a hint for the server"
schema:
format: int32
type: integer
- name: pageToken
in: query
description: "paging continuation token, as returned in the previous value\
\ of the field 'token' in the corresponding 'EntriesResponse' or 'LogResponse'\
\ or 'ReferencesResponse' or 'RefLogResponse'."
schema:
type: string
- name: startHash
in: query
description: "Hash on the given ref to start from (in chronological sense),\
\ the 'far' end of the commit log, returned 'late' in the result."
schema:
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
responses:
"200":
description: Returned commits.
content:
application/json:
schema:
$ref: "#/components/schemas/LogResponse_V1"
examples:
logResponseAdditionalInfo:
$ref: "#/components/examples/logResponseAdditionalInfo"
logResponseSimple:
$ref: "#/components/examples/logResponseSimple"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or get commit log for
it
"404":
description: Ref doesn't exists
/v1/trees/{referenceType}/{referenceName}:
put:
tags:
- v1
summary: Set a named reference to a specific hash via a named-reference.
description: This operation takes the name of the named reference to reassign
and the hash and the name of a named-reference via which the caller has access
to that hash.
operationId: assignReference
parameters:
- name: referenceName
in: path
description: Reference name to reassign
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: referenceType
in: path
description: Reference type to reassign
required: true
schema:
$ref: "#/components/schemas/ReferenceType"
examples:
referenceType:
$ref: "#/components/examples/referenceType"
- name: expectedHash
in: query
description: Expected previous hash of reference
required: true
schema:
type: string
examples:
hash:
$ref: "#/components/examples/hash"
requestBody:
description: "Reference hash to which 'referenceName' shall be assigned to.\
\ This must be either a 'Transaction', 'Branch' or 'Tag' via which the hash\
\ is visible to the caller."
content:
application/json:
schema:
$ref: "#/components/schemas/Reference"
examples:
refObj:
$ref: "#/components/examples/refObj"
tagObj:
$ref: "#/components/examples/tagObj"
responses:
"204":
description: Assigned successfully
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view or assign reference
"404":
description: One or more references don't exist
"409":
description: Update conflict
delete:
tags:
- v1
summary: Delete a reference endpoint
operationId: deleteReference
parameters:
- name: referenceName
in: path
description: Reference name to delete
required: true
schema:
type: string
examples:
ref:
$ref: "#/components/examples/ref"
- name: referenceType
in: path
description: Reference type to delete
required: true
schema:
$ref: "#/components/schemas/ReferenceType"
examples:
referenceType:
$ref: "#/components/examples/referenceType"
- name: expectedHash
in: query
description: Expected hash of tag
required: true
schema:
type: string
examples:
hash:
$ref: "#/components/examples/hash"
responses:
"204":
description: Deleted successfully.
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view or delete reference
"404":
description: Ref doesn't exists
"409":
description: update conflict
/v2/config:
get:
tags:
- v2
summary: Returns repository and server settings relevant to clients.
operationId: getConfigV2
responses:
"200":
description: Configuration settings
content:
application/json:
schema:
$ref: "#/components/schemas/NessieConfiguration_V2"
examples:
nessieConfig:
$ref: "#/components/examples/nessieConfig"
"401":
description: Invalid credentials provided
/v2/config/repository:
get:
tags:
- v2
summary: Returns repository configurations of the requested types.
operationId: getRepositoryConfig
parameters:
- name: type
in: query
schema:
type: array
items:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
title: Repository configuration objects for the requested types.
description: The existing configuration objects for the requested
types will be returned. Non-existing config objects will not be
returned.
type: object
properties:
configs:
title: Repository configuration objects for the requested types.
description: The existing configuration objects for the requested
types will be returned. Non-existing config objects will not
be returned.
type: array
items:
$ref: "#/components/schemas/RepositoryConfig_V2"
"401":
description: Invalid credentials provided
post:
tags:
- v2
summary: Create or update a repository configuration.
operationId: updateRepositoryConfig
responses:
"200":
description: The configuration was updated. The response body contains the
previous configuration value.
content:
application/json:
schema:
title: The previous state of the repository configuration object.
description: "When a repository configuration for the same type as\
\ in the request object did not exist, the response object will\
\ be null. Otherwise, if the configuration was updated, the old\
\ value will be returned."
type: object
properties:
previous:
title: The previous state of the repository configuration object.
description: "When a repository configuration for the same type\
\ as in the request object did not exist, the response object\
\ will be null. Otherwise, if the configuration was updated,\
\ the old value will be returned."
type: object
anyOf:
- $ref: "#/components/schemas/GarbageCollectorConfig_V2"
discriminator:
propertyName: type
mapping:
GARBAGE_COLLECTOR: "#/components/schemas/GarbageCollectorConfig_V2"
"401":
description: Invalid credentials provided
/v2/trees:
get:
tags:
- v2
summary: Get information about all branches and tags
operationId: getAllReferencesV2
parameters:
- name: fetch
in: query
description: |-
Specifies how much extra information is to be retrived from the server.
If the fetch option is set to 'ALL' the following addition information will be returned for each Branch object in the output:
- numCommitsAhead (number of commits ahead of the default branch)
- numCommitsBehind (number of commits behind the default branch)
- commitMetaOfHEAD (the commit metadata of the HEAD commit)
- commonAncestorHash (the hash of the common ancestor in relation to the default branch).
- numTotalCommits (the total number of commits from the root to the HEAD of the branch).
The returned Tag instances will only contain the 'commitMetaOfHEAD' and 'numTotalCommits' fields.
Note that computing & fetching additional metadata might be computationally expensive on the server-side, so this flag should be used with care.
schema:
$ref: "#/components/schemas/FetchOption"
- name: filter
in: query
description: |-
A Common Expression Language (CEL) expression. An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
Usable variables within the expression are:
- ref (Reference) describes the reference, with fields name (String), hash (String), metadata (ReferenceMetadata)
- metadata (ReferenceMetadata) shortcut to ref.metadata, never null, but possibly empty
- commit (CommitMeta) - shortcut to ref.metadata.commitMetaOfHEAD, never null, but possibly empty
- refType (String) - the reference type, either BRANCH or TAG
Note that the expression can only test attributes metadata and commit, if 'fetchOption' is set to 'ALL'.
schema:
type: string
examples:
expr_by_refType:
$ref: "#/components/examples/expr_by_refType"
expr_by_ref_name:
$ref: "#/components/examples/expr_by_ref_name"
expr_by_ref_commit:
$ref: "#/components/examples/expr_by_ref_commit"
- name: max-records
in: query
description: "maximum number of entries to return, just a hint for the server"
schema:
format: int32
type: integer
- name: page-token
in: query
description: "paging continuation token, as returned in the previous value\
\ of the field 'token' in the corresponding 'EntriesResponse' or 'LogResponse'\
\ or 'ReferencesResponse' or 'RefLogResponse'."
schema:
type: string
responses:
"200":
description: Returned references.
content:
application/json:
schema:
$ref: "#/components/schemas/ReferencesResponse_V2"
examples:
referencesResponse:
$ref: "#/components/examples/referencesResponse"
referencesResponseWithMetadata:
$ref: "#/components/examples/referencesResponseWithMetadata"
"401":
description: Invalid credentials provided
post:
tags:
- v2
summary: Create a new branch or tag
description: "The name and type query parameters define the kind of reference\
\ to be created. The payload object defines the new reference's origin in\
\ the commit history. \nOnly branches and tags can be created by this method,\
\ but the payload object may be any valid reference, including a detached\
\ commit.\nIf the payload reference object does not define a commit hash,\
\ the HEAD of that reference will be used."
operationId: createReferenceV2
parameters:
- name: name
in: query
description: |
A reference name.
Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain '..'
required: true
schema:
type: string
- name: type
in: query
description: Type of the reference to be created
required: true
schema:
type: string
examples:
referenceType:
$ref: "#/components/examples/referenceType"
requestBody:
description: Source reference data from which the new reference is to be created.
content:
application/json:
schema:
$ref: "#/components/schemas/Reference"
examples:
refObjNew:
$ref: "#/components/examples/refObjNew"
required: true
responses:
"200":
description: Created successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/SingleReferenceResponse_V2"
examples:
singleReferenceResponse:
$ref: "#/components/examples/singleReferenceResponse"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to create reference
"409":
description: Another reference with the same name already exists
/v2/trees/{branch}/history/commit:
post:
tags:
- v2
summary: Commit one or more operations against the given 'branch'.
description: |-
The state of contents specified by the 'branch' reference will be used for detecting conflicts with the operation being committed.
The hash in the successful response will be the hash of the commit that contains the requested operations, whose immediate parent commit will be the current HEAD of the specified branch.
operationId: commitV2
parameters:
- name: branch
in: path
description: |
A reference to a particular version of the contents tree (a point in history) on a branch.
This reference is specified in this form:
- name@hash - Identifies the 'hash' commit on the named branch.
The 'hash' commit must be reachable from the current HEAD of the branch.
In this case 'hash' indicates the state of contents that should be used for validating incoming changes.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
refWithHash:
$ref: "#/components/examples/refWithHash"
requestBody:
description: Operations to commit
content:
application/json:
schema:
$ref: "#/components/schemas/Operations"
examples:
operations:
$ref: "#/components/examples/operations"
required: true
responses:
"200":
description: Updated successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/CommitResponse_V2"
examples:
commitResponse:
$ref: "#/components/examples/commitResponse"
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or perform commits
"404":
description: Provided ref doesn't exist
"409":
description: Update conflict
/v2/trees/{branch}/history/merge:
post:
tags:
- v2
summary: Merge commits from another reference onto 'branch'.
description: |-
Merge commits referenced by the 'mergeRefName' and 'fromHash' parameters of the payload object into the requested 'branch'.
The state of contents specified by the 'branch' reference will be used for detecting conflicts with the commits being transplanted.
The merge is committed if it is free from conflicts. The set of commits merged into the target branch will be all of those starting at 'fromHash' on 'mergeRefName' until we arrive at the common ancestor. Depending on the underlying implementation, the number of commits allowed as part of this operation may be limited.
operationId: mergeV2
parameters:
- name: branch
in: path
description: |
A reference to a specific version of the contents tree (a point in history) on a branch.
This reference is specified in this form:
- name@hash - Identifies the 'hash' commit on the named branch.
The 'hash' commit must be reachable from the current HEAD of the branch.
In this case 'hash' indicates the state of contents known to the client and serves to ensure that the operation is performed on the contents that the client expects.
This hash can point to a commit in the middle of the change history, but it should be as recent as possible.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
refWithHash:
$ref: "#/components/examples/refWithHash"
requestBody:
description: "Merge operation that defines the source reference name and an\
\ optional hash. If 'fromHash' is not present, the current 'sourceRef's\
\ HEAD will be used."
content:
application/json:
schema:
$ref: "#/components/schemas/Merge1"
examples:
merge:
$ref: "#/components/examples/merge"
required: true
responses:
"204":
description: "Merge operation completed. The actual merge might have failed\
\ and reported as successful=false, if the client asked to return a conflict\
\ as a result instead of returning an error."
content:
application/json:
schema:
$ref: "#/components/schemas/MergeResponse_V2"
examples:
mergeResponseSuccess:
$ref: "#/components/examples/mergeResponseSuccess"
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or merge commits
"404":
description: Ref doesn't exists
"409":
description: Merge conflict
content:
application/json:
schema:
$ref: "#/components/schemas/MergeResponse_V2"
examples:
mergeResponseFail:
$ref: "#/components/examples/mergeResponseFail"
/v2/trees/{branch}/history/transplant:
post:
tags:
- v2
summary: Transplant commits specified by the 'Transplant' payload object onto
the given 'branch'
description: |-
This is done as an atomic operation such that only the last of the sequence is ever visible to concurrent readers/writers. The sequence to transplant must be contiguous and in order.
The state of contents specified by the 'branch' reference will be used for detecting conflicts with the commits being transplanted.
operationId: transplantV2
parameters:
- name: branch
in: path
description: |
A reference to a specific version of the contents tree (a point in history) on a branch.
This reference is specified in this form:
- name@hash - Identifies the 'hash' commit on the named branch.
The 'hash' commit must be reachable from the current HEAD of the branch.
In this case 'hash' indicates the state of contents known to the client and serves to ensure that the operation is performed on the contents that the client expects.
This hash can point to a commit in the middle of the change history, but it should be as recent as possible.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
refWithHash:
$ref: "#/components/examples/refWithHash"
requestBody:
description: Commits to transplant
content:
application/json:
schema:
$ref: "#/components/schemas/Transplant1"
examples:
transplant:
$ref: "#/components/examples/transplant"
required: true
responses:
"200":
description: "Transplant operation completed. The actual transplant might\
\ have failed and reported as successful=false, if the client asked to\
\ return a conflict as a result instead of returning an error. Note: the\
\ 'commonAncestor' field in a response will always be null for a transplant."
content:
application/json:
schema:
$ref: "#/components/schemas/MergeResponse_V2"
examples:
mergeResponseSuccess:
$ref: "#/components/examples/mergeResponseSuccess"
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or transplant commits
"404":
description: Ref doesn't exists
"409":
description: Transplant conflict
content:
application/json:
schema:
$ref: "#/components/schemas/MergeResponse_V2"
examples:
mergeResponseFail:
$ref: "#/components/examples/mergeResponseFail"
/v2/trees/{from-ref}/diff/{to-ref}:
get:
tags:
- v2
summary: Get contents that differ in the trees specified by the two given references
description: "The URL pattern is basically 'from' and 'to' reference specs separated\
\ by '/diff/'\n\nExamples: \n- main/diff/myBranch\n- main@1234567890123456/diff/myBranch\n\
- main@1234567890123456/diff/myBranch@23445678\n- main/diff/myBranch@23445678\n\
- main/diff/myBranch@23445678\n- my/branch@/diff/main\n- myBranch/diff/-\n"
operationId: getDiffV2
parameters:
- name: from-ref
in: path
description: |
A reference to a particular version of the contents tree (a point in history).
Reference representations consist of:
- The reference name. '-' means the default branch name.
- A commit hash prefixed with '@'.
- A relative commit specification. '~N' means the N-th predecessor commit, '*T' means the commit for which the timestamp T (milliseconds since epoch or ISO-8601 instant) is valid, '^N' means the N-th parentin a commit (N=2 is the merge parent).
If neither the reference name or the default branch name placeholder '-' is specified, the reference type 'DETACHED' will be assumed.
If no commit hash is specified, the HEAD of the specified named reference will be used.
An empty reference parameter is not valid.
This reference can be specified in these forms:
- \- (literal minus character) - identifies the HEAD of the default branch.
- name - Identifies the HEAD commit of a branch or tag.
- name@hash - Identifies the 'hash' commit on a branch or tag.
- @hash - Identifies the 'hash' commit in an unspecified branch or tag.
- -~3 - The 3rd predecessor commit from the HEAD of the default branch.
- name~3 - The 3rd predecessor commit from the HEAD of a branch or tag.
- @hash~3 - The 3rd predecessor commit of the 'hash' commit.
- name@hash^2 - The merge parent of the 'hash' commit of a branch or tag.
- @hash^2 - The merge parent of the 'hash' commit.
- -*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of the default branch for the given ISO-8601 timestamp.
- name*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of a branch or tag valid for the given ISO-8601 timestamp.
- name*1685185847230 - The predecessor commit closest to the HEAD of a branch or tag valid for the given timestamp in milliseconds since epoch.
If both 'name' and 'hash' are given, 'hash' must be reachable from the current HEAD of the branch or tag. If 'name' is omitted, the reference will be of type 'DETACHED' (referencing a specific commit hash without claiming its reachability from any live HEAD). Using references of the last form may have authorization implications when compared to an equivalent reference of the former forms.
An empty reference parameter is invalid.
The 'name@hash' form always refers to the exact commit on a specific named reference. This is the most complete form of a reference. Other forms omit some of the details and require those gaps to be filled by the server at runtime. Although these forms may be convenient to a human-being, they may resolve differently at different times depending on the state of the system. Using the full 'name@hash' form is recommended to avoid ambiguity.
required: true
schema:
pattern: "^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
refWithHash:
$ref: "#/components/examples/refWithHash"
refWithTimestampMillisSinceEpoch:
$ref: "#/components/examples/refWithTimestampMillisSinceEpoch"
refWithTimestampInstant:
$ref: "#/components/examples/refWithTimestampInstant"
refWithNthPredecessor:
$ref: "#/components/examples/refWithNthPredecessor"
refWithMergeParent:
$ref: "#/components/examples/refWithMergeParent"
refDefault:
$ref: "#/components/examples/refDefault"
refDetached:
$ref: "#/components/examples/refDetached"
- name: to-ref
in: path
description: Same reference spec as in the 'from-ref' parameter but identifying
the other tree for comparison.
required: true
schema:
pattern: "^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*$"
type: string
- name: filter
in: query
description: |-
A Common Expression Language (CEL) expression. An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
Usable variables within the expression are:
- 'key' (string, namespace + table name), 'keyElements' (list of strings), 'namespace' (string), 'namespaceElements' (list of strings) and 'name' (string, the "simple" table name)
schema:
type: string
- name: key
in: query
description: |-
Restrict the result to one or more keys.
Can be combined with min/max-key and prefix-key parameters, however both predicates must match. This means that keys specified via this parameter that do not match a given min/max-key or prefix-key will not be returned.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
type: array
items:
$ref: "#/components/schemas/ContentKey"
- name: max-key
in: query
description: |-
The upper bound of the content key range to retrieve (inclusive). The content keys of all returned entries will be less than or equal to the max-value. Content-keys are compared as a 'whole', unlike prefix-keys.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
$ref: "#/components/schemas/ContentKey"
examples:
ContentKeyGet:
$ref: "#/components/examples/ContentKeyGet"
- name: max-records
in: query
description: "maximum number of entries to return, just a hint for the server"
schema:
format: int32
type: integer
- name: min-key
in: query
description: |-
The lower bound of the content key range to retrieve (inclusive). The content keys of all returned entries will be greater than or equal to the min-value. Content-keys are compared as a 'whole', unlike prefix-keys.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
$ref: "#/components/schemas/ContentKey"
examples:
ContentKeyGet:
$ref: "#/components/examples/ContentKeyGet"
- name: page-token
in: query
description: "paging continuation token, as returned in the previous value\
\ of the field 'token' in the corresponding 'EntriesResponse' or 'LogResponse'\
\ or 'ReferencesResponse' or 'RefLogResponse'."
schema:
type: string
- name: prefix-key
in: query
description: |-
The content key prefix to retrieve (inclusive). A content key matches a given prefix, a content key's elements starts with all elements of the prefix-key. Key prefixes exactly match key-element boundaries.
Must not be combined with min/max-key parameters.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
$ref: "#/components/schemas/ContentKey"
examples:
ContentKeyGet:
$ref: "#/components/examples/ContentKeyGet"
responses:
"200":
description: Returned diff for the given references.
content:
application/json:
schema:
$ref: "#/components/schemas/DiffResponse_V2"
examples:
diffResponseWithRef:
$ref: "#/components/examples/diffResponseWithRef"
"400":
description: "Invalid input, fromRef/toRef name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given fromRef/toRef
"404":
description: fromRef/toRef not found
/v2/trees/{ref}:
get:
tags:
- v2
summary: Fetch details of a reference
operationId: getReferenceByNameV2
parameters:
- name: ref
in: path
description: |
Specifies a reference to a particular commit history branch or tag.
This reference can be specification in these forms:
- \- (literal minus character) - identifies the default branch.
- name - Identifies the named branch or tag.
required: true
schema:
pattern: "^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
refDefault:
$ref: "#/components/examples/refDefault"
- name: fetch
in: query
description: |-
Specify how much information to be returned. Will fetch additional metadata for references if set to 'ALL'.
A returned Branch instance will have the following information:
- numCommitsAhead (number of commits ahead of the default branch)
- numCommitsBehind (number of commits behind the default branch)
- commitMetaOfHEAD (the commit metadata of the HEAD commit)
- commonAncestorHash (the hash of the common ancestor in relation to the default branch).
- numTotalCommits (the total number of commits in this reference).
A returned Tag instance will only contain the 'commitMetaOfHEAD' and 'numTotalCommits' fields.
Note that computing & fetching additional metadata might be computationally expensive on the server-side, so this flag should be used with care.
schema:
$ref: "#/components/schemas/FetchOption"
responses:
"200":
description: Found and returned reference.
content:
application/json:
schema:
$ref: "#/components/schemas/SingleReferenceResponse_V2"
examples:
singleReferenceResponse:
$ref: "#/components/examples/singleReferenceResponse"
singleReferenceResponseWithMetadata:
$ref: "#/components/examples/singleReferenceResponseWithMetadata"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference
"404":
description: Ref not found
put:
tags:
- v2
summary: Set a named reference to a specific hash via another reference.
description: |-
The 'ref' parameter identifies the branch or tag to be reassigned.
The 'ref' parameter may contain a hash qualifier. That hash as well as the optional 'type' parameter may be used to ensure the operation is performed on the same object that the user expects.
Only branches and tags may be reassigned.
The payload object identifies any reference visible to the current user whose 'hash' will be used to define the new HEAD of the reference being reassigned. Detached hashes may be used in the payload.
operationId: assignReferenceV2
parameters:
- name: ref
in: path
description: |
Specifies a named branch or tag reference with its expected HEAD 'hash' value.
For example:
- name@hash - Identifies the 'hash' commit on a branch or tag.
The specified 'hash' must be the value of the current HEAD of the branch or tag known by the client. It will be used to validate that at execution time the reference points to the same hash that the caller expected when the operation arguments were constructed.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
refWithHash:
$ref: "#/components/examples/refWithHash"
- name: type
in: query
description: Optional expected type of the reference being reassigned
schema:
type: string
examples:
referenceType:
$ref: "#/components/examples/referenceType"
requestBody:
description: "Reference to which the 'ref' (from the path parameter) shall\
\ be assigned. This must be either a 'Detached' commit, 'Branch' or 'Tag'\
\ via which the hash is visible to the caller."
content:
application/json:
schema:
$ref: "#/components/schemas/Reference"
examples:
refObj:
$ref: "#/components/examples/refObj"
tagObj:
$ref: "#/components/examples/tagObj"
required: true
responses:
"200":
description: Assigned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/SingleReferenceResponse_V2"
examples:
singleReferenceResponse:
$ref: "#/components/examples/singleReferenceResponse"
"400":
description: "Invalid input, ref specification not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view or assign reference
"404":
description: One or more references don't exist
"409":
description: Update conflict or expected hash / type mismatch
delete:
tags:
- v2
summary: Delete a reference
description: |-
The 'ref' parameter identifies the branch or tag to be deleted.
The 'ref' parameter may contain a hash qualifier. That hash as well as the optional 'type' parameter may be used to ensure the operation is performed on the same object that the user expects.
Only branches and tags can be deleted. However, deleting the default branch may be restricted.
operationId: deleteReferenceV2
parameters:
- name: ref
in: path
description: |
Specifies a named branch or tag reference with its expected HEAD 'hash' value.
For example:
- name@hash - Identifies the 'hash' commit on a branch or tag.
The specified 'hash' must be the value of the current HEAD of the branch or tag known by the client. It will be used to validate that at execution time the reference points to the same hash that the caller expected when the operation arguments were constructed.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
refWithHash:
$ref: "#/components/examples/refWithHash"
- name: type
in: query
description: Optional expected type of the reference being deleted
schema:
type: string
examples:
referenceType:
$ref: "#/components/examples/referenceType"
responses:
"200":
description: Deleted successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/SingleReferenceResponse_V2"
examples:
singleReferenceResponse:
$ref: "#/components/examples/singleReferenceResponse"
"400":
description: "Invalid input, ref/hash name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view or delete reference
"404":
description: Ref doesn't exists
"409":
description: update conflict
/v2/trees/{ref}/contents:
get:
tags:
- v2
summary: Get multiple content objects.
description: |-
Similar to 'GET /trees/{ref}/content/{key}', but takes multiple 'key' query parameters and returns zero or more content values in the same JSON structure as the 'POST /trees/{ref}/content' endpoint.
This is a convenience method for fetching a small number of content objects. It is mostly intended for human use. For automated use cases or when the number of keys is large the 'POST /trees/{ref}/content' method is preferred.
operationId: getSeveralContents
parameters:
- name: ref
in: path
description: |
A reference to a particular version of the contents tree (a point in history).
Reference representations consist of:
- The reference name. '-' means the default branch name.
- A commit hash prefixed with '@'.
- A relative commit specification. '~N' means the N-th predecessor commit, '*T' means the commit for which the timestamp T (milliseconds since epoch or ISO-8601 instant) is valid, '^N' means the N-th parentin a commit (N=2 is the merge parent).
If neither the reference name or the default branch name placeholder '-' is specified, the reference type 'DETACHED' will be assumed.
If no commit hash is specified, the HEAD of the specified named reference will be used.
An empty reference parameter is not valid.
This reference can be specified in these forms:
- \- (literal minus character) - identifies the HEAD of the default branch.
- name - Identifies the HEAD commit of a branch or tag.
- name@hash - Identifies the 'hash' commit on a branch or tag.
- @hash - Identifies the 'hash' commit in an unspecified branch or tag.
- -~3 - The 3rd predecessor commit from the HEAD of the default branch.
- name~3 - The 3rd predecessor commit from the HEAD of a branch or tag.
- @hash~3 - The 3rd predecessor commit of the 'hash' commit.
- name@hash^2 - The merge parent of the 'hash' commit of a branch or tag.
- @hash^2 - The merge parent of the 'hash' commit.
- -*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of the default branch for the given ISO-8601 timestamp.
- name*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of a branch or tag valid for the given ISO-8601 timestamp.
- name*1685185847230 - The predecessor commit closest to the HEAD of a branch or tag valid for the given timestamp in milliseconds since epoch.
If both 'name' and 'hash' are given, 'hash' must be reachable from the current HEAD of the branch or tag. If 'name' is omitted, the reference will be of type 'DETACHED' (referencing a specific commit hash without claiming its reachability from any live HEAD). Using references of the last form may have authorization implications when compared to an equivalent reference of the former forms.
An empty reference parameter is invalid.
The 'name@hash' form always refers to the exact commit on a specific named reference. This is the most complete form of a reference. Other forms omit some of the details and require those gaps to be filled by the server at runtime. Although these forms may be convenient to a human-being, they may resolve differently at different times depending on the state of the system. Using the full 'name@hash' form is recommended to avoid ambiguity.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
ref:
$ref: "#/components/examples/ref"
refWithHash:
$ref: "#/components/examples/refWithHash"
refWithTimestampMillisSinceEpoch:
$ref: "#/components/examples/refWithTimestampMillisSinceEpoch"
refWithTimestampInstant:
$ref: "#/components/examples/refWithTimestampInstant"
refWithNthPredecessor:
$ref: "#/components/examples/refWithNthPredecessor"
refWithMergeParent:
$ref: "#/components/examples/refWithMergeParent"
refDefault:
$ref: "#/components/examples/refDefault"
refDetached:
$ref: "#/components/examples/refDetached"
- name: for-write
in: query
description: "If set to 'true', access control checks will check for write/create\
\ privilege in addition to read privileges."
schema:
type: boolean
- name: key
in: query
description: |-
The key to a content object.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
type: array
items:
type: string
- name: with-doc
in: query
description: "Whether to return the documentation, if it exists. Default is\
\ to not return the documentation."
schema:
type: boolean
responses:
"200":
description: Retrieved successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/GetMultipleContentsResponse_V2"
examples:
multipleContentsResponse:
$ref: "#/components/examples/multipleContentsResponse"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or read object content
for a key
"404":
description: Provided ref doesn't exists
post:
tags:
- v2
summary: Get multiple content objects.
description: |-
Similar to 'GET /trees/{ref}/content/{key}', but takes multiple 'ContentKey's (in the JSON payload) and returns zero or more content objects.
Note that if some keys from the request do not have an associated content object at the point in history defined by the 'ref' parameter, the response will be successful, but no data will be returned for the missing keys.
operationId: getMultipleContentsV2
parameters:
- name: ref
in: path
description: |
A reference to a particular version of the contents tree (a point in history).
Reference representations consist of:
- The reference name. '-' means the default branch name.
- A commit hash prefixed with '@'.
- A relative commit specification. '~N' means the N-th predecessor commit, '*T' means the commit for which the timestamp T (milliseconds since epoch or ISO-8601 instant) is valid, '^N' means the N-th parentin a commit (N=2 is the merge parent).
If neither the reference name or the default branch name placeholder '-' is specified, the reference type 'DETACHED' will be assumed.
If no commit hash is specified, the HEAD of the specified named reference will be used.
An empty reference parameter is not valid.
This reference can be specified in these forms:
- \- (literal minus character) - identifies the HEAD of the default branch.
- name - Identifies the HEAD commit of a branch or tag.
- name@hash - Identifies the 'hash' commit on a branch or tag.
- @hash - Identifies the 'hash' commit in an unspecified branch or tag.
- -~3 - The 3rd predecessor commit from the HEAD of the default branch.
- name~3 - The 3rd predecessor commit from the HEAD of a branch or tag.
- @hash~3 - The 3rd predecessor commit of the 'hash' commit.
- name@hash^2 - The merge parent of the 'hash' commit of a branch or tag.
- @hash^2 - The merge parent of the 'hash' commit.
- -*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of the default branch for the given ISO-8601 timestamp.
- name*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of a branch or tag valid for the given ISO-8601 timestamp.
- name*1685185847230 - The predecessor commit closest to the HEAD of a branch or tag valid for the given timestamp in milliseconds since epoch.
If both 'name' and 'hash' are given, 'hash' must be reachable from the current HEAD of the branch or tag. If 'name' is omitted, the reference will be of type 'DETACHED' (referencing a specific commit hash without claiming its reachability from any live HEAD). Using references of the last form may have authorization implications when compared to an equivalent reference of the former forms.
An empty reference parameter is invalid.
The 'name@hash' form always refers to the exact commit on a specific named reference. This is the most complete form of a reference. Other forms omit some of the details and require those gaps to be filled by the server at runtime. Although these forms may be convenient to a human-being, they may resolve differently at different times depending on the state of the system. Using the full 'name@hash' form is recommended to avoid ambiguity.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
ref:
$ref: "#/components/examples/ref"
refWithHash:
$ref: "#/components/examples/refWithHash"
refWithTimestampMillisSinceEpoch:
$ref: "#/components/examples/refWithTimestampMillisSinceEpoch"
refWithTimestampInstant:
$ref: "#/components/examples/refWithTimestampInstant"
refWithNthPredecessor:
$ref: "#/components/examples/refWithNthPredecessor"
refWithMergeParent:
$ref: "#/components/examples/refWithMergeParent"
refDefault:
$ref: "#/components/examples/refDefault"
refDetached:
$ref: "#/components/examples/refDetached"
- name: for-write
in: query
description: "If set to 'true', access control checks will check for write/create\
\ privilege in addition to read privileges."
schema:
type: boolean
- name: with-doc
in: query
description: "Whether to return the documentation, if it exists. Default is\
\ to not return the documentation."
schema:
type: boolean
requestBody:
description: Keys to retrieve.
content:
application/json:
schema:
$ref: "#/components/schemas/GetMultipleContentsRequest"
examples:
multiGetRequest:
$ref: "#/components/examples/multiGetRequest"
responses:
"200":
description: Retrieved successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/GetMultipleContentsResponse_V2"
examples:
multipleContentsResponse:
$ref: "#/components/examples/multipleContentsResponse"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or read object content
for a key
"404":
description: Provided ref doesn't exists
/v2/trees/{ref}/contents/{key}:
get:
tags:
- v2
summary: Get the content object associated with a key.
description: This operation returns the content value for a content key at a
particular point in history as defined by the 'ref' parameter.
operationId: getContentV2
parameters:
- name: key
in: path
description: |-
The key to a content object.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
required: true
schema:
$ref: "#/components/schemas/ContentKey"
- name: ref
in: path
description: |
A reference to a particular version of the contents tree (a point in history).
Reference representations consist of:
- The reference name. '-' means the default branch name.
- A commit hash prefixed with '@'.
- A relative commit specification. '~N' means the N-th predecessor commit, '*T' means the commit for which the timestamp T (milliseconds since epoch or ISO-8601 instant) is valid, '^N' means the N-th parentin a commit (N=2 is the merge parent).
If neither the reference name or the default branch name placeholder '-' is specified, the reference type 'DETACHED' will be assumed.
If no commit hash is specified, the HEAD of the specified named reference will be used.
An empty reference parameter is not valid.
This reference can be specified in these forms:
- \- (literal minus character) - identifies the HEAD of the default branch.
- name - Identifies the HEAD commit of a branch or tag.
- name@hash - Identifies the 'hash' commit on a branch or tag.
- @hash - Identifies the 'hash' commit in an unspecified branch or tag.
- -~3 - The 3rd predecessor commit from the HEAD of the default branch.
- name~3 - The 3rd predecessor commit from the HEAD of a branch or tag.
- @hash~3 - The 3rd predecessor commit of the 'hash' commit.
- name@hash^2 - The merge parent of the 'hash' commit of a branch or tag.
- @hash^2 - The merge parent of the 'hash' commit.
- -*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of the default branch for the given ISO-8601 timestamp.
- name*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of a branch or tag valid for the given ISO-8601 timestamp.
- name*1685185847230 - The predecessor commit closest to the HEAD of a branch or tag valid for the given timestamp in milliseconds since epoch.
If both 'name' and 'hash' are given, 'hash' must be reachable from the current HEAD of the branch or tag. If 'name' is omitted, the reference will be of type 'DETACHED' (referencing a specific commit hash without claiming its reachability from any live HEAD). Using references of the last form may have authorization implications when compared to an equivalent reference of the former forms.
An empty reference parameter is invalid.
The 'name@hash' form always refers to the exact commit on a specific named reference. This is the most complete form of a reference. Other forms omit some of the details and require those gaps to be filled by the server at runtime. Although these forms may be convenient to a human-being, they may resolve differently at different times depending on the state of the system. Using the full 'name@hash' form is recommended to avoid ambiguity.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
ref:
$ref: "#/components/examples/ref"
refWithHash:
$ref: "#/components/examples/refWithHash"
refWithTimestampMillisSinceEpoch:
$ref: "#/components/examples/refWithTimestampMillisSinceEpoch"
refWithTimestampInstant:
$ref: "#/components/examples/refWithTimestampInstant"
refWithNthPredecessor:
$ref: "#/components/examples/refWithNthPredecessor"
refWithMergeParent:
$ref: "#/components/examples/refWithMergeParent"
refDefault:
$ref: "#/components/examples/refDefault"
refDetached:
$ref: "#/components/examples/refDetached"
- name: for-write
in: query
description: "If set to 'true', access control checks will check for write/create\
\ privilege in addition to read privileges."
schema:
type: boolean
- name: with-doc
in: query
description: "Whether to return the documentation, if it exists. Default is\
\ to not return the documentation."
schema:
type: boolean
responses:
"200":
description: "Information for a table, view or another content object for\
\ the given key"
content:
application/json:
schema:
$ref: "#/components/schemas/ContentResponse_V2"
examples:
contentResponseIceberg:
$ref: "#/components/examples/contentResponseIceberg"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or read object content
for a key
"404":
description: Table not found on 'ref' or non-existent reference
/v2/trees/{ref}/entries:
get:
tags:
- v2
summary: Fetch all entries for a given reference
description: |
Retrieves objects for a ref, potentially truncated by the backend.
Retrieves up to 'maxRecords' entries for the given named reference (tag or branch) or the given hash. The backend may respect the given 'max' records hint, but return less or more entries. Backends may also cap the returned entries at a hard-coded limit, the default REST server implementation has such a hard-coded limit.
To implement paging, check 'hasMore' in the response and, if 'true', pass the value returned as 'token' in the next invocation as the 'pageToken' parameter.
The content and meaning of the returned 'token' is "private" to the implementation,treat is as an opaque value.
It is wrong to assume that invoking this method with a very high 'maxRecords' value will return all available data in one page.
Different pages may have different numbers of log records in them even if they come from another call to this method with the same parameters. Also, pages are not guaranteed to be filled to contain exactly 'maxRecords' even if the total amount of available data allows that. Pages may contain more of less entries at server's discretion.
The 'filter' parameter allows for advanced filtering capabilities using the Common Expression Language (CEL).
An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
operationId: getEntriesV2
parameters:
- name: ref
in: path
description: |
A reference to a particular version of the contents tree (a point in history).
Reference representations consist of:
- The reference name. '-' means the default branch name.
- A commit hash prefixed with '@'.
- A relative commit specification. '~N' means the N-th predecessor commit, '*T' means the commit for which the timestamp T (milliseconds since epoch or ISO-8601 instant) is valid, '^N' means the N-th parentin a commit (N=2 is the merge parent).
If neither the reference name or the default branch name placeholder '-' is specified, the reference type 'DETACHED' will be assumed.
If no commit hash is specified, the HEAD of the specified named reference will be used.
An empty reference parameter is not valid.
This reference can be specified in these forms:
- \- (literal minus character) - identifies the HEAD of the default branch.
- name - Identifies the HEAD commit of a branch or tag.
- name@hash - Identifies the 'hash' commit on a branch or tag.
- @hash - Identifies the 'hash' commit in an unspecified branch or tag.
- -~3 - The 3rd predecessor commit from the HEAD of the default branch.
- name~3 - The 3rd predecessor commit from the HEAD of a branch or tag.
- @hash~3 - The 3rd predecessor commit of the 'hash' commit.
- name@hash^2 - The merge parent of the 'hash' commit of a branch or tag.
- @hash^2 - The merge parent of the 'hash' commit.
- -*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of the default branch for the given ISO-8601 timestamp.
- name*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of a branch or tag valid for the given ISO-8601 timestamp.
- name*1685185847230 - The predecessor commit closest to the HEAD of a branch or tag valid for the given timestamp in milliseconds since epoch.
If both 'name' and 'hash' are given, 'hash' must be reachable from the current HEAD of the branch or tag. If 'name' is omitted, the reference will be of type 'DETACHED' (referencing a specific commit hash without claiming its reachability from any live HEAD). Using references of the last form may have authorization implications when compared to an equivalent reference of the former forms.
An empty reference parameter is invalid.
The 'name@hash' form always refers to the exact commit on a specific named reference. This is the most complete form of a reference. Other forms omit some of the details and require those gaps to be filled by the server at runtime. Although these forms may be convenient to a human-being, they may resolve differently at different times depending on the state of the system. Using the full 'name@hash' form is recommended to avoid ambiguity.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
ref:
$ref: "#/components/examples/ref"
refWithHash:
$ref: "#/components/examples/refWithHash"
refWithTimestampMillisSinceEpoch:
$ref: "#/components/examples/refWithTimestampMillisSinceEpoch"
refWithTimestampInstant:
$ref: "#/components/examples/refWithTimestampInstant"
refWithNthPredecessor:
$ref: "#/components/examples/refWithNthPredecessor"
refWithMergeParent:
$ref: "#/components/examples/refWithMergeParent"
refDefault:
$ref: "#/components/examples/refDefault"
refDetached:
$ref: "#/components/examples/refDetached"
- name: content
in: query
description: Optionally request to return 'Content' objects for the returned
keys.
schema:
type: boolean
- name: filter
in: query
description: |-
A Common Expression Language (CEL) expression. An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
Usable variables within the expression are 'entry.namespace' (string) & 'entry.contentType' (string)
schema:
type: string
examples:
expr_by_namespace:
$ref: "#/components/examples/expr_by_namespace"
expr_by_contentType:
$ref: "#/components/examples/expr_by_contentType"
expr_by_namespace_and_contentType:
$ref: "#/components/examples/expr_by_namespace_and_contentType"
- name: key
in: query
description: |-
Restrict the result to one or more keys.
Can be combined with min/max-key and prefix-key parameters, however both predicates must match. This means that keys specified via this parameter that do not match a given min/max-key or prefix-key will not be returned.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
type: array
items:
$ref: "#/components/schemas/ContentKey"
- name: max-key
in: query
description: |-
The upper bound of the content key range to retrieve (inclusive). The content keys of all returned entries will be less than or equal to the max-value. Content-keys are compared as a 'whole', unlike prefix-keys.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
$ref: "#/components/schemas/ContentKey"
examples:
ContentKeyGet:
$ref: "#/components/examples/ContentKeyGet"
- name: max-records
in: query
description: "maximum number of entries to return, just a hint for the server"
schema:
format: int32
type: integer
- name: min-key
in: query
description: |-
The lower bound of the content key range to retrieve (inclusive). The content keys of all returned entries will be greater than or equal to the min-value. Content-keys are compared as a 'whole', unlike prefix-keys.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
$ref: "#/components/schemas/ContentKey"
examples:
ContentKeyGet:
$ref: "#/components/examples/ContentKeyGet"
- name: page-token
in: query
description: "paging continuation token, as returned in the previous value\
\ of the field 'token' in the corresponding 'EntriesResponse' or 'LogResponse'\
\ or 'ReferencesResponse' or 'RefLogResponse'."
schema:
type: string
- name: prefix-key
in: query
description: |-
The content key prefix to retrieve (inclusive). A content key matches a given prefix, a content key's elements starts with all elements of the prefix-key. Key prefixes exactly match key-element boundaries.
Must not be combined with min/max-key parameters.
Content key and namespace components are separated by the dot (`.`) character.
The components itself must be escaped using the rules described in [NESSIE-SPEC-2.0.md in the repository](https://github.com/projectnessie/nessie/blob/main/api/NESSIE-SPEC-2-0.md).
schema:
$ref: "#/components/schemas/ContentKey"
examples:
ContentKeyGet:
$ref: "#/components/examples/ContentKeyGet"
responses:
default:
description: List names and object types in a contents tree
content:
application/json:
schema:
$ref: "#/components/schemas/EntriesResponse_V2"
examples:
entriesResponseV2:
$ref: "#/components/examples/entriesResponseV2"
"200":
description: Returned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/EntriesResponse_V2"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or fetch entries for
it
"404":
description: Ref not found
/v2/trees/{ref}/history:
get:
tags:
- v2
summary: Get commit log for a particular reference
description: |-
Retrieve the commit log for a reference, potentially truncated by the backend.
The backend may respect the given 'max-entries' records hint, or may return more or less entries. Backends may also cap the returned entries at a hard-coded limit
To implement paging, check 'hasMore' in the response and, if 'true', pass the value returned as 'token' in the next invocation as the 'pageToken' parameter.
The content and meaning of the returned 'token' is "private" to the implementation,treat is as an opaque value.
It is wrong to assume that invoking this method with a very high 'maxRecords' value will return all available data in one page.
Different pages may have different numbers of log records in them even if they come from another call to this method with the same parameters. Also, pages are not guaranteed to be filled to contain exactly 'maxRecords' even if the total amount of available data allows that. Pages may contain more of less entries at server's discretion.
The 'filter' parameter allows for advanced filtering capabilities using the Common Expression Language (CEL).
An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
The fetching of the log starts from the HEAD of the given ref (or a more specific commit, if provided as part of the 'ref' path element) and proceeds until the 'root' commit or the 'limit-hash' commit are encountered.
operationId: getCommitLogV2
parameters:
- name: ref
in: path
description: |
A reference to a particular version of the contents tree (a point in history).
Reference representations consist of:
- The reference name. '-' means the default branch name.
- A commit hash prefixed with '@'.
- A relative commit specification. '~N' means the N-th predecessor commit, '*T' means the commit for which the timestamp T (milliseconds since epoch or ISO-8601 instant) is valid, '^N' means the N-th parentin a commit (N=2 is the merge parent).
If neither the reference name or the default branch name placeholder '-' is specified, the reference type 'DETACHED' will be assumed.
If no commit hash is specified, the HEAD of the specified named reference will be used.
An empty reference parameter is not valid.
This reference can be specified in these forms:
- \- (literal minus character) - identifies the HEAD of the default branch.
- name - Identifies the HEAD commit of a branch or tag.
- name@hash - Identifies the 'hash' commit on a branch or tag.
- @hash - Identifies the 'hash' commit in an unspecified branch or tag.
- -~3 - The 3rd predecessor commit from the HEAD of the default branch.
- name~3 - The 3rd predecessor commit from the HEAD of a branch or tag.
- @hash~3 - The 3rd predecessor commit of the 'hash' commit.
- name@hash^2 - The merge parent of the 'hash' commit of a branch or tag.
- @hash^2 - The merge parent of the 'hash' commit.
- -*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of the default branch for the given ISO-8601 timestamp.
- name*2021-04-07T14:42:25.534748Z - The predecessor commit closest to the HEAD of a branch or tag valid for the given ISO-8601 timestamp.
- name*1685185847230 - The predecessor commit closest to the HEAD of a branch or tag valid for the given timestamp in milliseconds since epoch.
If both 'name' and 'hash' are given, 'hash' must be reachable from the current HEAD of the branch or tag. If 'name' is omitted, the reference will be of type 'DETACHED' (referencing a specific commit hash without claiming its reachability from any live HEAD). Using references of the last form may have authorization implications when compared to an equivalent reference of the former forms.
An empty reference parameter is invalid.
The 'name@hash' form always refers to the exact commit on a specific named reference. This is the most complete form of a reference. Other forms omit some of the details and require those gaps to be filled by the server at runtime. Although these forms may be convenient to a human-being, they may resolve differently at different times depending on the state of the system. Using the full 'name@hash' form is recommended to avoid ambiguity.
required: true
schema:
pattern: "([^/]+|[^@]+(@|%40)[^@/]*)"
examples:
ref:
$ref: "#/components/examples/ref"
refWithHash:
$ref: "#/components/examples/refWithHash"
refWithTimestampMillisSinceEpoch:
$ref: "#/components/examples/refWithTimestampMillisSinceEpoch"
refWithTimestampInstant:
$ref: "#/components/examples/refWithTimestampInstant"
refWithNthPredecessor:
$ref: "#/components/examples/refWithNthPredecessor"
refWithMergeParent:
$ref: "#/components/examples/refWithMergeParent"
refDefault:
$ref: "#/components/examples/refDefault"
refDetached:
$ref: "#/components/examples/refDetached"
- name: fetch
in: query
description: "Specify how much information to be returned. Will fetch additional\
\ metadata such as parent commit hash and operations in a commit, for each\
\ commit if set to 'ALL'."
schema:
$ref: "#/components/schemas/FetchOption"
- name: filter
in: query
description: |-
A Common Expression Language (CEL) expression. An intro to CEL can be found at https://github.com/google/cel-spec/blob/master/doc/intro.md.
Usable variables within the expression are:
- 'commit' with fields 'author' (string), 'committer' (string), 'commitTime' (timestamp), 'hash' (string), ',message' (string), 'properties' (map)
- 'operations' (list), each operation has the fields 'type' (string, either 'PUT' or 'DELETE'), 'key' (string, namespace + table name), 'keyElements' (list of strings), 'namespace' (string), 'namespaceElements' (list of strings) and 'name' (string, the "simple" table name)
Note that the expression can only test against 'operations', if 'fetch' is set to 'ALL'.
Hint: when filtering commits, you can determine whether commits are "missing" (filtered) by checking whether 'LogEntry.parentCommitHash' is different from the hash of the previous commit in the log response.
schema:
type: string
examples:
expr_by_commit_author:
$ref: "#/components/examples/expr_by_commit_author"
expr_by_commit_committer:
$ref: "#/components/examples/expr_by_commit_committer"
expr_by_commitTime:
$ref: "#/components/examples/expr_by_commitTime"
expr_by_commit_operations_table_name:
$ref: "#/components/examples/expr_by_commit_operations_table_name"
expr_by_commit_operations_type:
$ref: "#/components/examples/expr_by_commit_operations_type"
- name: limit-hash
in: query
description: "Hash on the given ref to identify the commit where the operation\
\ of fetching the log should stop, i.e. the 'far' end of the commit log,\
\ returned late in the result."
schema:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
examples:
nullHash:
$ref: "#/components/examples/nullHash"
hash:
$ref: "#/components/examples/hash"
- name: max-records
in: query
description: "maximum number of entries to return, just a hint for the server"
schema:
format: int32
type: integer
- name: page-token
in: query
description: "paging continuation token, as returned in the previous value\
\ of the field 'token' in the corresponding 'EntriesResponse' or 'LogResponse'\
\ or 'ReferencesResponse' or 'RefLogResponse'."
schema:
type: string
responses:
"200":
description: Returned commits.
content:
application/json:
schema:
$ref: "#/components/schemas/LogResponse_V2"
examples:
logResponseAdditionalInfo:
$ref: "#/components/examples/logResponseAdditionalInfo"
logResponseSimple:
$ref: "#/components/examples/logResponseSimple"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference or get commit log for
it
"404":
description: Ref doesn't exists
/v2/trees/{ref}/recent-changes:
get:
tags:
- v2
summary: Fetch recent pointer changes of a reference
description: |-
Retrieve the recorded recent history of a reference.
A reference's history is a size and time limited record of changes of the reference's current pointer, aka HEAD. The size and time limits are configured in the Nessie server configuration.
This function is only useful for deployments using replicating multi-zone/region database setups. If the "primary write target" fails and cannot be recovered, replicas might not have all written records (data loss scenario). This function helps identifying whether the commits of a reference that were written within the configured "replication lag" are present and consistent. A reference might then be deleted or re-assigned to a consistent commit.
operationId: getReferenceHistory
parameters:
- name: ref
in: path
description: |
Specifies a reference to a particular commit history branch or tag.
This reference can be specification in these forms:
- \- (literal minus character) - identifies the default branch.
- name - Identifies the named branch or tag.
required: true
schema:
pattern: "^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*$"
type: string
examples:
ref:
$ref: "#/components/examples/ref"
refDefault:
$ref: "#/components/examples/refDefault"
- name: scan-commits
in: query
description: "Optional parameter, specifies the number of commits to scan\
\ from the reference's current HEAD, limited to the given amount of commits.\
\ Default is to not scan the commit log. The server may impose a hard limit\
\ on the amount of commits from the commit log."
schema:
format: int32
type: integer
responses:
"200":
description: Found and returned reference.
content:
application/json:
schema:
$ref: "#/components/schemas/ReferenceHistoryResponse_V2"
examples:
referenceHistoryResponse:
$ref: "#/components/examples/referenceHistoryResponse"
"400":
description: "Invalid input, ref name not valid"
"401":
description: Invalid credentials provided
"403":
description: Not allowed to view the given reference
"404":
description: Reference not found
components:
schemas:
AddedContent:
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
AddedContent_V2:
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V2"
Branch:
title: Branch
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata"
hash:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
Branch_V1:
title: Branch
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata_V1"
hash:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
Branch_V2:
title: Branch
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata_V2"
hash:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
CommitConsistency:
enum:
- NOT_CHECKED
- COMMIT_CONSISTENT
- COMMIT_CONTENT_INCONSISTENT
- COMMIT_INCONSISTENT
type: string
CommitConsistency_V2:
enum:
- NOT_CHECKED
- COMMIT_CONSISTENT
- COMMIT_CONTENT_INCONSISTENT
- COMMIT_INCONSISTENT
type: string
CommitMeta:
title: CommitMeta
required:
- authors
- allSignedOffBy
- message
- properties
- allProperties
- parentCommitHashes
type: object
properties:
hash:
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
committer:
type: string
author:
type: string
authors:
type: array
items:
type: string
signedOffBy:
type: string
allSignedOffBy:
type: array
items:
type: string
message:
pattern: \S
type: string
commitTime:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
authorTime:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
properties:
type: object
additionalProperties:
type: string
allProperties:
type: object
additionalProperties:
type: array
items:
type: string
parentCommitHashes:
type: array
items:
type: string
CommitMeta_V1:
title: CommitMeta
required:
- message
- properties
type: object
properties:
hash:
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
committer:
type: string
author:
type: string
signedOffBy:
type: string
message:
pattern: \S
type: string
commitTime:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
authorTime:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
properties:
type: object
additionalProperties:
type: string
CommitMeta_V2:
title: CommitMeta
required:
- authors
- allSignedOffBy
- message
- allProperties
- parentCommitHashes
type: object
properties:
hash:
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
committer:
type: string
authors:
type: array
items:
type: string
allSignedOffBy:
type: array
items:
type: string
message:
pattern: \S
type: string
commitTime:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
authorTime:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
allProperties:
type: object
additionalProperties:
type: array
items:
type: string
parentCommitHashes:
type: array
items:
type: string
CommitResponse:
title: Commit Response
required:
- targetBranch
type: object
properties:
targetBranch:
$ref: "#/components/schemas/Branch"
addedContents:
type: array
items:
$ref: "#/components/schemas/AddedContent"
CommitResponse_V2:
title: Commit Response
required:
- targetBranch
type: object
properties:
targetBranch:
$ref: "#/components/schemas/Branch_V2"
addedContents:
type: array
items:
$ref: "#/components/schemas/AddedContent_V2"
Conflict:
title: Per Content Key conflict details
type: object
properties:
conflictType:
description: Conflict type (enum).
key:
description: The conflicting Content Key.
message:
description: Conflict details.
Conflict_V2:
title: Per Content Key conflict details
type: object
properties:
conflictType:
description: Conflict type (enum).
key:
description: The conflicting Content Key.
message:
description: Conflict details.
Content:
title: Content
type: object
properties:
id:
type: string
anyOf:
- $ref: "#/components/schemas/IcebergTable"
- $ref: "#/components/schemas/DeltaLakeTable"
- $ref: "#/components/schemas/IcebergView"
- $ref: "#/components/schemas/Namespace"
- $ref: "#/components/schemas/UDF"
- type: object
discriminator:
propertyName: type
mapping:
ICEBERG_TABLE: "#/components/schemas/IcebergTable"
DELTA_LAKE_TABLE: "#/components/schemas/DeltaLakeTable"
ICEBERG_VIEW: "#/components/schemas/IcebergView"
NAMESPACE: "#/components/schemas/Namespace"
UDF: "#/components/schemas/UDF"
ContentKey:
required:
- elements
type: object
properties:
elements:
type: array
items:
type: string
ContentKeyDetails:
title: Merge Per-Content-Key details
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
mergeBehavior:
$ref: "#/components/schemas/MergeBehavior"
conflict:
$ref: "#/components/schemas/Conflict"
ContentKeyDetails_V1:
title: Merge Per-Content-Key details
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V1"
mergeBehavior:
$ref: "#/components/schemas/MergeBehavior_V1"
ContentKeyDetails_V2:
title: Merge Per-Content-Key details
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V2"
mergeBehavior:
$ref: "#/components/schemas/MergeBehavior_V2"
conflict:
$ref: "#/components/schemas/Conflict_V2"
ContentKey_V1:
required:
- elements
type: object
properties:
elements:
type: array
items:
type: string
ContentKey_V2:
required:
- elements
type: object
properties:
elements:
type: array
items:
type: string
ContentMetadata:
title: ContentMetadata
required:
- variant
type: object
properties:
variant:
minLength: 1
type: string
discriminator:
propertyName: variant
ContentMetadata_V2:
title: ContentMetadata
required:
- variant
type: object
properties:
variant:
minLength: 1
type: string
discriminator:
propertyName: variant
ContentResponse_V2:
required:
- content
- effectiveReference
type: object
properties:
content:
$ref: "#/components/schemas/Content_V2"
effectiveReference:
$ref: "#/components/schemas/Reference_V2"
documentation:
$ref: "#/components/schemas/Documentation_V2"
ContentWithKey:
required:
- key
- content
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
content:
$ref: "#/components/schemas/Content"
documentation:
$ref: "#/components/schemas/Documentation"
ContentWithKey_V1:
required:
- key
- content
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V1"
content:
$ref: "#/components/schemas/Content_V1"
ContentWithKey_V2:
required:
- key
- content
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V2"
content:
$ref: "#/components/schemas/Content_V2"
documentation:
$ref: "#/components/schemas/Documentation_V2"
Content_V1:
title: Content
type: object
properties:
id:
type: string
anyOf:
- $ref: "#/components/schemas/IcebergTable_V1"
- $ref: "#/components/schemas/DeltaLakeTable_V1"
- $ref: "#/components/schemas/IcebergView_V1"
- $ref: "#/components/schemas/Namespace_V1"
- $ref: "#/components/schemas/UDF_V1"
- type: object
discriminator:
propertyName: type
mapping:
ICEBERG_TABLE: "#/components/schemas/IcebergTable_V1"
DELTA_LAKE_TABLE: "#/components/schemas/DeltaLakeTable_V1"
ICEBERG_VIEW: "#/components/schemas/IcebergView_V1"
NAMESPACE: "#/components/schemas/Namespace_V1"
UDF: "#/components/schemas/UDF_V1"
Content_V2:
title: Content
type: object
properties:
id:
type: string
anyOf:
- $ref: "#/components/schemas/IcebergTable_V2"
- $ref: "#/components/schemas/DeltaLakeTable_V2"
- $ref: "#/components/schemas/IcebergView_V2"
- $ref: "#/components/schemas/Namespace_V2"
- $ref: "#/components/schemas/UDF_V2"
- type: object
discriminator:
propertyName: type
mapping:
ICEBERG_TABLE: "#/components/schemas/IcebergTable_V2"
DELTA_LAKE_TABLE: "#/components/schemas/DeltaLakeTable_V2"
ICEBERG_VIEW: "#/components/schemas/IcebergView_V2"
NAMESPACE: "#/components/schemas/Namespace_V2"
UDF: "#/components/schemas/UDF_V2"
Delete:
title: Delete-'Content'-operation for a 'ContentKey'.
description: |-
Used to delete an existing content key.
If the key for a content shall change (aka a rename), then use a `Delete` operation using the current (old) key and a `Put` operation using the new key with the current `Content` in the the `value` field. See `Put` operation.
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
Delete_V1:
title: Delete-'Content'-operation for a 'ContentKey'.
description: |-
Used to delete an existing content key.
If the key for a content shall change (aka a rename), then use a `Delete` operation using the current (old) key and a `Put` operation using the new key with the current `Content` in the the `value` field. See `Put` operation.
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V1"
Delete_V2:
title: Delete-'Content'-operation for a 'ContentKey'.
description: |-
Used to delete an existing content key.
If the key for a content shall change (aka a rename), then use a `Delete` operation using the current (old) key and a `Put` operation using the new key with the current `Content` in the the `value` field. See `Put` operation.
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V2"
DeltaLakeTable:
required:
- metadataLocationHistory
- checkpointLocationHistory
type: object
properties:
id:
type: string
metadataLocationHistory:
type: array
items:
type: string
checkpointLocationHistory:
type: array
items:
type: string
lastCheckpoint:
type: string
DeltaLakeTable_V1:
required:
- metadataLocationHistory
- checkpointLocationHistory
type: object
properties:
id:
type: string
metadataLocationHistory:
type: array
items:
type: string
checkpointLocationHistory:
type: array
items:
type: string
lastCheckpoint:
type: string
DeltaLakeTable_V2:
required:
- metadataLocationHistory
- checkpointLocationHistory
type: object
properties:
id:
type: string
metadataLocationHistory:
type: array
items:
type: string
checkpointLocationHistory:
type: array
items:
type: string
lastCheckpoint:
type: string
Detached:
title: Detached commit hash
required:
- hash
type: object
properties:
hash:
minLength: 1
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata"
Detached_V1:
title: Detached commit hash
required:
- hash
type: object
properties:
hash:
minLength: 1
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata_V1"
Detached_V2:
title: Detached commit hash
required:
- hash
type: object
properties:
hash:
minLength: 1
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata_V2"
DiffEntry:
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
from:
$ref: "#/components/schemas/Content"
to:
$ref: "#/components/schemas/Content"
DiffEntry_V1:
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V1"
from:
$ref: "#/components/schemas/Content_V1"
to:
$ref: "#/components/schemas/Content_V1"
DiffEntry_V2:
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V2"
from:
$ref: "#/components/schemas/Content_V2"
to:
$ref: "#/components/schemas/Content_V2"
DiffResponse:
title: DiffResponse
type: object
properties:
hasMore:
type: boolean
token:
type: string
diffs:
type: array
items:
$ref: "#/components/schemas/DiffEntry"
effectiveFromReference:
$ref: "#/components/schemas/Reference"
effectiveToReference:
$ref: "#/components/schemas/Reference"
DiffResponse_V1:
title: DiffResponse
type: object
properties:
hasMore:
type: boolean
token:
type: string
diffs:
type: array
items:
$ref: "#/components/schemas/DiffEntry_V1"
DiffResponse_V2:
title: DiffResponse
type: object
properties:
hasMore:
type: boolean
token:
type: string
diffs:
type: array
items:
$ref: "#/components/schemas/DiffEntry_V2"
effectiveFromReference:
$ref: "#/components/schemas/Reference_V2"
effectiveToReference:
$ref: "#/components/schemas/Reference_V2"
Documentation:
required:
- mimeType
- text
type: object
properties:
mimeType:
type: string
text:
type: string
Documentation_V2:
required:
- mimeType
- text
type: object
properties:
mimeType:
type: string
text:
type: string
EntriesResponse_V1:
required:
- entries
type: object
properties:
hasMore:
type: boolean
token:
type: string
entries:
type: array
items:
$ref: "#/components/schemas/Entry_V1"
EntriesResponse_V2:
required:
- entries
type: object
properties:
hasMore:
type: boolean
token:
type: string
entries:
type: array
items:
$ref: "#/components/schemas/Entry_V2"
effectiveReference:
$ref: "#/components/schemas/Reference_V2"
Entry_V1:
required:
- name
type: object
properties:
type:
$ref: "#/components/schemas/Type"
name:
$ref: "#/components/schemas/ContentKey_V1"
Entry_V2:
required:
- name
type: object
properties:
type:
$ref: "#/components/schemas/Type"
name:
$ref: "#/components/schemas/ContentKey_V2"
contentId:
type: string
content:
$ref: "#/components/schemas/Content_V2"
FetchOption:
enum:
- MINIMAL
- ALL
type: string
GarbageCollectorConfig:
title: Garbage collector config object
type: object
properties:
defaultCutoffPolicy:
description: |-
The default cutoff policy.
Policies can be one of: - number of commits as an integer value - a duration (see java.time.Duration) - an ISO instant - 'NONE', means everything's considered as live
pattern: "NONE|^[1-9]\\d{0,10}|([-+]?)P(?:([-+]?[0-9]+)D)?(T(?:([-+]?[0-9]+)H)?(?:([-+]?[0-9]+)M)?(?:([-+]?[0-9]+)(?:[.,]([0-9]{0,9}))?S)?)?|^(?:[1-9]\\\
d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\\
d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\\\
d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,9})?(?:Z|[+-][01]\\d:[0-5]\\d)$"
type: string
perRefCutoffPolicies:
type: array
items:
$ref: "#/components/schemas/ReferenceCutoffPolicy"
newFilesGracePeriod:
format: duration
title: Grace period for files created concurrent to GC runs.
description: Files that have been created after 'gc-start-time - new-files-grace-period'
are not being deleted.
type: string
example: P1D
expectedFileCountPerContent:
format: int32
title: The total number of expected live files for a single content.
type: integer
GarbageCollectorConfig_V2:
title: Garbage collector config object
type: object
properties:
defaultCutoffPolicy:
description: |-
The default cutoff policy.
Policies can be one of: - number of commits as an integer value - a duration (see java.time.Duration) - an ISO instant - 'NONE', means everything's considered as live
pattern: "NONE|^[1-9]\\d{0,10}|([-+]?)P(?:([-+]?[0-9]+)D)?(T(?:([-+]?[0-9]+)H)?(?:([-+]?[0-9]+)M)?(?:([-+]?[0-9]+)(?:[.,]([0-9]{0,9}))?S)?)?|^(?:[1-9]\\\
d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\\
d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\\\
d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,9})?(?:Z|[+-][01]\\d:[0-5]\\d)$"
type: string
perRefCutoffPolicies:
type: array
items:
$ref: "#/components/schemas/ReferenceCutoffPolicy_V2"
newFilesGracePeriod:
format: duration
title: Grace period for files created concurrent to GC runs.
description: Files that have been created after 'gc-start-time - new-files-grace-period'
are not being deleted.
type: string
example: P1D
expectedFileCountPerContent:
format: int32
title: The total number of expected live files for a single content.
type: integer
GetMultipleContentsRequest:
title: GetMultipleContentsRequest
required:
- requestedKeys
type: object
properties:
requestedKeys:
type: array
items:
$ref: "#/components/schemas/ContentKey"
GetMultipleContentsResponse:
title: GetMultipleContentsResponse
required:
- contents
type: object
properties:
contents:
type: array
items:
$ref: "#/components/schemas/ContentWithKey"
effectiveReference:
$ref: "#/components/schemas/Reference"
GetMultipleContentsResponse_V1:
title: GetMultipleContentsResponse
required:
- contents
type: object
properties:
contents:
type: array
items:
$ref: "#/components/schemas/ContentWithKey_V1"
GetMultipleContentsResponse_V2:
title: GetMultipleContentsResponse
required:
- contents
type: object
properties:
contents:
type: array
items:
$ref: "#/components/schemas/ContentWithKey_V2"
effectiveReference:
$ref: "#/components/schemas/Reference_V2"
GetNamespacesResponse_V1:
required:
- namespaces
type: object
properties:
namespaces:
type: array
items:
$ref: "#/components/schemas/Namespace_V1"
IcebergTable:
title: Iceberg table state
description: |-
Represents the state of an Iceberg table in Nessie. An Iceberg table is globally identified via its unique 'Content.id'.
A Nessie commit-operation, performed via 'TreeApi.commitMultipleOperations',for Iceberg consists of a 'Operation.Put' with an 'IcebergTable' as in the 'content' field and the previous value of 'IcebergTable' in the 'expectedContent' field.
required:
- metadataLocation
type: object
properties:
id:
type: string
metadataLocation:
pattern: \S
type: string
snapshotId:
format: int64
type: integer
schemaId:
format: int32
type: integer
specId:
format: int32
type: integer
sortOrderId:
format: int32
type: integer
metadata:
type: object
additionalProperties: {}
deprecated: true
IcebergTable_V1:
title: Iceberg table state
description: |-
Represents the state of an Iceberg table in Nessie. An Iceberg table is globally identified via its unique 'Content.id'.
A Nessie commit-operation, performed via 'TreeApi.commitMultipleOperations',for Iceberg consists of a 'Operation.Put' with an 'IcebergTable' as in the 'content' field and the previous value of 'IcebergTable' in the 'expectedContent' field.
required:
- metadataLocation
type: object
properties:
id:
type: string
metadataLocation:
pattern: \S
type: string
snapshotId:
format: int64
type: integer
schemaId:
format: int32
type: integer
specId:
format: int32
type: integer
sortOrderId:
format: int32
type: integer
metadata:
type: object
additionalProperties: {}
deprecated: true
IcebergTable_V2:
title: Iceberg table state
description: |-
Represents the state of an Iceberg table in Nessie. An Iceberg table is globally identified via its unique 'Content.id'.
A Nessie commit-operation, performed via 'TreeApi.commitMultipleOperations',for Iceberg consists of a 'Operation.Put' with an 'IcebergTable' as in the 'content' field and the previous value of 'IcebergTable' in the 'expectedContent' field.
required:
- metadataLocation
type: object
properties:
id:
type: string
metadataLocation:
pattern: \S
type: string
snapshotId:
format: int64
type: integer
schemaId:
format: int32
type: integer
specId:
format: int32
type: integer
sortOrderId:
format: int32
type: integer
IcebergView:
required:
- metadataLocation
- sqlText
type: object
properties:
id:
type: string
metadataLocation:
pattern: \S
type: string
versionId:
format: int64
type: integer
schemaId:
format: int32
type: integer
sqlText:
pattern: \S
type: string
deprecated: true
dialect:
type: string
deprecated: true
metadata:
type: object
additionalProperties: {}
deprecated: true
IcebergView_V1:
required:
- metadataLocation
- sqlText
type: object
properties:
id:
type: string
metadataLocation:
pattern: \S
type: string
versionId:
format: int64
type: integer
schemaId:
format: int32
type: integer
sqlText:
pattern: \S
type: string
deprecated: true
dialect:
type: string
deprecated: true
metadata:
type: object
additionalProperties: {}
deprecated: true
IcebergView_V2:
required:
- metadataLocation
- sqlText
type: object
properties:
id:
type: string
metadataLocation:
pattern: \S
type: string
versionId:
format: int64
type: integer
schemaId:
format: int32
type: integer
sqlText:
pattern: \S
type: string
deprecated: true
dialect:
type: string
deprecated: true
LogEntry:
title: LogEntry
required:
- commitMeta
type: object
properties:
commitMeta:
$ref: "#/components/schemas/CommitMeta"
additionalParents:
type: array
items:
type: string
deprecated: true
parentCommitHash:
type: string
operations:
type: array
items:
$ref: "#/components/schemas/Operation"
LogEntry_V1:
title: LogEntry
required:
- commitMeta
type: object
properties:
commitMeta:
$ref: "#/components/schemas/CommitMeta_V1"
additionalParents:
type: array
items:
type: string
deprecated: true
parentCommitHash:
type: string
operations:
type: array
items:
$ref: "#/components/schemas/Operation_V1"
LogEntry_V2:
title: LogEntry
required:
- commitMeta
type: object
properties:
commitMeta:
$ref: "#/components/schemas/CommitMeta_V2"
parentCommitHash:
type: string
operations:
type: array
items:
$ref: "#/components/schemas/Operation_V2"
LogResponse:
title: LogResponse
required:
- logEntries
type: object
properties:
hasMore:
type: boolean
token:
type: string
logEntries:
type: array
items:
$ref: "#/components/schemas/LogEntry"
LogResponse_V1:
title: LogResponse
required:
- logEntries
type: object
properties:
hasMore:
type: boolean
token:
type: string
logEntries:
type: array
items:
$ref: "#/components/schemas/LogEntry_V1"
LogResponse_V2:
title: LogResponse
required:
- logEntries
type: object
properties:
hasMore:
type: boolean
token:
type: string
logEntries:
type: array
items:
$ref: "#/components/schemas/LogEntry_V2"
Merge:
title: Merge Operation
required:
- fromRefName
- fromHash
type: object
properties:
fromRefName:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
fromHash:
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
keyMergeModes:
type: array
items:
$ref: "#/components/schemas/MergeKeyBehavior"
defaultKeyMergeMode:
$ref: "#/components/schemas/MergeBehavior"
dryRun:
type: boolean
fetchAdditionalInfo:
type: boolean
returnConflictAsResult:
type: boolean
Merge1:
title: Merge Operation
required:
- fromRefName
type: object
properties:
message:
description: "Optional commit message for this merge request\n\nIf not set,\
\ the server will generate a commit message automatically using metadata\
\ from the \nmerged commits."
type: string
deprecated: true
fromHash:
description: |-
The hash of the last commit to merge.
This commit must be present in the history on 'fromRefName' before the first common parent with respect to the target branch.
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
fromRefName:
description: |
The name of the reference that contains the 'source' commits for the requested merge or transplant operation.
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
keyMergeModes:
description: |
Specific merge behaviour requests by content key.
The default is set by the `defaultKeyMergeMode` parameter.
type: array
items:
$ref: "#/components/schemas/MergeKeyBehavior"
defaultKeyMergeMode:
description: |
The default merge mode. If not set, `NORMAL` is assumed.
This settings applies to key thaWhen set to 'true' instructs the server to validate the request
but to avoid committing any changes.t are not explicitly mentioned in the `keyMergeModes` property.
type: string
allOf:
- $ref: "#/components/schemas/MergeBehavior"
dryRun:
description: |
When set to 'true' instructs the server to validate the request but to avoid committing any changes.
type: boolean
fetchAdditionalInfo:
description: |
Whether to provide optional response data.
type: boolean
returnConflictAsResult:
description: When set to 'true' instructs the server to produce normal (non-error)
responses in case a conflict is detected and report conflict details in
the response payload.
type: boolean
commitMeta:
$ref: "#/components/schemas/CommitMeta"
MergeBehavior:
enum:
- NORMAL
- FORCE
- DROP
type: string
MergeBehavior_V1:
enum:
- NORMAL
- FORCE
- DROP
type: string
MergeBehavior_V2:
enum:
- NORMAL
- FORCE
- DROP
type: string
MergeKeyBehavior:
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
mergeBehavior:
$ref: "#/components/schemas/MergeBehavior"
expectedTargetContent:
$ref: "#/components/schemas/Content"
resolvedContent:
$ref: "#/components/schemas/Content"
expectedTargetDocumentation:
$ref: "#/components/schemas/Documentation"
resolvedDocumentation:
$ref: "#/components/schemas/Documentation"
metadata:
type: array
items:
$ref: "#/components/schemas/ContentMetadata"
MergeResponse:
title: Merge Response
type: object
properties:
resultantTargetHash:
type: string
commonAncestor:
type: string
targetBranch:
type: string
effectiveTargetHash:
type: string
expectedHash:
type: string
details:
type: array
items:
$ref: "#/components/schemas/ContentKeyDetails"
MergeResponse_V1:
title: Merge Response
type: object
properties:
resultantTargetHash:
type: string
commonAncestor:
type: string
targetBranch:
type: string
effectiveTargetHash:
type: string
expectedHash:
type: string
details:
type: array
items:
$ref: "#/components/schemas/ContentKeyDetails_V1"
MergeResponse_V2:
title: Merge Response
type: object
properties:
resultantTargetHash:
type: string
commonAncestor:
type: string
targetBranch:
type: string
effectiveTargetHash:
type: string
expectedHash:
type: string
details:
type: array
items:
$ref: "#/components/schemas/ContentKeyDetails_V2"
Namespace:
required:
- elements
- properties
type: object
properties:
id:
type: string
elements:
type: array
items:
type: string
properties:
type: object
additionalProperties:
type: string
NamespaceUpdate:
type: object
properties:
propertyUpdates:
type: object
additionalProperties:
type: string
propertyRemovals:
uniqueItems: true
type: array
items:
type: string
Namespace_V1:
required:
- elements
- properties
type: object
properties:
id:
type: string
elements:
type: array
items:
type: string
properties:
type: object
additionalProperties:
type: string
Namespace_V2:
required:
- elements
- properties
type: object
properties:
id:
type: string
elements:
type: array
items:
type: string
properties:
type: object
additionalProperties:
type: string
NessieConfiguration:
title: NessieConfiguration
description: Configuration object to tell a client how a server is configured.
type: object
properties:
defaultBranch:
type: string
minSupportedApiVersion:
format: int32
type: integer
maxSupportedApiVersion:
format: int32
type: integer
actualApiVersion:
format: int32
type: integer
specVersion:
description: |-
Semver version representing the behavior of the Nessie server.
Additional functionality might be added to Nessie servers within a "spec major version" in a non-breaking way. Clients are encouraged to check the spec version when using such added functionality.
type: string
noAncestorHash:
type: string
repositoryCreationTimestamp:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
oldestPossibleCommitTimestamp:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
additionalProperties:
type: object
additionalProperties:
type: string
NessieConfiguration_V1:
title: NessieConfiguration
description: Configuration object to tell a client how a server is configured.
type: object
properties:
defaultBranch:
type: string
maxSupportedApiVersion:
format: int32
type: integer
specVersion:
description: |-
Semver version representing the behavior of the Nessie server.
Additional functionality might be added to Nessie servers within a "spec major version" in a non-breaking way. Clients are encouraged to check the spec version when using such added functionality.
type: string
NessieConfiguration_V2:
title: NessieConfiguration
description: Configuration object to tell a client how a server is configured.
type: object
properties:
defaultBranch:
type: string
minSupportedApiVersion:
format: int32
type: integer
maxSupportedApiVersion:
format: int32
type: integer
actualApiVersion:
format: int32
type: integer
specVersion:
description: |-
Semver version representing the behavior of the Nessie server.
Additional functionality might be added to Nessie servers within a "spec major version" in a non-breaking way. Clients are encouraged to check the spec version when using such added functionality.
type: string
noAncestorHash:
type: string
repositoryCreationTimestamp:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
oldestPossibleCommitTimestamp:
format: date-time
type: string
example: 2022-03-10T16:15:50Z
additionalProperties:
type: object
additionalProperties:
type: string
Operation:
title: Operation
description: |-
Describes an operation to be performed against one content object.
The Nessie backend will validate the correctness of the operations.
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
oneOf:
- $ref: "#/components/schemas/Put"
- $ref: "#/components/schemas/Unchanged"
- $ref: "#/components/schemas/Delete"
discriminator:
propertyName: type
mapping:
PUT: "#/components/schemas/Put"
UNCHANGED: "#/components/schemas/Unchanged"
DELETE: "#/components/schemas/Delete"
Operation_V1:
title: Operation
description: |-
Describes an operation to be performed against one content object.
The Nessie backend will validate the correctness of the operations.
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V1"
oneOf:
- $ref: "#/components/schemas/Put_V1"
- $ref: "#/components/schemas/Unchanged_V1"
- $ref: "#/components/schemas/Delete_V1"
discriminator:
propertyName: type
mapping:
PUT: "#/components/schemas/Put_V1"
UNCHANGED: "#/components/schemas/Unchanged_V1"
DELETE: "#/components/schemas/Delete_V1"
Operation_V2:
title: Operation
description: |-
Describes an operation to be performed against one content object.
The Nessie backend will validate the correctness of the operations.
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V2"
oneOf:
- $ref: "#/components/schemas/Put_V2"
- $ref: "#/components/schemas/Unchanged_V2"
- $ref: "#/components/schemas/Delete_V2"
discriminator:
propertyName: type
mapping:
PUT: "#/components/schemas/Put_V2"
UNCHANGED: "#/components/schemas/Unchanged_V2"
DELETE: "#/components/schemas/Delete_V2"
Operations:
title: Operations
required:
- commitMeta
- operations
type: object
properties:
commitMeta:
$ref: "#/components/schemas/CommitMeta"
operations:
type: array
items:
$ref: "#/components/schemas/Operation"
Put:
title: Put-'Content'-operation for a 'ContentKey'.
description: |-
Used to add new content or to update existing content.
A new content object is created by populating the `value` field, the content-id in the content object must not be present (null).
A content object is updated by populating the `value` containing the correct content-id.
If the key for a content shall change (aka a rename), then use a `Delete` operation using the current (old) key and a `Put` operation using the new key with the `value` having the correct content-id. Both operations must happen in the same commit.
A content object can be replaced (think: `DROP TABLE xyz` + `CREATE TABLE xyz`) with a `Delete` operation and a `Put` operation for a content using a `value`representing a new content object, so without a content-id, in the same commit.
required:
- key
- content
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
content:
$ref: "#/components/schemas/Content"
expectedContent:
type: object
allOf:
- $ref: "#/components/schemas/Content"
deprecated: true
metadata:
type: array
items:
$ref: "#/components/schemas/ContentMetadata"
documentation:
$ref: "#/components/schemas/Documentation"
Put_V1:
title: Put-'Content'-operation for a 'ContentKey'.
description: |-
Used to add new content or to update existing content.
A new content object is created by populating the `value` field, the content-id in the content object must not be present (null).
A content object is updated by populating the `value` containing the correct content-id.
If the key for a content shall change (aka a rename), then use a `Delete` operation using the current (old) key and a `Put` operation using the new key with the `value` having the correct content-id. Both operations must happen in the same commit.
A content object can be replaced (think: `DROP TABLE xyz` + `CREATE TABLE xyz`) with a `Delete` operation and a `Put` operation for a content using a `value`representing a new content object, so without a content-id, in the same commit.
required:
- key
- content
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V1"
content:
$ref: "#/components/schemas/Content_V1"
expectedContent:
type: object
allOf:
- $ref: "#/components/schemas/Content_V1"
deprecated: true
Put_V2:
title: Put-'Content'-operation for a 'ContentKey'.
description: |-
Used to add new content or to update existing content.
A new content object is created by populating the `value` field, the content-id in the content object must not be present (null).
A content object is updated by populating the `value` containing the correct content-id.
If the key for a content shall change (aka a rename), then use a `Delete` operation using the current (old) key and a `Put` operation using the new key with the `value` having the correct content-id. Both operations must happen in the same commit.
A content object can be replaced (think: `DROP TABLE xyz` + `CREATE TABLE xyz`) with a `Delete` operation and a `Put` operation for a content using a `value`representing a new content object, so without a content-id, in the same commit.
required:
- key
- content
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V2"
content:
$ref: "#/components/schemas/Content_V2"
metadata:
type: array
items:
$ref: "#/components/schemas/ContentMetadata_V2"
documentation:
$ref: "#/components/schemas/Documentation_V2"
Reference:
title: Reference
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
hash:
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
metadata:
type: object
allOf:
- $ref: "#/components/schemas/ReferenceMetadata"
nullable: true
oneOf:
- $ref: "#/components/schemas/Branch"
- $ref: "#/components/schemas/Tag"
- $ref: "#/components/schemas/Detached"
discriminator:
propertyName: type
mapping:
TAG: "#/components/schemas/Tag"
BRANCH: "#/components/schemas/Branch"
DETACHED: "#/components/schemas/Detached"
ReferenceCutoffPolicy:
title: References cutoff policy
description: Cutoff policies per reference names. Supplied as a ref-name-pattern=policy
tuple. Reference name patterns are regular expressions.
type: object
properties:
referenceNamePattern:
description: Reference name patterns as a regular expressions.
type: string
policy:
description: "Policies can be one of: - number of commits as an integer\
\ value - a duration (see java.time.Duration) - an ISO instant - 'NONE',\
\ means everything's considered as live"
type: string
ReferenceCutoffPolicy_V2:
title: References cutoff policy
description: Cutoff policies per reference names. Supplied as a ref-name-pattern=policy
tuple. Reference name patterns are regular expressions.
type: object
properties:
referenceNamePattern:
description: Reference name patterns as a regular expressions.
type: string
policy:
description: "Policies can be one of: - number of commits as an integer\
\ value - a duration (see java.time.Duration) - an ISO instant - 'NONE',\
\ means everything's considered as live"
type: string
ReferenceHistoryResponse:
title: ReferenceHistoryResponse
description: |-
Describes the consistency status of a named reference.
Possible values of the `CommitConsistency` enum:
- `NOT_CHECKED` means: Consistency was not checked.
- `COMMIT_CONSISTENT` means: The commit object, its index information and all reachable content is present.
- `COMMIT_CONTENT_INCONSISTENT` means: The commit object is present and its index is accessible, but some content reachable from the commit is not present.
- `COMMIT_INCONSISTENT` means: The commit is inconsistent in a way that makes it impossible to access the commit, for example if the commit object itself or its index information is missing.
required:
- reference
- current
- previous
- commitLogConsistency
type: object
properties:
reference:
$ref: "#/components/schemas/Reference"
current:
description: Consistency status of the current HEAD commit.
type: object
allOf:
- $ref: "#/components/schemas/ReferenceHistoryState"
previous:
description: "Consistency status of the recorded recent HEADs of the reference,\
\ including re-assign operations."
type: array
items:
$ref: "#/components/schemas/ReferenceHistoryState"
commitLogConsistency:
description: "Combined consistency status of the commit-log of the reference,\
\ if requested by the client."
type: string
allOf:
- $ref: "#/components/schemas/CommitConsistency"
ReferenceHistoryResponse_V2:
title: ReferenceHistoryResponse
description: |-
Describes the consistency status of a named reference.
Possible values of the `CommitConsistency` enum:
- `NOT_CHECKED` means: Consistency was not checked.
- `COMMIT_CONSISTENT` means: The commit object, its index information and all reachable content is present.
- `COMMIT_CONTENT_INCONSISTENT` means: The commit object is present and its index is accessible, but some content reachable from the commit is not present.
- `COMMIT_INCONSISTENT` means: The commit is inconsistent in a way that makes it impossible to access the commit, for example if the commit object itself or its index information is missing.
required:
- reference
- current
- previous
- commitLogConsistency
type: object
properties:
reference:
$ref: "#/components/schemas/Reference_V2"
current:
description: Consistency status of the current HEAD commit.
type: object
allOf:
- $ref: "#/components/schemas/ReferenceHistoryState_V2"
previous:
description: "Consistency status of the recorded recent HEADs of the reference,\
\ including re-assign operations."
type: array
items:
$ref: "#/components/schemas/ReferenceHistoryState_V2"
commitLogConsistency:
description: "Combined consistency status of the commit-log of the reference,\
\ if requested by the client."
type: string
allOf:
- $ref: "#/components/schemas/CommitConsistency_V2"
ReferenceHistoryState:
title: ReferenceHistoryState
description: |-
Describes the consistency status of a commit within a `ReferenceHistoryResponse` object.
Possible values of the `CommitConsistency` enum:
- `NOT_CHECKED` means: Consistency was not checked.
- `COMMIT_CONSISTENT` means: The commit object, its index information and all reachable content is present.
- `COMMIT_CONTENT_INCONSISTENT` means: The commit object is present and its index is accessible, but some content reachable from the commit is not present.
- `COMMIT_INCONSISTENT` means: The commit is inconsistent in a way that makes it impossible to access the commit, for example if the commit object itself or its index information is missing.
type: object
properties:
commitHash:
description: Nessie commit ID.
type: string
commitConsistency:
description: Consistency status of the commit.
type: string
allOf:
- $ref: "#/components/schemas/CommitConsistency"
meta:
description: "Meta information from the commit, if available."
type: object
allOf:
- $ref: "#/components/schemas/CommitMeta"
ReferenceHistoryState_V2:
title: ReferenceHistoryState
description: |-
Describes the consistency status of a commit within a `ReferenceHistoryResponse` object.
Possible values of the `CommitConsistency` enum:
- `NOT_CHECKED` means: Consistency was not checked.
- `COMMIT_CONSISTENT` means: The commit object, its index information and all reachable content is present.
- `COMMIT_CONTENT_INCONSISTENT` means: The commit object is present and its index is accessible, but some content reachable from the commit is not present.
- `COMMIT_INCONSISTENT` means: The commit is inconsistent in a way that makes it impossible to access the commit, for example if the commit object itself or its index information is missing.
type: object
properties:
commitHash:
description: Nessie commit ID.
type: string
commitConsistency:
description: Consistency status of the commit.
type: string
allOf:
- $ref: "#/components/schemas/CommitConsistency_V2"
meta:
description: "Meta information from the commit, if available."
type: object
allOf:
- $ref: "#/components/schemas/CommitMeta_V2"
ReferenceMetadata:
title: ReferenceMetadata
description: |+
Only returned by the server when explicitly requested by the client and contains the following information:
- numCommitsAhead (number of commits ahead of the default branch)
- numCommitsBehind (number of commits behind the default branch)
- commitMetaOfHEAD (the commit metadata of the HEAD commit)
- commonAncestorHash (the hash of the common ancestor in relation to the default branch).
- numTotalCommits (the total number of commits in this reference).
type: object
properties:
numCommitsAhead:
format: int32
type: integer
numCommitsBehind:
format: int32
type: integer
commitMetaOfHEAD:
$ref: "#/components/schemas/CommitMeta"
commonAncestorHash:
type: string
numTotalCommits:
format: int64
type: integer
ReferenceMetadata_V1:
title: ReferenceMetadata
description: |+
Only returned by the server when explicitly requested by the client and contains the following information:
- numCommitsAhead (number of commits ahead of the default branch)
- numCommitsBehind (number of commits behind the default branch)
- commitMetaOfHEAD (the commit metadata of the HEAD commit)
- commonAncestorHash (the hash of the common ancestor in relation to the default branch).
- numTotalCommits (the total number of commits in this reference).
type: object
properties:
numCommitsAhead:
format: int32
type: integer
numCommitsBehind:
format: int32
type: integer
commitMetaOfHEAD:
$ref: "#/components/schemas/CommitMeta_V1"
commonAncestorHash:
type: string
numTotalCommits:
format: int64
type: integer
ReferenceMetadata_V2:
title: ReferenceMetadata
description: |+
Only returned by the server when explicitly requested by the client and contains the following information:
- numCommitsAhead (number of commits ahead of the default branch)
- numCommitsBehind (number of commits behind the default branch)
- commitMetaOfHEAD (the commit metadata of the HEAD commit)
- commonAncestorHash (the hash of the common ancestor in relation to the default branch).
- numTotalCommits (the total number of commits in this reference).
type: object
properties:
numCommitsAhead:
format: int32
type: integer
numCommitsBehind:
format: int32
type: integer
commitMetaOfHEAD:
$ref: "#/components/schemas/CommitMeta_V2"
commonAncestorHash:
type: string
numTotalCommits:
format: int64
type: integer
ReferenceType:
enum:
- branch
- tag
type: string
Reference_V1:
title: Reference
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
hash:
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
metadata:
type: object
allOf:
- $ref: "#/components/schemas/ReferenceMetadata_V1"
nullable: true
oneOf:
- $ref: "#/components/schemas/Branch_V1"
- $ref: "#/components/schemas/Tag_V1"
- $ref: "#/components/schemas/Detached_V1"
discriminator:
propertyName: type
mapping:
TAG: "#/components/schemas/Tag_V1"
BRANCH: "#/components/schemas/Branch_V1"
DETACHED: "#/components/schemas/Detached_V1"
Reference_V2:
title: Reference
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
hash:
pattern: "^[0-9a-fA-F]{8,64}$"
type: string
metadata:
type: object
allOf:
- $ref: "#/components/schemas/ReferenceMetadata_V2"
nullable: true
oneOf:
- $ref: "#/components/schemas/Branch_V2"
- $ref: "#/components/schemas/Tag_V2"
- $ref: "#/components/schemas/Detached_V2"
discriminator:
propertyName: type
mapping:
TAG: "#/components/schemas/Tag_V2"
BRANCH: "#/components/schemas/Branch_V2"
DETACHED: "#/components/schemas/Detached_V2"
ReferencesResponse_V1:
required:
- references
type: object
properties:
hasMore:
type: boolean
token:
type: string
references:
type: array
items:
$ref: "#/components/schemas/Reference_V1"
ReferencesResponse_V2:
required:
- references
type: object
properties:
hasMore:
type: boolean
token:
type: string
references:
type: array
items:
$ref: "#/components/schemas/Reference_V2"
RepositoryConfig:
title: RepositoryConfig
type: object
anyOf:
- $ref: "#/components/schemas/GarbageCollectorConfig"
discriminator:
propertyName: type
mapping:
GARBAGE_COLLECTOR: "#/components/schemas/GarbageCollectorConfig"
RepositoryConfigResponse:
title: RepositoryConfigResponse
type: object
properties:
configs:
title: Repository configuration objects for the requested types.
description: The existing configuration objects for the requested types
will be returned. Non-existing config objects will not be returned.
type: array
items:
$ref: "#/components/schemas/RepositoryConfig"
RepositoryConfigResponse_V2:
title: Repository configuration objects for the requested types.
description: The existing configuration objects for the requested types will
be returned. Non-existing config objects will not be returned.
type: object
properties:
configs:
title: Repository configuration objects for the requested types.
description: The existing configuration objects for the requested types
will be returned. Non-existing config objects will not be returned.
type: array
items:
$ref: "#/components/schemas/RepositoryConfig_V2"
RepositoryConfigType:
description: "Declares the type of a Nessie repository config object, which\
\ is currently only GARBAGE_COLLECTOR, which is the discriminator mapping\
\ value of the 'RepositoryConfig' type."
type: string
RepositoryConfig_V2:
title: The previous state of the repository configuration object.
description: "When a repository configuration for the same type as in the request\
\ object did not exist, the response object will be null. Otherwise, if the\
\ configuration was updated, the old value will be returned."
type: object
anyOf:
- $ref: "#/components/schemas/GarbageCollectorConfig_V2"
discriminator:
propertyName: type
mapping:
GARBAGE_COLLECTOR: "#/components/schemas/GarbageCollectorConfig_V2"
SingleReferenceResponse:
title: SingleReferenceResponse
required:
- reference
type: object
properties:
reference:
$ref: "#/components/schemas/Reference"
SingleReferenceResponse_V2:
title: SingleReferenceResponse
required:
- reference
type: object
properties:
reference:
$ref: "#/components/schemas/Reference_V2"
Tag:
title: Tag
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata"
hash:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
Tag_V1:
title: Tag
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata_V1"
hash:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
Tag_V2:
title: Tag
required:
- name
type: object
properties:
name:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
metadata:
$ref: "#/components/schemas/ReferenceMetadata_V2"
hash:
pattern: "^([0-9a-fA-F]{8,64})?((?:([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-9]+)))*)$"
type: string
Transplant:
title: Transplant
required:
- fromRefName
- hashesToTransplant
type: object
properties:
fromRefName:
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
hashesToTransplant:
uniqueItems: true
type: array
items:
type: string
keyMergeModes:
type: array
items:
$ref: "#/components/schemas/MergeKeyBehavior"
defaultKeyMergeMode:
$ref: "#/components/schemas/MergeBehavior"
dryRun:
type: boolean
fetchAdditionalInfo:
type: boolean
returnConflictAsResult:
type: boolean
Transplant1:
title: Transplant
required:
- fromRefName
- hashesToTransplant
type: object
properties:
message:
description: Commit message for this transplant request.
type: string
hashesToTransplant:
description: Lists the hashes of commits that should be transplanted into
the target branch.
uniqueItems: true
type: array
items:
type: string
fromRefName:
description: |
The name of the reference that contains the 'source' commits for the requested merge or transplant operation.
pattern: "^(?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-$"
type: string
keyMergeModes:
description: |
Specific merge behaviour requests by content key.
The default is set by the `defaultKeyMergeMode` parameter.
type: array
items:
$ref: "#/components/schemas/MergeKeyBehavior"
defaultKeyMergeMode:
description: |
The default merge mode. If not set, `NORMAL` is assumed.
This settings applies to key thaWhen set to 'true' instructs the server to validate the request
but to avoid committing any changes.t are not explicitly mentioned in the `keyMergeModes` property.
type: string
allOf:
- $ref: "#/components/schemas/MergeBehavior"
dryRun:
description: |
When set to 'true' instructs the server to validate the request but to avoid committing any changes.
type: boolean
fetchAdditionalInfo:
description: |
Whether to provide optional response data.
type: boolean
returnConflictAsResult:
description: When set to 'true' instructs the server to produce normal (non-error)
responses in case a conflict is detected and report conflict details in
the response payload.
type: boolean
Type:
description: "Declares the type of a Nessie content object, which is currently\
\ one of ICEBERG_TABLE, DELTA_LAKE_TABLE, ICEBERG_VIEW, NAMESPACE or UDF,\
\ which are the discriminator mapping values of the 'Content' type."
type: string
UDF:
required:
- sqlText
type: object
properties:
id:
type: string
sqlText:
pattern: \S
type: string
deprecated: true
dialect:
type: string
deprecated: true
versionId:
type: string
signatureId:
type: string
metadataLocation:
type: string
UDF_V1:
required:
- sqlText
type: object
properties:
id:
type: string
sqlText:
pattern: \S
type: string
deprecated: true
dialect:
type: string
deprecated: true
versionId:
type: string
signatureId:
type: string
metadataLocation:
type: string
UDF_V2:
required:
- sqlText
type: object
properties:
id:
type: string
sqlText:
pattern: \S
type: string
deprecated: true
dialect:
type: string
deprecated: true
versionId:
type: string
signatureId:
type: string
metadataLocation:
type: string
Unchanged:
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey"
Unchanged_V1:
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V1"
Unchanged_V2:
required:
- key
type: object
properties:
key:
$ref: "#/components/schemas/ContentKey_V2"
UpdateRepositoryConfigRequest:
title: UpdateRepositoryConfigRequest
type: object
properties:
config:
$ref: "#/components/schemas/RepositoryConfig"
UpdateRepositoryConfigResponse:
title: UpdateRepositoryConfigResponse
type: object
properties:
previous:
title: The previous state of the repository configuration object.
description: "When a repository configuration for the same type as in the\
\ request object did not exist, the response object will be null. Otherwise,\
\ if the configuration was updated, the old value will be returned."
type: object
anyOf:
- $ref: "#/components/schemas/GarbageCollectorConfig"
discriminator:
propertyName: type
mapping:
GARBAGE_COLLECTOR: "#/components/schemas/GarbageCollectorConfig"
UpdateRepositoryConfigResponse_V2:
title: The previous state of the repository configuration object.
description: "When a repository configuration for the same type as in the request\
\ object did not exist, the response object will be null. Otherwise, if the\
\ configuration was updated, the old value will be returned."
type: object
properties:
previous:
title: The previous state of the repository configuration object.
description: "When a repository configuration for the same type as in the\
\ request object did not exist, the response object will be null. Otherwise,\
\ if the configuration was updated, the old value will be returned."
type: object
anyOf:
- $ref: "#/components/schemas/GarbageCollectorConfig_V2"
discriminator:
propertyName: type
mapping:
GARBAGE_COLLECTOR: "#/components/schemas/GarbageCollectorConfig_V2"
examples:
nessieConfigV1:
value:
defaultBranch: main
maxSupportedApiVersion: 2
nessieConfig:
value:
defaultBranch: main
minSupportedApiVersion: 1
maxSupportedApiVersion: 2
specVersion: 2.0.0
namespace:
value: a.b.c
ref:
value: main
refWithHash:
value: main@1122334455667788112233445566778811223344556677881122334455667788
refWithTimestampMillisSinceEpoch:
value: main*1685185847230
refWithTimestampInstant:
value: main*2021-04-07T14:42:25.534748Z
refWithNthPredecessor:
value: main~10
refWithMergeParent:
value: main@1122334455667788112233445566778811223344556677881122334455667788^2
refDefault:
value: "-"
refDetached:
value: '@1122334455667788112233445566778811223344556677881122334455667788'
refForDiffWithHash:
value: main@1122334455667788112233445566778811223344556677881122334455667788
referenceType:
value: branch
hash:
value: "1122334455667788112233445566778811223344556677881122334455667788"
nullHash: {}
refObj:
value:
type: BRANCH
hash: "1122334455667788112233445566778811223344556677881122334455667788"
name: main
refObjNew:
value:
type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
tagObj:
value:
type: TAG
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleTag
ContentKeyGet:
value: example.key
ContentKey:
value:
elements:
- example
- key
namespaceName:
value: a.b.c
emptyNamespaceName: {}
namespacesResponse:
value:
namespaces:
- type: NAMESPACE
elements:
- a
- b.c
- d
- type: NAMESPACE
elements:
- a
- b
- d
namespaceUpdate:
value:
propertyUpdates:
key1: value1
key2: value2
propertyRemovals:
- key3
- key4
iceberg:
value:
type: ICEBERG_TABLE
id: b874b5d5-f926-4eed-9be7-b2380d9810c0
metadataLocation: /path/to/metadata/
snapshotId: 1
schemaId: 2
specId: 3
sortOrderId: 4
expr_by_namespace:
value: entry.namespace.startsWith('a.b.c')
expr_by_contentType:
value: "entry.contentType in ['ICEBERG_TABLE','DELTA_LAKE_TABLE']"
expr_by_namespace_and_contentType:
value: "entry.namespace.startsWith('some.name.space') && entry.contentType in\
\ ['ICEBERG_TABLE','DELTA_LAKE_TABLE']"
expr_by_commit_author:
value: commit.author=='nessie_author'
expr_by_commit_committer:
value: commit.committer=='nessie_committer'
expr_by_commitTime:
value: timestamp(commit.commitTime) > timestamp('2021-05-31T08:23:15Z')
expr_by_commit_operations_in_namespace:
value: "operations.exists(op, op.key.startsWith('some.name.space.'))"
expr_by_commit_operations_table_name:
value: "operations.exists(op, op.name == 'BaseTable')"
expr_by_commit_operations_type:
value: "operations.exists(op, op.type == 'PUT')"
expr_by_refType:
value: refType == 'BRANCH'
expr_by_ref_name:
value: ref.name == 'my-tag-or-branch'
expr_by_ref_commit:
value: commit.message == 'invent awesome things'
commitMessage:
value: Example Commit Message
multiGetResponse:
value:
contents:
- content:
type: ICEBERG_TABLE
id: b874b5d5-f926-4eed-9be7-b2380d9810c0
metadataLocation: /path/to/metadata/
snapshotId: 1
schemaId: 2
specId: 3
sortOrderId: 4
key:
elements:
- example
- key
multiGetRequest:
value:
requestedKeys:
- elements:
- example
- key
entriesResponse:
value:
token: null
hasMore: false
entries:
- name:
elements:
- example
- key
type: ICEBERG_TABLE
entriesResponseV2:
value:
token: xxx
hasMore: false
effectiveReference:
type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
entries:
- name:
elements:
- example
- key
type: ICEBERG_TABLE
contentId: f350b391-f492-41eb-9959-730a8c49f01e
content:
type: ICEBERG_TABLE
id: f350b391-f492-41eb-9959-730a8c49f01e
metadataLocation: /path/to/metadata/
snapshotId: 23
schemaId: 15
specId: 15
sortOrderId: 15
types:
value:
- ICEBERG_TABLE
merge:
value:
fromHash: abcdef4242424242424242424242beef00dead42112233445566778899001122
fromRefName: source-ref-name
defaultKeyMergeMode: NORMAL
keyMergeModes:
- key:
elements:
- example
- key
mergeBehavior: FORCE
dryRun: false
fetchAdditionalInfo: false
returnConflictAsResult: true
transplant:
value:
hashesToTransplant:
- abcdef4242424242424242424242beef00dead42112233445566778899001122
fromRefName: source-ref-name
defaultKeyMergeMode: NORMAL
keyMergeModes:
- key:
elements:
- example
- key
mergeBehavior: FORCE
dryRun: false
fetchAdditionalInfo: false
returnConflictAsResult: true
mergeResponseSuccess:
value:
wasApplied: true
wasSuccessful: true
resultantTargetHash: 8a2f19888eb620c25b0d2cbcddfdf56fb2d3e9dd443c6d29e37c567493fc5d3b
commonAncestor: abcdef4242424242424242424242beef00dead42112233445566778899001122
targetBranch: main
effectiveTargetHash: e9058b675c519b3542cd8155aed42ecf1ddb4e55874e3eb241b30b96f861566a
expectedHash: "1122334455667788112233445566778811223344556677881122334455667788"
details:
- key:
elements:
- example
- key
mergeBehavior: NORMAL
mergeResponseFail:
value:
wasApplied: false
wasSuccessful: false
resultantTargetHash: 8a2f19888eb620c25b0d2cbcddfdf56fb2d3e9dd443c6d29e37c567493fc5d3b
commonAncestor: abcdef4242424242424242424242beef00dead42112233445566778899001122
targetBranch: main
effectiveTargetHash: 8a2f19888eb620c25b0d2cbcddfdf56fb2d3e9dd443c6d29e37c567493fc5d3b
expectedHash: "1122334455667788112233445566778811223344556677881122334455667788"
details:
- key:
elements:
- example
- key
mergeBehavior: NORMAL
conflict:
type: KEY_EXISTS
message: key 'example.key' already exists
key:
elements:
- example
- key
operations:
value:
commitMeta:
author: authorName
authorTime: 2021-04-07T14:42:25.534748Z
message: Example Commit Message
properties:
additionalProp1: xxx
additionalProp2: yyy
additionalProp3: zzz
signedOffBy: signedOffByName
operations:
- type: PUT
key:
elements:
- table1
content:
type: ICEBERG_TABLE
metadataLocation: /path/to/metadata/
snapshotId: 1
schemaId: 2
specId: 3
sortOrderId: 4
logResponseAdditionalInfo:
value:
token: xxx
hasMore: false
logEntries:
- commitMeta:
author: authorName
authorTime: 2021-04-07T14:42:25.534748Z
commitTime: 2021-04-07T14:42:25.534748Z
committer: committerName
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
message: Example Commit Message
properties:
additionalProp1: xxx
additionalProp2: yyy
additionalProp3: zzz
signedOffBy: signedOffByName
parentCommitHash: "1122334455667788112233445566778811223344556677881122334455667788"
operations:
- type: DELETE
key:
elements:
- deleted
- table
- type: PUT
key:
elements:
- example
- key
content:
type: ICEBERG_TABLE
id: b874b5d5-f926-4eed-9be7-b2380d9810c0
metadataLocation: /path/to/metadata/
snapshotId: 1
schemaId: 2
specId: 3
sortOrderId: 4
logResponseSimple:
value:
token: xxx
hasMore: false
logEntries:
- commitMeta:
author: authorName
authorTime: 2021-04-07T14:42:25.534748Z
commitTime: 2021-04-07T14:42:25.534748Z
committer: committerName
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
message: Example Commit Message
properties:
additionalProp1: xxx
additionalProp2: yyy
additionalProp3: zzz
signedOffBy: signedOffByName
multipleContentsResponse:
value:
contents:
- content:
type: ICEBERG_TABLE
id: b874b5d5-f926-4eed-9be7-b2380d9810c0
metadataLocation: /path/to/metadata/
snapshotId: 1
schemaId: 2
specId: 3
sortOrderId: 4
key:
elements:
- example
- key
effectiveReference:
type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
commitResponse:
value:
targetBranch:
type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
addedContents:
- contentId: 7fe924d9-45af-574e-9bbc-51b48077017e
key:
elements:
- example
- key
contentResponseIceberg:
value:
content:
type: ICEBERG_TABLE
id: b874b5d5-f926-4eed-9be7-b2380d9810c0
metadataLocation: /path/to/metadata/
snapshotId: 1
schemaId: 2
specId: 3
sortOrderId: 4
effectiveReference:
type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
singleReferenceResponse:
value:
reference:
type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
singleReferenceResponseWithMetadata:
value:
reference:
type: BRANCH
hash: 84c57a20c5e956af4af40f3cc34ecc8a9028b9586da135c79011b1867aa3191d
name: main
metadata:
commitMetaOfHEAD:
hash: 84c57a20c5e956af4af40f3cc34ecc8a9028b9586da135c79011b1867aa3191d
committer: ""
author: nessie-author
signedOffBy: null
message: update table
commitTime: 2021-11-26T08:01:13.855974Z
authorTime: 2021-11-26T08:01:13.852826Z
properties: {}
referencesResponse:
value:
token: null
hasMore: false
references:
- type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
- type: TAG
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleTag
- type: BRANCH
hash: "1122334455667788112233445566778811223344556677881122334455667788"
name: main
referenceHistoryResponse:
value:
reference:
type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
current:
pointer: abcdef4242424242424242424242beef00dead42112233445566778899001122
commitConsistency: COMMIT_CONSISTENT
meta:
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
committer: ""
author: nessie-author
signedOffBy: null
message: update table
commitTime: 2021-11-26T08:01:13.855974Z
authorTime: 2021-11-26T08:01:13.852826Z
properties: {}
previous:
- pointer: 84c57a20c5e956af4af40f3cc34ecc8a9028b9586da135c79011b1867aa3191d
commitConsistency: COMMIT_CONSISTENT
meta:
hash: 84c57a20c5e956af4af40f3cc34ecc8a9028b9586da135c79011b1867aa3191d
committer: ""
author: nessie-author
signedOffBy: null
message: add table
commitTime: 2021-11-26T07:01:13.855974Z
authorTime: 2021-11-26T07:01:13.852826Z
properties: {}
- pointer: "1122334455667788112233445566778811223344556677881122334455667788"
commitConsistency: COMMIT_CONSISTENT
meta:
hash: "1122334455667788112233445566778811223344556677881122334455667788"
committer: ""
author: nessie-author
signedOffBy: null
message: add table
commitTime: 2021-11-26T06:01:13.855974Z
authorTime: 2021-11-26T06:01:13.852826Z
properties: {}
commitLogConsistency: NOT_CHECKED
referencesResponseWithMetadata:
value:
token: null
hasMore: false
references:
- type: BRANCH
hash: 84c57a20c5e956af4af40f3cc34ecc8a9028b9586da135c79011b1867aa3191d
name: main
metadata:
commitMetaOfHEAD:
hash: 84c57a20c5e956af4af40f3cc34ecc8a9028b9586da135c79011b1867aa3191d
committer: ""
author: nessie-author
signedOffBy: null
message: update table
commitTime: 2021-11-26T08:01:13.855974Z
authorTime: 2021-11-26T08:01:13.852826Z
properties: {}
- type: BRANCH
hash: da086850076827d2989c8ee1d7fd22f152f525d46a0441f2b22ad8119c0bbbe5
name: dev
metadata:
numCommitsAhead: 1
numCommitsBehind: 2
commonAncestorHash: "1122334455667788112233445566778811223344556677881122334455667788"
numTotalCommits: 42
commitMetaOfHEAD:
hash: da086850076827d2989c8ee1d7fd22f152f525d46a0441f2b22ad8119c0bbbe5
committer: ""
author: nessie-author
signedOffBy: null
message: update table X
commitTime: 2021-11-26T08:01:13.834397Z
authorTime: 2021-11-26T08:01:13.831371Z
properties: {}
- type: BRANCH
hash: "1122334455667788112233445566778811223344556677881122334455667788"
name: dev2
metadata:
numCommitsAhead: 0
numCommitsBehind: 2
commonAncestorHash: "1122334455667788112233445566778811223344556677881122334455667788"
- type: TAG
hash: a682bfdcd5d357b5c964ef07e2eef61fabba42cb8effa8d62357df45a6cc0371
name: testTag1
metadata:
numCommitsAhead: null
numCommitsBehind: null
commonAncestorHash: null
numTotalCommits: 42
commitMetaOfHEAD:
hash: a682bfdcd5d357b5c964ef07e2eef61fabba42cb8effa8d62357df45a6cc0371
committer: ""
author: nessie-author
signedOffBy: null
message: update table Y
commitTime: 2021-11-23T08:01:14.834397Z
authorTime: 2021-11-23T08:01:14.831371Z
properties: {}
- type: TAG
hash: da086850076827d2989c8ee1d7fd22f152f525d46a0441f2b22ad8119c0bbbe5
name: testTag2
metadata:
numCommitsAhead: null
numCommitsBehind: null
commonAncestorHash: null
numTotalCommits: 42
commitMetaOfHEAD:
hash: da086850076827d2989c8ee1d7fd22f152f525d46a0441f2b22ad8119c0bbbe5
committer: ""
author: nessie-author
signedOffBy: null
message: update table X
commitTime: 2021-11-26T08:01:13.834397Z
authorTime: 2021-11-26T08:01:13.831371Z
properties: {}
diffResponse:
value:
diffs:
- key:
elements:
- example
- key
from:
type: ICEBERG_TABLE
id: f350b391-f492-41eb-9959-730a8c49f01e
metadataLocation: /path/to/metadata/
snapshotId: 23
schemaId: 15
specId: 15
sortOrderId: 15
to:
type: ICEBERG_TABLE
id: dec31d0a-7d4b-4534-8c24-24f08eda33b2
metadataLocation: /path/to/metadata/
snapshotId: 24
schemaId: 16
specId: 16
sortOrderId: 16
diffResponseWithRef:
value:
hasMore: false
token: null
diffs:
- key:
elements:
- example
- key
from:
type: ICEBERG_TABLE
id: f350b391-f492-41eb-9959-730a8c49f01e
metadataLocation: /path/to/metadata/
snapshotId: 23
schemaId: 15
specId: 15
sortOrderId: 15
to:
type: ICEBERG_TABLE
id: dec31d0a-7d4b-4534-8c24-24f08eda33b2
metadataLocation: /path/to/metadata/
snapshotId: 24
schemaId: 16
specId: 16
sortOrderId: 16
effectiveFromReference:
type: BRANCH
hash: da086850076827d2989c8ee1d7fd22f152f525d46a0441f2b22ad8119c0bbbe5
name: dev
effectiveToReference:
type: BRANCH
hash: abcdef4242424242424242424242beef00dead42112233445566778899001122
name: exampleBranch
