API Reference
- SDKs
- Overview
- GETList all tables
- POSTRegister a table to a namespace
- POSTDescribe information of a table
- POSTCheck if a table exists
- POSTDrop a table
- POSTDeregister a table
- POSTRestore table to a specific version
- POSTRename a table
- POSTUpdate table schema metadata
- POSTList all versions of a table
- POSTCreate a new table version
- POSTDescribe a specific table version
- POSTDelete table version records
- POSTAtomically create versions for multiple tables
- POSTAtomically commit a batch of mixed table operations
- POSTModify existing columns
- POSTRemove columns from table
- POSTGet table statistics
- POSTInsert records into a table
- POSTMerge insert (upsert) records into a table
- POSTUpdate rows in a table
- POSTDelete rows from a table
- POSTQuery a table
- POSTCount rows in a table
- POSTCreate a table with the given name
- POSTGet query execution plan explanation
- POSTAnalyze query execution plan
- POSTAdd new columns to table schema
- POSTCreate an index on a table
- POSTCreate a scalar index on a table
- POSTList indexes on a table
- POSTGet table index statistics
- POSTDrop a specific index
- POSTList all tags for a table
- POSTGet version for a specific tag
- POSTDeclare a table
- POSTCreate a new tag
- POSTDelete a tag
- POSTUpdate a tag to point to a different version
A valid request URL is required to generate request examples{
"table": "<string>",
"namespace": [
"<string>"
],
"version": 1,
"location": "<string>",
"table_uri": "<string>",
"schema": {
"fields": [
{
"name": "<string>",
"nullable": true,
"type": {
"type": "<string>",
"fields": "<array>",
"length": 1
},
"metadata": {}
}
],
"metadata": {}
},
"storage_options": {},
"stats": {
"num_deleted_rows": 1,
"num_fragments": 1
},
"metadata": {},
"properties": {
"owner": "Ralph",
"created_at": "1452120468"
},
"managed_versioning": true,
"is_only_declared": true
}Describe information of a table
Describe the detailed information for table id.
REST NAMESPACE ONLY
REST namespace passes with_table_uri, load_detailed_metadata, and check_declared as query parameters instead of in the request body.
A valid request URL is required to generate request examples{
"table": "<string>",
"namespace": [
"<string>"
],
"version": 1,
"location": "<string>",
"table_uri": "<string>",
"schema": {
"fields": [
{
"name": "<string>",
"nullable": true,
"type": {
"type": "<string>",
"fields": "<array>",
"length": 1
},
"metadata": {}
}
],
"metadata": {}
},
"storage_options": {},
"stats": {
"num_deleted_rows": 1,
"num_fragments": 1
},
"metadata": {},
"properties": {
"owner": "Ralph",
"created_at": "1452120468"
},
"managed_versioning": true,
"is_only_declared": true
}Documentation Index
Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
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
An optional delimiter of the string identifier, following the Lance Namespace spec.
When not specified, the $ delimiter must be used.
Whether to include the table URI in the response
Whether to load detailed metadata that requires opening the dataset.
When false (default), only location is required in the response.
When true, the response includes additional metadata such as version, schema, and stats.
Whether to check if the table exists only as a namespace declaration
without storage data. When false (default), the response should return
null for is_only_declared unless another option such as
load_detailed_metadata requires the check.
Body
Identity information of a request.
Show child attributes
Show child attributes
Arbitrary context for a request as key-value pairs. How to use the context is custom to the specific implementation.
REST NAMESPACE ONLY
Context entries are passed via HTTP headers using the naming convention
x-lance-ctx-<key>: <value>. For example, a context entry
{"trace_id": "abc123"} would be sent as the header x-lance-ctx-trace_id: abc123.
Show child attributes
Show child attributes
Version of the table to describe. If not specified, server should resolve it to the latest version.
x >= 0Whether to include the table URI in the response. Default is false.
Whether to load detailed metadata that requires opening the dataset.
When true, the response must include all detailed metadata such as version, schema, and stats
which require reading the dataset.
When not set, the implementation can decide whether to return detailed metadata
and which parts of detailed metadata to return.
Whether to check if the table exists only as a namespace declaration
without storage data. Default is false.
When true, the response should populate is_only_declared.
When false, the implementation should return null for is_only_declared
unless another option such as load_detailed_metadata requires
checking declared-only table state.
Whether to include vended credentials in the response storage_options.
When true, the implementation should provide vended credentials for accessing storage.
When not set, the implementation can decide whether to return vended credentials.
Response
Table properties result when loading a table
Table name.
Only populated when load_detailed_metadata is true.
The namespace identifier as a list of parts.
Only populated when load_detailed_metadata is true.
Table version number.
Only populated when load_detailed_metadata is true.
x >= 0Table storage location (e.g., S3/GCS path).
Table URI. Unlike location, this field must be a complete and valid URI.
Only returned when with_table_uri is true.
Table schema in JSON Arrow format.
Only populated when load_detailed_metadata is true.
Show child attributes
Show child attributes
Configuration options to be used to access storage. The available
options depend on the type of storage in use. These will be
passed directly to Lance to initialize storage access.
When vend_credentials is true, this field may include vended credentials.
If the vended credentials are temporary, the expires_at_millis key should be
included to indicate the millisecond timestamp when the credentials expire.
Show child attributes
Show child attributes
Table statistics.
Only populated when load_detailed_metadata is true.
Show child attributes
Show child attributes
Optional table metadata as key-value pairs. This records the information of the table
and requires loading the table.
It is only populated when load_detailed_metadata is true.
Show child attributes
Show child attributes
Properties stored on the table, if supported by the server. This records the information managed by the namespace. If the server does not support table properties, it should return null for this field. If table properties are supported, but none are set, it should return an empty object.
Show child attributes
Show child attributes
{
"owner": "Ralph",
"created_at": "1452120468"
}
When true, the caller should use namespace table version operations (CreateTableVersion, BatchCreateTableVersions, DescribeTableVersion, ListTableVersions, BatchDeleteTableVersions) to manage table versions instead of relying on Lance's native version management.
When true, indicates that the table has been declared in the namespace
but not yet created on storage. This means the table exists in the
namespace but has no data files on the underlying storage.
When false, the table has storage components (data and metadata files).
When null, the implementation did not check whether the table is only
declared. Clients should treat an omitted value as null. Implementations
should populate this field when check_declared is true or another
option such as load_detailed_metadata requires checking declared-only
table state. Operations like describe_table with load_detailed_metadata=true
may fail for declared-only tables.
Was this page helpful?