Atomically commit a batch of mixed table operations

curl --request POST \
  --url {scheme}://{host}:{port}/{basePath}/v1/table/batch-commit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operations": [
    {
      "declare_table": {
        "identity": {
          "api_key": "<string>",
          "auth_token": "<string>"
        },
        "context": {},
        "id": [
          "<string>"
        ],
        "location": "<string>",
        "vend_credentials": true,
        "properties": {}
      },
      "deregister_table": {
        "identity": {
          "api_key": "<string>",
          "auth_token": "<string>"
        },
        "context": {},
        "id": [
          "<string>"
        ]
      }
    }
  ],
  "identity": {
    "api_key": "<string>",
    "auth_token": "<string>"
  },
  "context": {}
}
'

import requests

url = "{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit"

payload = {
    "operations": [
        {
            "declare_table": {
                "identity": {
                    "api_key": "<string>",
                    "auth_token": "<string>"
                },
                "context": {},
                "id": ["<string>"],
                "location": "<string>",
                "vend_credentials": True,
                "properties": {}
            },
            "deregister_table": {
                "identity": {
                    "api_key": "<string>",
                    "auth_token": "<string>"
                },
                "context": {},
                "id": ["<string>"]
            }
        }
    ],
    "identity": {
        "api_key": "<string>",
        "auth_token": "<string>"
    },
    "context": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    operations: [
      {
        declare_table: {
          identity: {api_key: '<string>', auth_token: '<string>'},
          context: {},
          id: ['<string>'],
          location: '<string>',
          vend_credentials: true,
          properties: {}
        },
        deregister_table: {
          identity: {api_key: '<string>', auth_token: '<string>'},
          context: {},
          id: ['<string>']
        }
      }
    ],
    identity: {api_key: '<string>', auth_token: '<string>'},
    context: {}
  })
};

fetch('{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "62437",
  CURLOPT_URL => "{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'operations' => [
        [
                'declare_table' => [
                                'identity' => [
                                                                'api_key' => '<string>',
                                                                'auth_token' => '<string>'
                                ],
                                'context' => [
                                                                
                                ],
                                'id' => [
                                                                '<string>'
                                ],
                                'location' => '<string>',
                                'vend_credentials' => true,
                                'properties' => [
                                                                
                                ]
                ],
                'deregister_table' => [
                                'identity' => [
                                                                'api_key' => '<string>',
                                                                'auth_token' => '<string>'
                                ],
                                'context' => [
                                                                
                                ],
                                'id' => [
                                                                '<string>'
                                ]
                ]
        ]
    ],
    'identity' => [
        'api_key' => '<string>',
        'auth_token' => '<string>'
    ],
    'context' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit"

	payload := strings.NewReader("{\n  \"operations\": [\n    {\n      \"declare_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ],\n        \"location\": \"<string>\",\n        \"vend_credentials\": true,\n        \"properties\": {}\n      },\n      \"deregister_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ]\n      }\n    }\n  ],\n  \"identity\": {\n    \"api_key\": \"<string>\",\n    \"auth_token\": \"<string>\"\n  },\n  \"context\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"operations\": [\n    {\n      \"declare_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ],\n        \"location\": \"<string>\",\n        \"vend_credentials\": true,\n        \"properties\": {}\n      },\n      \"deregister_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ]\n      }\n    }\n  ],\n  \"identity\": {\n    \"api_key\": \"<string>\",\n    \"auth_token\": \"<string>\"\n  },\n  \"context\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"operations\": [\n    {\n      \"declare_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ],\n        \"location\": \"<string>\",\n        \"vend_credentials\": true,\n        \"properties\": {}\n      },\n      \"deregister_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ]\n      }\n    }\n  ],\n  \"identity\": {\n    \"api_key\": \"<string>\",\n    \"auth_token\": \"<string>\"\n  },\n  \"context\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "declare_table": {
        "context": {},
        "transaction_id": "<string>",
        "location": "<string>",
        "storage_options": {},
        "properties": {
          "owner": "Ralph",
          "created_at": "1452120468"
        },
        "managed_versioning": true
      },
      "create_table_version": {
        "context": {},
        "transaction_id": "<string>",
        "version": {
          "version": 1,
          "manifest_path": "<string>",
          "manifest_size": 1,
          "e_tag": "<string>",
          "timestamp_millis": 123,
          "metadata": {}
        }
      },
      "delete_table_versions": {
        "context": {},
        "deleted_count": 1,
        "transaction_id": "<string>"
      },
      "deregister_table": {
        "context": {},
        "transaction_id": "<string>",
        "id": [
          "<string>"
        ],
        "location": "<string>",
        "properties": {
          "owner": "Ralph",
          "created_at": "1452120468"
        }
      }
    }
  ],
  "context": {},
  "transaction_id": "<string>"
}

{
  "type": "/errors/bad-request",
  "title": "Malformed request",
  "status": 400,
  "detail": "",
  "instance": "/v1/namespaces"
}

