LanceDB Cloud API 1.0.0

LanceDB Cloud API is a RESTful API that allows users to access and modify data stored in LanceDB Cloud. Table actions are considered temporary resource creations and all use POST method.

Contact: LanceDB support contact@lancedb.com

Servers

Description	URL
LanceDB Cloud REST endpoint.	https://{db}.{region}.api.lancedb.com

Tables

GET /v1/table/

List Tables

Description

List tables, optionally, with pagination.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`limit`	query	integer	10	No	Limits the number of items to return.
`page_token`	query	string		No	Specifies the starting position of the next query

Response 200 OK

application/json

{
    "tables": [
        "string"
    ],
    "page_token": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "tables": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "page_token": {
            "type": "string"
        }
    }
}

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

POST /v1/table/{name}/create/

Create a new table

Description

Create a new table.

Will return 400 if table with requested name already exists.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/vnd.apache.arrow.stream

"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "string",
    "format": "binary"
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

POST /v1/table/{name}/count_rows/

Count rows in a table

Description

Count the number of rows in a table.

Can optionally pass a predicate to count the rows that match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "predicate": "category = 'shoes'"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "predicate": {
            "type": "string",
            "example": "category = 'shoes'",
            "description": "A SQL filter expression that specifies the rows to count.\n"
        }
    }
}

Response 200 OK

application/json

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "integer",
    "example": 1000
}

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/rename

Rename a table.

Description

Rename a table

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "new_table_name": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "required": [
        "new_table_name"
    ],
    "properties": {
        "new_table_name": {
            "type": "string",
            "description": "The new name of the table."
        }
    }
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/drop/

Drop a table

Description

Drop a table

If the table does not exist, it will return 200.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Response 200 OK

Response 401 Unauthorized

Refer to the common response description: unauthorized.

POST /v1/table/{name}/describe/

Describe a table

Description

Describe a table and return Table Information.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Response 200 OK

application/json

⚠️ This example has been generated automatically from href="#__codelineno-10-1">{ "table": "string", "version": 0, "schema": { "fields": [ { "name": "id", "type": { "name": "int64" } }, { "name": "name", "type": { "type": "string" } }, { "name": "vector", "type": { "type": "float32", "length": 128 } } ], "metadata": { "key": "value" } }, "stats": { "num_deleted_rows": 0, "num_fragments": 0 } } the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "table": {
            "description": "Name of the table",
            "type": "string"
        },
        "version": {
            "description": "The latest version of the table",
            "type": "integer"
        },
        "schema": {
            "$ref": "#/components/schemas/json_schema"
        },
        "stats": {
            "type": "object",
            "properties": {
                "num_deleted_rows": {
                    "type": "integer"
                },
                "num_fragments": {
                    "type": "integer"
                }
            }
        }
    }
}

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

Data

POST /v1/table/{name}/query/

Vector Query

Description

Search for rows, using any combination of vector search, full text search, and SQL filter expressions.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "vector": [
        0.1,
        0.2,
        0.3
    ],
    "full_text_query": {
        "columns": [
            "name",
            "description"
        ],
        "query": "sneakers"
    },
    "vector_column": "vector",
    "prefilter": true,
    "k": 0,
    "offset": 0,
    "distance_type": "L2",
    "bypass_vector_index": true,
    "filter": "category = 'shoes'",
    "columns": [
        "string"
    ],
    "nprobes": 0,
    "refine_factor": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "vector": {
            "type": "array",
            "items": {
                "type": "number"
            },
            "example": [
                0.1,
                0.2,
                0.3
            ],
            "description": "The targeted vector to search for.\n"
        },
        "full_text_query": {
            "description": "The full text query to search for.\n",
            "type": "object",
            "required": [
                "query"
            ],
            "properties": {
                "columns": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "name",
                        "description"
                    ],
                    "description": "The columns to search within.\n"
                },
                "query": {
                    "type": "string",
                    "example": "sneakers",
                    "description": "The full text query to search for.\n"
                }
            }
        },
        "vector_column": {
            "type": "string",
            "example": "vector",
            "description": "The column to query, it can be inferred from the schema if there is only one vector column.\n"
        },
        "prefilter": {
            "type": "boolean",
            "default": false,
            "description": "Whether to apply the filter before search.\n"
        },
        "k": {
            "type": "integer",
            "default": 10,
            "description": "The number of search results to return.\n"
        },
        "offset": {
            "type": "integer",
            "description": "The number of search results to skip.\n"
        },
        "distance_type": {
            "$ref": "#/components/schemas/distance_type",
            "default": "L2"
        },
        "bypass_vector_index": {
            "type": "boolean",
            "default": false,
            "description": "Whether to bypass vector index.\n"
        },
        "filter": {
            "type": "string",
            "example": "category = 'shoes'",
            "description": "A SQL filter expression that specifies the rows to query.\n"
        },
        "columns": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "The columns to return. Defaults to all columns in the table.\n"
        },
        "nprobes": {
            "type": "integer",
            "default": 10,
            "description": "The number of partitions to search. Higher values yield\nbetter search results but are slower.\n"
        },
        "refine_factor": {
            "type": "integer",
            "nullable": true,
            "default": null,
            "description": "The refine step re-ranks refine_factor * k results based on\nexact vectors. Null (the default) skips this step for faster\nqueries.\n"
        }
    }
}

