Skip to main content
POST
/
v1
/
data
/
indexes
/
{index_name}
/
vector-search
curl --request POST \
  --url https://api.example.com/v1/data/indexes/{index_name}/vector-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ef_search": 100,
  "filter": "video_id > 100",
  "projection": "video_title, channel_name, video_id, timestamp",
  "query_vectors": {
    "dense": [
      [
        0.1,
        0.2,
        0.3,
        0.4
      ],
      [
        0.5,
        0.6,
        0.7,
        0.8
      ]
    ]
  },
  "top_k": 3
}
'
{
  "code": 200,
  "data": {
    "data": [
      [
        {
          "distance": 0.10213412,
          "id": "1",
          "metadata": "{\"file_name\": \"abc.pdf\"}",
          "text": "hello"
        },
        {
          "distance": 0.20213412,
          "id": "2",
          "metadata": "{\"file_name\": \"def.pdf\"}",
          "text": "world"
        },
        {
          "distance": 0.30213412,
          "id": "3",
          "metadata": "{\"file_name\": \"ghi.pdf\"}",
          "text": "rust"
        }
      ],
      [
        {
          "distance": 0.15223412,
          "id": "4",
          "metadata": "{\"file_name\": \"jkl.pdf\"}",
          "text": "python"
        },
        {
          "distance": 0.25223412,
          "id": "5",
          "metadata": "{\"file_name\": \"mno.pdf\"}",
          "text": "java"
        },
        {
          "distance": 0.35223412,
          "id": "6",
          "metadata": "{\"file_name\": \"pqr.pdf\"}",
          "text": "go"
        }
      ]
    ],
    "num_resultsets": 2,
    "schema": {
      "fields": [
        {
          "data_type": "LargeUtf8",
          "dict_id": 0,
          "dict_is_ordered": false,
          "metadata": {},
          "name": "id",
          "nullable": false
        },
        {
          "data_type": "LargeUtf8",
          "dict_id": 0,
          "dict_is_ordered": false,
          "metadata": {},
          "name": "metadata",
          "nullable": false
        },
        {
          "data_type": "LargeUtf8",
          "dict_id": 0,
          "dict_is_ordered": false,
          "metadata": {},
          "name": "text",
          "nullable": false
        },
        {
          "data_type": "Float32",
          "dict_id": 0,
          "dict_is_ordered": false,
          "metadata": {},
          "name": "distance",
          "nullable": false
        }
      ],
      "metadata": {}
    }
  },
  "exception": null,
  "success": true
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Include the token in the Authorization header as 'Bearer '

Path Parameters

​
index_name
string
required

The name of the vector column to search

Body

application/json

Vector search request. It includes top_k, query_vectors, ef_search, projection, and filter. Supports dense vectors.

​
query_vectors
object
required

Query vectors to search. Can be either dense (Vec<Vec>) or sparse (Vec).

​
top_k
integer<int32>
required

Number of top results to return from the vector search. Must be greater than 0.

Example:

"3"

​
ef_search
integer<int32> | null
default:Same value as top_k

Size of the dynamic candidate list during search. A larger value will result in more accurate but slower searches.

Required range: x >= 0
Example:

"1000"

​
filter
string | null
default:""

SQL WHERE clause to filter the results. If not specified, no filtering will be applied. The filter condition must be a valid SQL expression that evaluates to a boolean value. For example: "video_id < 3000" or "category = 'music' AND views > 1000"

Example:

"video_id < 3000"

​
projection
string | null
default:*

Columns to include in the result set. Uses SQL projection syntax (e.g. "col1, col2"). If not specified, all columns will be returned.

Example:

"video_title , channel_name, video_id, timestamp, distance"

​
sparse_metadata
object

Optional metadata for sparse vector search (ignored for dense) Example: {"N": 50001, "avgdl": 200.51, "df": ["205:30001 101:15000", "205:25000 101:12000"]}

​
sparse_parameters
object

Parameters for sparse model (BM25): k (term frequency weight), b (length penalty)

Response

Success to search vector

​
code
integer<int32>
required

HTTP status code.

Required range: x >= 0
​
success
boolean
required

Whether the request was successful.

​
data
object
​
exception
object