{
  "type": "/errors/unauthorized-request",
  "title": "No valid authentication credentials for the operation",
  "status": 401,
  "detail": "",
  "instance": "/v1/namespaces"
}

{
  "type": "/errors/forbidden-request",
  "title": "Not authorized to make this request",
  "status": 403,
  "detail": "",
  "instance": "/v1/namespaces"
}

{
  "type": "/errors/not-found-error",
  "title": "Not found Error",
  "status": 404,
  "detail": "",
  "instance": "/v1/namespaces/{ns}"
}

{
  "type": "/errors/conflict",
  "title": "The namespace has been concurrently modified",
  "status": 409,
  "detail": "",
  "instance": "/v1/namespaces/{ns}"
}

{
  "type": "/errors/service-unavailable",
  "title": "Slow down",
  "status": 503,
  "detail": "",
  "instance": "/v1/namespaces"
}

{
  "type": "/errors/server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "",
  "instance": "/v1/namespaces"
}

Table

Atomically commit a batch of mixed table operations

Atomically commit a batch of table operations. This is a generalized version of BatchCreateTableVersions that supports mixed operation types within a single atomic transaction at the metadata layer.

Supported operation types:

DeclareTable: Declare (reserve) a new table
CreateTableVersion: Create a new version entry for a table
DeleteTableVersions: Delete version ranges from a table
DeregisterTable: Deregister (soft-delete) a table

All operations are committed atomically: either all succeed or none are applied.

POST

table

batch-commit

Atomically commit a batch of mixed table operations

curl --request POST \
  --url {scheme}://{host}:{port}/{basePath}/v1/table/batch-commit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operations": [
    {
      "declare_table": {
        "identity": {
          "api_key": "<string>",
          "auth_token": "<string>"
        },
        "context": {},
        "id": [
          "<string>"
        ],
        "location": "<string>",
        "vend_credentials": true,
        "properties": {}
      },
      "deregister_table": {
        "identity": {
          "api_key": "<string>",
          "auth_token": "<string>"
        },
        "context": {},
        "id": [
          "<string>"
        ]
      }
    }
  ],
  "identity": {
    "api_key": "<string>",
    "auth_token": "<string>"
  },
  "context": {}
}
'

import requests

url = "{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit"

payload = {
    "operations": [
        {
            "declare_table": {
                "identity": {
                    "api_key": "<string>",
                    "auth_token": "<string>"
                },
                "context": {},
                "id": ["<string>"],
                "location": "<string>",
                "vend_credentials": True,
                "properties": {}
            },
            "deregister_table": {
                "identity": {
                    "api_key": "<string>",
                    "auth_token": "<string>"
                },
                "context": {},
                "id": ["<string>"]
            }
        }
    ],
    "identity": {
        "api_key": "<string>",
        "auth_token": "<string>"
    },
    "context": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    operations: [
      {
        declare_table: {
          identity: {api_key: '<string>', auth_token: '<string>'},
          context: {},
          id: ['<string>'],
          location: '<string>',
          vend_credentials: true,
          properties: {}
        },
        deregister_table: {
          identity: {api_key: '<string>', auth_token: '<string>'},
          context: {},
          id: ['<string>']
        }
      }
    ],
    identity: {api_key: '<string>', auth_token: '<string>'},
    context: {}
  })
};

fetch('{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "62437",
  CURLOPT_URL => "{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'operations' => [
        [
                'declare_table' => [
                                'identity' => [
                                                                'api_key' => '<string>',
                                                                'auth_token' => '<string>'
                                ],
                                'context' => [
                                                                
                                ],
                                'id' => [
                                                                '<string>'
                                ],
                                'location' => '<string>',
                                'vend_credentials' => true,
                                'properties' => [
                                                                
                                ]
                ],
                'deregister_table' => [
                                'identity' => [
                                                                'api_key' => '<string>',
                                                                'auth_token' => '<string>'
                                ],
                                'context' => [
                                                                
                                ],
                                'id' => [
                                                                '<string>'
                                ]
                ]
        ]
    ],
    'identity' => [
        'api_key' => '<string>',
        'auth_token' => '<string>'
    ],
    'context' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit"

	payload := strings.NewReader("{\n  \"operations\": [\n    {\n      \"declare_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ],\n        \"location\": \"<string>\",\n        \"vend_credentials\": true,\n        \"properties\": {}\n      },\n      \"deregister_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ]\n      }\n    }\n  ],\n  \"identity\": {\n    \"api_key\": \"<string>\",\n    \"auth_token\": \"<string>\"\n  },\n  \"context\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"operations\": [\n    {\n      \"declare_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ],\n        \"location\": \"<string>\",\n        \"vend_credentials\": true,\n        \"properties\": {}\n      },\n      \"deregister_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ]\n      }\n    }\n  ],\n  \"identity\": {\n    \"api_key\": \"<string>\",\n    \"auth_token\": \"<string>\"\n  },\n  \"context\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("{scheme}://{host}:{port}/{basePath}/v1/table/batch-commit")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"operations\": [\n    {\n      \"declare_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ],\n        \"location\": \"<string>\",\n        \"vend_credentials\": true,\n        \"properties\": {}\n      },\n      \"deregister_table\": {\n        \"identity\": {\n          \"api_key\": \"<string>\",\n          \"auth_token\": \"<string>\"\n        },\n        \"context\": {},\n        \"id\": [\n          \"<string>\"\n        ]\n      }\n    }\n  ],\n  \"identity\": {\n    \"api_key\": \"<string>\",\n    \"auth_token\": \"<string>\"\n  },\n  \"context\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "declare_table": {
        "context": {},
        "transaction_id": "<string>",
        "location": "<string>",
        "storage_options": {},
        "properties": {
          "owner": "Ralph",
          "created_at": "1452120468"
        },
        "managed_versioning": true
      },
      "create_table_version": {
        "context": {},
        "transaction_id": "<string>",
        "version": {
          "version": 1,
          "manifest_path": "<string>",
          "manifest_size": 1,
          "e_tag": "<string>",
          "timestamp_millis": 123,
          "metadata": {}
        }
      },
      "delete_table_versions": {
        "context": {},
        "deleted_count": 1,
        "transaction_id": "<string>"
      },
      "deregister_table": {
        "context": {},
        "transaction_id": "<string>",
        "id": [
          "<string>"
        ],
        "location": "<string>",
        "properties": {
          "owner": "Ralph",
          "created_at": "1452120468"
        }
      }
    }
  ],
  "context": {},
  "transaction_id": "<string>"
}