Response 200 OK

application/vnd.apache.arrow.file

"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string",
    "format": "binary"
}

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/insert/

Insert data to a table

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`mode`	query	string	append	No	The mode of insertion. If `overwrite`, the existing data will be replaced. If `append`, the new data will be appended to the existing data.
`name`	path	string		No	name of the table

Request body

application/vnd.apache.arrow.stream

"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "string",
    "format": "binary"
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/update/

Apply a SQL update to a table.

Description

Update rows in a table, using SQL expressions and an optional predicate.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "updates": [
        [
            "price",
            "price + 0.10"
        ]
    ],
    "predicate": "id in (1, 2, 3)"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "required": [
        "updates"
    ],
    "properties": {
        "updates": {
            "type": "array",
            "description": "A list to column updates. Each item is a pair of strings. The\nfirst string is the column name to update, and the second\nstring is a SQL expression to update the column.\n",
            "items": {
                "type": "array",
                "minItems": 2,
                "maxItems": 2,
                "items": {
                    "type": "string"
                },
                "example": [
                    "price",
                    "price + 0.10"
                ]
            }
        },
        "predicate": {
            "type": "string",
            "example": "id in (1, 2, 3)",
            "description": "A filter expression that specifies the rows to update.\n"
        }
    }
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/delete/

Delete rows from a table

Description

Delete rows from a table using a SQL predicate.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "predicate": "id in (1, 2, 3)"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "predicate": {
            "type": "string",
            "example": "id in (1, 2, 3)",
            "description": "A filter expression that specifies the rows to delete.\n"
        }
    }
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/merge_insert/

Merge-insert data to a table

Description

Perform a merge-insert SQL query against a table. This can be used to perform upserts. To perform an upsert, set when_matched_update_all and when_not_matched_insert_all to true.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`True`	query	string		No	The column to match on.
`name`	path	string		No	name of the table
`when_matched_update_all`	query	boolean		No	If true, update all columns when a match is found with the new values.
`when_matched_update_all_filt`	query	string		Yes	An additional filter to apply when updating all columns.
`when_not_matched_by_source_delete`	query	boolean		No	If true, delete rows in the target table when there is no match in the source table.
`when_not_matched_by_source_delete_filt`	query	string		Yes	An additional filter to apply when deleting rows in the target table.
`when_not_matched_insert_all`	query	boolean		No	If true, insert all columns when no match is found.

Request body

application/vnd.apache.arrow.stream

"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "string",
    "format": "binary"
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/add_columns/

Add columns to a table

Description

Add new columns to a table. You must pass a SQL expression to generate the new columns. This expression can reference existing columns.

For example, you can add a new column new_column that is old_column + 1:

{
  "new_columns": [
    {
      "name": "new_column",
      "expression": "old_column + 1"
    }
  ]
}

If you want to fill with null, you can use a NULL expression with a cast to the correct type:

{
  "new_columns": [
    {
      "name": "new_column",
      "expression": "CAST(NULL AS int64)"
    }
  ]
}

Some example data types: - int64 - float32 - string

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "new_columns": [
        {
            "name": "new_column",
            "expression": "old_column + 1"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "new_columns": {
            "type": "array",
            "items": {
                "type": "object",
                "required": [
                    "name",
                    "expression"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "The name of the new column.",
                        "example": "new_column"
                    },
                    "expression": {
                        "type": "string",
                        "description": "The SQL expression to generate the column.\n",
                        "example": "old_column + 1"
                    }
                }
            }
        }
    }
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/alter_columns/

Alter name, type, or nullability of a column

Description

Alter the name, type, or nullability of a column.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "alterations": [
        {
            "path": "outer.inner",
            "rename": "new_name",
            "data_type": {
                "type": "int64",
                "fields": [
                    {
                        "name": "string",
                        "type": null,
                        "nullable": true
                    }
                ],
                "length": 0
            },
            "nullable": true
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "alterations": {
            "type": "array",
            "items": {
                "type": "object",
                "required": [
                    "path"
                ],
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "The path to the column to alter. To reference a nested\ncolumn, separate pieces by dots.\n",
                        "example": "outer.inner"
                    },
                    "rename": {
                        "type": "string",
                        "description": "The new name of the column. If not provided, the name\nwill not be changed.\n",
                        "example": "new_name"
                    },
                    "data_type": {
                        "$ref": "#/components/schemas/json_schema_type"
                    },
                    "nullable": {
                        "type": "boolean",
                        "description": "Whether the column can contain null values. If not provided,\nthe nullability will not be changed.\n"
                    }
                }
            }
        }
    }
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/drop_columns/

Drop columns from a table

