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

application/json

Body

required

k integerrequired

Possible values: >= 1

query

object

required

oneOf

MOD1

string

MOD2

Array [

number

]

fields string[]
task_type string

Possible values: [search_document, search_query, null]

Default value: search_query

projection_id uuidrequired

selection

object

method stringrequired

Possible values: [composition]

polarity boolean

Default value: true

conjunctor stringrequired

Possible values: [ANY, ALL]

cherries

object

polarity boolean

Default value: true

method stringrequired

Possible values: [cherrypick]

added array[]

Possible values: >= 2, <= 2

Default value: ``

removed array[]

Possible values: >= 2, <= 2

Default value: ``

field stringnullable

filters

object[]

Array [

oneOf

SearchSelection

polarity boolean

Default value: true

method stringrequired

Possible values: [search]

query stringrequired

field stringrequired

ignoreCase boolean

Default value: true

regex boolean

wordBoundary boolean

SemanticSearchSelection

polarity boolean

Default value: true

method stringrequired

Possible values: [semanticSearch]

value stringrequired

statistic string

Possible values: [dot, l2]

Default value: dot

embedding

object

required

oneOf

MOD1

Array [

number

]

MOD2

string

range number[]required

Possible values: >= 2, <= 2

taskType stringnullable

Possible values: [search_document, search_query]

]

includeSimilarity boolean

Default value: true

Responses

200

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.

application/json

Schema

Schema

data object[]required

Example (from schema)

{
  "data": [
    {
      "title": "Guide Gear Lace Up Walking Shoes for Men, Comfortable Shoes for Work, Casual Working",
      "average_rating": 3.5999999046325684,
      "price": 39.9900016784668,
      "_similarity": 0.7691732048988342
    },
    {
      "title": "Womens High Heel Wedges with Comfortable Plantar Orthopedic Sandals, Suitable for Outdoor",
      "average_rating": 2.0999999046325684,
      "price": null,
      "_similarity": 0.7547734975814819
    },
    {
      "title": "Men's Military Tactical Boots Lightweight Work Boots Combat Boots Comfortable Hiking Boots Breathable Jungle Boots",
      "average_rating": 3.799999952316284,
      "price": null,
      "_similarity": 0.7544335722923279
    }
  ]
}

400

Bad request

401

Unauthorized

Loading...