Sign in

v52

latestOpenAPI 3.1.1Apache 2.0raw.githubusercontent.com2026-08-0354155395.9 KB
Table
Data

Insert records into a table

Insert new records into table id.

For tables that have been declared but not yet created on storage (is_only_declared=true), this operation will create the table with the provided data.

REST NAMESPACE ONLY REST namespace uses Arrow IPC stream as the request body. It passes in the InsertIntoTableRequest information in the following way:

  • id: pass through path parameter of the same name
  • mode: pass through query parameter of the same name
post/v1/table/{id}/insert

Path parameters

idstring required

string identifier of an object in a namespace, following the Lance Namespace spec. When the value is equal to the delimiter, it represents the root namespace. For example, v1/namespace/$/list performs a ListNamespace on the root namespace.

Query parameters

delimiterstring

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

branchstring

Optional branch to target. When not specified, the main branch is used. Used by branch-scoped operations that cannot carry a branch field in their request body (Arrow IPC stream and bodyless operations). Operations with a JSON request body carry branch as a body field instead.

modestring

How the insert should behave. Case insensitive, supports both PascalCase and snake_case. Valid values are:

  • Append (default): insert data to the existing table
  • Overwrite: remove all data in the table and then insert data to it

Response

Result of inserting records into a table

{"stackTrail":"components:schemas:InsertIntoTableResponse:properties:context","oasType":"schema","type":"unknown","description":"Arbitrary context as key-value pairs.\nHow to use the context is custom to the specific implementation.\n\nOn a request, it carries caller-provided context to the implementation.\nOn a response, it carries implementation-provided context back to the caller.\n\nREST NAMESPACE ONLY\nContext entries are mapped to and from HTTP headers using the `header.` prefix:\n- On a request, any entry whose key starts with `header.` is sent as an HTTP\n request header with the prefix stripped. For example, the entry\n `{\"header.Authorization\": \"Bearer abc\"}` is sent as the request header\n `Authorization: Bearer abc`.\n- On a response, every HTTP response header is returned as an entry whose key is the\n header name prefixed with `header.`. For example, the response header\n `x-request-id: abc123` is returned as the entry `{\"header.x-request-id\": \"abc123\"}`.\n"}
transaction_idstring

Optional transaction identifier

num_inserted_rowsinteger

Number of rows inserted

versioninteger

The commit version associated with the operation

Example response

{
  "transaction_id": "transaction_id",
  "num_inserted_rows": 0,
  "context": {
    "key": "context"
  },
  "version": 0
}