Skip to main content
POST
/
v1
/
data
/
semantic-search
Semantic Search
curl --request POST \
  --url https://api.example.com/v1/data/semantic-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "ef_search": 1000,
  "filter": "text like '%hello%'",
  "index_name": "embedding",
  "projection": "text,metadata,distance",
  "query": "dnotitia에 대해 설명해줘",
  "top_k": 5
}
EOF
{
  "code": 200,
  "data": {
    "data": [
      [
        {
          "distance": 0.58199745,
          "metadata": "{\"source\": \"small/test-file-01.pdf\", \"page\": 638, \"file_name\": \"test-file-01.pdf\", \"processed_time\": 1747208826.8216445, \"source_type\": \"S3\"}",
          "text": "Filename: test file 01"
        },
        {
          "distance": 0.5931134,
          "metadata": "{\"source\": \"small/test-file-02.pdf\", \"page\": 642, \"file_name\": \"test-file-02.pdf\", \"processed_time\": 1747208826.8216455, \"source_type\": \"S3\"}",
          "text": "Filename: test file 02"
        },
        {
          "distance": 0.59964377,
          "metadata": "{\"source\": \"small/test-file-02.pdf\", \"page\": 640, \"file_name\": \"test-file-02.pdf\", \"processed_time\": 1747208826.821645, \"source_type\": \"S3\"}",
          "text": "Filename: test file 02"
        },
        {
          "distance": 0.60592294,
          "metadata": "{\"source\": \"small/test-file-01.pdf\", \"page\": 56, \"file_name\": \"test-file-01.pdf\", \"processed_time\": 1747208783.0184922, \"source_type\": \"S3\"}",
          "text": "Filename: test file 01"
        },
        {
          "distance": 0.61381185,
          "metadata": "{\"source\": \"small/test-file-01.pdf\", \"page\": 642, \"file_name\": \"test-file-01.pdf\", \"processed_time\": 1747208826.8216455, \"source_type\": \"S3\"}",
          "text": "Filename: test file 01"
        }
      ]
    ],
    "num_resultsets": 1,
    "schema": {
      "fields": [
        {
          "data_type": "LargeUtf8",
          "dict_id": 0,
          "dict_is_ordered": false,
          "metadata": {},
          "name": "text",
          "nullable": false
        },
        {
          "data_type": "LargeUtf8",
          "dict_id": 0,
          "dict_is_ordered": false,
          "metadata": {},
          "name": "metadata",
          "nullable": false
        },
        {
          "data_type": "Float32",
          "dict_id": 0,
          "dict_is_ordered": false,
          "metadata": {},
          "name": "distance",
          "nullable": true
        }
      ],
      "metadata": {}
    }
  },
  "exception": null,
  "success": true
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

Semantic search request. It includes top_k, query, ef_search, projection.

​
index_name
string
required

The name of the vector column to search.

Example:

"embedding"

​
query
string
required

Query to run on Semantic Search

​
top_k
integer<int32>
required

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

Example:

"5"

​
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: "text like '%hello%'" or "metadata like '%world%'"

Example:

"text like '%hello%'"

​
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:

"text,metadata,distance"

Response

Success to search semantic

​
code
integer<int32>
required

HTTP status code.

Required range: x >= 0
​
success
boolean
required

Whether the request was successful.

​
data
object
​
exception
object