Skip to main content
POST
/
v1
/
table
/
{id}
/
merge_insert
Error
A valid request URL is required to generate request examples
{
  "context": {},
  "transaction_id": "<string>",
  "num_updated_rows": 1,
  "num_inserted_rows": 1,
  "num_deleted_rows": 1,
  "version": 1
}
{
  "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/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.

Path Parameters

id
string
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

delimiter
string

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

branch
string

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.

on
string
required

Lance field path to use for matching rows. Nested fields use dot-separated segments; use backtick-quoted segments for literal dots and double backticks inside quoted segments. Use canonical full paths for display and errors; leaf names alone only identify top-level fields; invalid or unresolved paths should return InvalidInput or TableColumnNotFound.

Minimum string length: 1
when_matched_update_all
boolean
default:false

Update all columns when rows match

when_matched_update_all_filt
string

The row is updated (similar to UpdateAll) only for rows where the SQL expression evaluates to true. Field references must use Lance field path syntax: nested fields use dot-separated segments, literal dots require backtick-quoted segments, and backticks inside quoted segments are doubled.

when_not_matched_insert_all
boolean
default:false

Insert all columns when rows don't match

when_not_matched_by_source_delete
boolean
default:false

Delete all rows from target table that don't match a row in the source table

when_not_matched_by_source_delete_filt
string

Delete rows from the target table if there is no match AND the SQL expression evaluates to true. Field references must use Lance field path syntax: nested fields use dot-separated segments, literal dots require backtick-quoted segments, and backticks inside quoted segments are doubled.

timeout
string

Timeout for the operation (e.g., "30s", "5m")

use_index
boolean
default:false

Whether to use index for matching rows

Body

application/vnd.apache.arrow.stream

Arrow IPC stream containing the records to merge

The body is of type file.

Response

Result of merge insert operation

Response from merge insert operation

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"}.
transaction_id
string

Optional transaction identifier

num_updated_rows
integer<int64>

Number of rows updated

Required range: x >= 0
num_inserted_rows
integer<int64>

Number of rows inserted

Required range: x >= 0
num_deleted_rows
integer<int64>

Number of rows deleted (typically 0 for merge insert)

Required range: x >= 0
version
integer<int64>

The commit version associated with the operation

Required range: x >= 0