Description

Drop columns from a table.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "columns": [
        "string"
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "columns": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "The columns to drop.\n"
        }
    }
}

Response 200 OK

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

Index

POST /v1/table/{name}/create_index/

Create Vector Index

Description

Create an index on a column.

Vector index options are: IVF_PQ and IVF_HNSW_SQ. The distance_type parameter is required for vector indices.

For full text search, use FTS. For scalar indices, use BTREE, BITMAP, or LABEL_LIST.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Request body

application/json

{
    "index_type": "IVF_PQ",
    "column": "vector",
    "distance_type": "L2",
    "with_position": true,
    "base_tokenizer": "string",
    "language": "string",
    "max_token_length": 0,
    "lower_case": true,
    "stem": true,
    "remove_stop_words": true,
    "ascii_folding": true
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "required": [
        "index_type"
    ],
    "properties": {
        "index_type": {
            "$ref": "#/components/schemas/index_type"
        },
        "column": {
            "type": "string",
            "example": "vector",
            "description": "The targeted vector column to index. Required only if there are multiple vector columns.\n"
        },
        "distance_type": {
            "$ref": "#/components/schemas/distance_type"
        },
        "with_position": {
            "type": "boolean",
            "default": true,
            "description": "Whether to store the position of tokens in docs, required for phrase search.\n"
        },
        "base_tokenizer": {
            "type": "string",
            "default": "simple",
            "description": "The base tokenizer to use for full text search.\n"
        },
        "language": {
            "type": "string",
            "default": "English",
            "description": "The language to use for stemming and stop words.\n"
        },
        "max_token_length": {
            "type": "integer",
            "default": 40,
            "description": "The maximum token length to index, longer tokens are ignored.\n"
        },
        "lower_case": {
            "type": "boolean",
            "default": false,
            "description": "Whether to convert tokens to lowercase.\n"
        },
        "stem": {
            "type": "boolean",
            "default": false,
            "description": "Whether to apply stemming to tokens.\n"
        },
        "remove_stop_words": {
            "type": "boolean",
            "default": false,
            "description": "Whether to remove stop words from tokens.\n"
        },
        "ascii_folding": {
            "type": "boolean",
            "default": false,
            "description": "Whether to convert non-ASCII characters to ASCII, used for accent folding.\n"
        }
    }
}

Response 200 OK

application/json

Schema of the response body

{
    "type": "object"
}

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/index/list/

List indices of a table

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`name`	path	string		No	name of the table

Response 200 OK

application/json

{
    "indexes": [
        {
            "index_name": "vector_idx",
            "index_uuid": "7a77457b-3975-4422-8955-1a7392449e50",
            "columns": [
                "vector"
            ],
            "index_status": "pending"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "indexes": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "index_name": {
                        "type": "string",
                        "example": "vector_idx"
                    },
                    "index_uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "columns": {
                        "type": "array",
                        "example": [
                            "vector"
                        ],
                        "items": {
                            "type": "string"
                        }
                    },
                    "index_status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "indexing",
                            "done",
                            "failed"
                        ]
                    }
                }
            }
        }
    }
}

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

POST /v1/table/{name}/index/{index_name}/stats/

List the details of an index

Input parameters

Parameter	In	Type	Default	Nullable	Description
`key_auth`	header	string	N/A	No	API key
`index_name`	path	string		No	name of the index
`name`	path	string		No	name of the table

Response 200 OK

application/json

{
    "num_indexed_rows": 100000,
    "num_unindexed_rows": 0,
    "index_type": "IVF_PQ",
    "distance_type": "L2"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "num_indexed_rows": {
            "type": "integer",
            "example": 100000
        },
        "num_unindexed_rows": {
            "type": "integer"
        },
        "index_type": {
            "$ref": "#/components/schemas/index_type"
        },
        "distance_type": {
            "$ref": "#/components/schemas/distance_type"
        }
    }
}

Response 400 Bad Request

Refer to the common response description: invalid_request.

Response 401 Unauthorized

Refer to the common response description: unauthorized.

Response 404 Not Found

Refer to the common response description: not_found.

Schemas

distance_type

Type: string

index_type

Type: string

json_schema

Name	Type
`fields`	json_schema_fields
`metadata`	Properties: `key, value`

json_schema_fields

Name	Type
`name`	string
`nullable`	boolean
`type`	json_schema_type

json_schema_type

Name	Type
`fields`	Array<json_schema_fields>
`length`	integer
`type`	string

Common responses

This section describes common responses that are reused across operations.

invalid_request

Invalid request

text/plain

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string"
}

not_found

Not found

text/plain

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string"
}

unauthorized

Unauthorized

text/plain

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string"
}

Common parameters

This section describes common parameters that are reused across operations.

table_name

Name	In	Type	Default	Nullable	Description
`name`	path	string		No

index_name

Name	In	Type	Default	Nullable	Description
`index_name`	path	string		No

Security schemes

Name	Type	Scheme	Description
key_auth	apiKey