Skip to main content
POST
/
v1
/
table
/
{name}
/
query
Search Data
curl --request POST \
  --url https://{db}.{region}.api.lancedb.com/v1/table/{name}/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "vector": [
    0.1,
    0.2,
    0.3
  ],
  "full_text_query": {
    "query": "sneakers",
    "columns": [
      "name",
      "description"
    ]
  },
  "vector_column": "vector",
  "prefilter": false,
  "k": 10,
  "offset": 1,
  "distance_type": "L2",
  "bypass_vector_index": false,
  "filter": "category = 'shoes' AND price < 100",
  "columns": [
    "<string>"
  ],
  "nprobes": 10,
  "refine_factor": null
}
EOF
"<string>"

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
name
string
required

name of the table

Body

application/json
​
vector
number[]

The query vector for similarity search. Must match the dimensionality of your vector column. Use this for semantic search, recommendation systems, or any similarity-based queries.

Example:
[0.1, 0.2, 0.3]
​
full_text_query
object

Configuration for full-text search using BM25 algorithm.

​
vector_column
string

The vector column to search in. Can be omitted if the table has only one vector column. Required when multiple vector columns exist in the table.

Example:

"vector"

​
prefilter
boolean
default:false

Whether to apply the filter before vector search. Use true for complex filters to improve performance, false for simple filters where post-filtering is more efficient.

​
k
integer
default:10

The number of search results to return. Higher values provide more candidates but may impact performance.

Required range: 1 <= x <= 1000
​
offset
integer

The number of results to skip for pagination. Useful for implementing paginated search interfaces.

Required range: x >= 0
​
distance_type
enum<string>
default:L2

Distance metric to use for vector similarity search. The choice of metric significantly impacts search accuracy and performance.

  • L2 (Euclidean): Default metric, measures straight-line distance between vectors. Best for general-purpose similarity search.
  • Cosine: Measures the cosine of the angle between vectors (0-1 range). Best for normalized embeddings and semantic similarity.
  • Dot: Raw dot product without normalization. Sensitive to vector magnitudes, useful for raw similarity scores.
  • Hamming: Counts differing bit positions in binary vectors. Only for binary vectors stored as packed uint8 arrays.

Important: Use the same distance metric that your embedding model was trained with. Most modern embedding models use cosine similarity.

Available options:
L2,
Cosine,
Dot
​
bypass_vector_index
boolean
default:false

Whether to bypass the vector index and perform exhaustive search. Use only for small datasets or debugging. Significantly slower but guarantees exact results.

​
filter
string

SQL filter expression to apply to the search results. Supports complex boolean logic, comparisons, and functions. Examples: category = 'shoes', price BETWEEN 50 AND 200, created_at > '2024-01-01'

Example:

"category = 'shoes' AND price < 100"

​
columns
string[]

The columns to return in the results. If not specified, returns all columns. Use this to optimize response size and improve performance.

​
nprobes
integer
default:10

Number of IVF partitions to search. Higher values improve recall but increase query time. Recommended range: 1-100 for most use cases, higher for very large datasets.

Required range: 1 <= x <= 1000
​
refine_factor
integer | null

Refinement factor for improved accuracy. When set, re-ranks refine_factor * k results using exact vectors. Use for applications requiring high precision at the cost of some speed.

Required range: x >= 1

Response

top k results if query is successfully executed

The response is of type file.