Skip to main content

Vector Search

POST 
/v1/query/topk

Get sorted results of the top k most semantically similar data points to your query.

The below example demonstrates how to call the endpoint using curl. It includes a vector search query for "footwear", a filter for data with "comfortable" in the title, and will return the fields title, average_rating, and price along with _similarity (which is returned by default).

The results will be 3 data points that contain the text "comfortable" and are most semantically related to "footwear". If fields is not provided, all user-uploaded fields will be returned.

See this guide for a more detailed walkthrough.

curl -X POST 'https://api-atlas.nomic.ai/v1/query/topk' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $NOMIC_API_KEY' \
-d '{
    "projection_id": "f1e499cd-b5c1-4d31-b38a-fff61e1f8b59",
    "k": 3,
    "fields": ["title", "average_rating", "price"],
    "query": "footwear",
    "selection": {
        "method": "composition",
        "conjunctor": "ALL",
        "filters": [
            {
                "method": "search",
                "query": "comfortable",
                "field": "title"
            }
        ]
    }
}'

Request​

Body

required
    kintegerrequired

    Possible values: >= 1

    queryobjectrequired

    oneOf

    string

    fieldsstring[]
    task_typestring

    Possible values: [search_document, search_query, null]

    Default value: search_query
    projection_iduuidrequired

    selection

    object
    methodstringrequired

    Possible values: [composition]

    polarityboolean
    Default value: true
    conjunctorstringrequired

    Possible values: [ANY, ALL]

    cherries

    object
    polarityboolean
    Default value: true
    methodstringrequired

    Possible values: [cherrypick]

    addedarray[]

    Possible values: >= 2, <= 2

    Default value: []
    removedarray[]

    Possible values: >= 2, <= 2

    Default value: []
    fieldstringnullable

    filters

    object[]

  • Array [

    • oneOf

    polarityboolean
    Default value: true
    methodstringrequired

    Possible values: [search]

    querystringrequired
    fieldstringrequired
    ignoreCaseboolean
    Default value: true
    regexboolean
    Default value: false
    wordBoundaryboolean
    Default value: false

  • ]

    • includeSimilarityboolean
    Default value: true

Responses​

Returns the data included in your optional selection most semantically similar to your query. Each object contains the fields specified in the fields request parameter.

Schema
    dataobject[]required