Skip to main content

Vector Search

posthttps://api-atlas.nomic.ai/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) application/json

kinteger*required
querystring | array<number>*required
fieldsarray<string>
task_typestring

Possible values: search_document, search_query, null

Default: "search_query"

projection_idstring ($uuid)*required
selectionobject
methodstring*required

Possible values: composition

polarityboolean

Default: true

conjunctorstring*required

Possible values: ANY, ALL

cherriesobject
polarityboolean

Default: true

methodstring*required

Possible values: cherrypick

addedarray<array<any>>

Default: []

removedarray<array<any>>

Default: []

fieldstring
filtersarray<object>
includeSimilarityboolean

Default: true

Responses​

200Returns the data included in your optional selection most semantically similar to your query. Each object contains the fields specified in the fields request parameter.
dataarray<object>*required
400Bad request
401Unauthorized

Examples​

curl
curl -X 'POST' \
  'https://api-atlas.nomic.ai/v1/query/topk' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "k": 1,
  "query": "string",
  "fields": [
    "string"
  ],
  "task_type": "search_document",
  "projection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "selection": {
    "method": "composition",
    "polarity": true,
    "conjunctor": "ANY",
    "cherries": {
      "polarity": true,
      "method": "cherrypick",
      "added": [],
      "removed": [],
      "field": "string"
    },
    "filters": [
      {
        "polarity": null,
        "method": "search",
        "query": "string",
        "field": "string",
        "ignoreCase": true,
        "regex": false,
        "wordBoundary": false
      },
      {
        "polarity": null,
        "method": "range",
        "field": "string",
        "range": [
          null
        ]
      },
      {
        "polarity": null,
        "method": "category",
        "field": "string",
        "values": null
      },
      {
        "method": "composition",
        "polarity": true,
        "conjunctor": "ANY",
        "cherries": {},
        "filters": [
          null,
          null,
          null,
          null
        ]
      }
    ]
  },
  "includeSimilarity": true
}'