{
  "type": "/errors/bad-request",
  "title": "Malformed request",
  "status": 400,
  "detail": "",
  "instance": "/v1/namespaces"
}

{
  "type": "/errors/unauthorized-request",
  "title": "No valid authentication credentials for the operation",
  "status": 401,
  "detail": "",
  "instance": "/v1/namespaces"
}

{
  "type": "/errors/forbidden-request",
  "title": "Not authorized to make this request",
  "status": 403,
  "detail": "",
  "instance": "/v1/namespaces"
}

{
  "type": "/errors/not-found-error",
  "title": "Not found Error",
  "status": 404,
  "detail": "",
  "instance": "/v1/namespaces/{ns}"
}

{
  "type": "/errors/conflict",
  "title": "The namespace has been concurrently modified",
  "status": 409,
  "detail": "",
  "instance": "/v1/namespaces/{ns}"
}

{
  "type": "/errors/service-unavailable",
  "title": "Slow down",
  "status": 503,
  "detail": "",
  "instance": "/v1/namespaces"
}

{
  "type": "/errors/server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "",
  "instance": "/v1/namespaces"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

FlowClient Credentials

Token URL: /oauth/token

Query Parameters

delimiter

string

An optional delimiter of the string identifier, following the Lance Namespace spec. When not specified, the $ delimiter must be used.

Body

application/json

Request to atomically commit a batch of table operations. This replaces BatchCreateTableVersionsRequest with a more general interface that supports mixed operations (DeclareTable, CreateTableVersion, DeleteTableVersions, DeregisterTable) within a single atomic transaction at the metadata layer.

All operations are committed atomically: either all succeed or none are applied.

operations

object[]

required

List of operations to commit atomically. Supported operation types: DeclareTable, CreateTableVersion, DeleteTableVersions, DeregisterTable.

Show child attributes

identity

object

Identity information of a request.

Show child attributes

context

object

Arbitrary context as key-value pairs. How to use the context is custom to the specific implementation.

On a request, it carries caller-provided context to the implementation. On a response, it carries implementation-provided context back to the caller.

REST NAMESPACE ONLY Context entries are mapped to and from HTTP headers using the header. prefix:

On a request, any entry whose key starts with header. is sent as an HTTP request header with the prefix stripped. For example, the entry {"header.Authorization": "Bearer abc"} is sent as the request header Authorization: Bearer abc.
On a response, every HTTP response header is returned as an entry whose key is the header name prefixed with header.. For example, the response header x-request-id: abc123 is returned as the entry {"header.x-request-id": "abc123"}.

Show child attributes

Response

Result of atomically committing a batch of mixed table operations

Response for a batch commit of table operations. Contains the results of each operation in the same order as the request.

results

object[]

required

Results for each operation, in the same order as the request operations. Each result contains the outcome of the corresponding operation.

Show child attributes

context

object

Arbitrary context as key-value pairs. How to use the context is custom to the specific implementation.

On a request, it carries caller-provided context to the implementation. On a response, it carries implementation-provided context back to the caller.

REST NAMESPACE ONLY Context entries are mapped to and from HTTP headers using the header. prefix:

On a request, any entry whose key starts with header. is sent as an HTTP request header with the prefix stripped. For example, the entry {"header.Authorization": "Bearer abc"} is sent as the request header Authorization: Bearer abc.
On a response, every HTTP response header is returned as an entry whose key is the header name prefixed with header.. For example, the response header x-request-id: abc123 is returned as the entry {"header.x-request-id": "abc123"}.

Show child attributes

transaction_id

string

Optional transaction identifier for the batch commit