For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
CloudGitHub
  • API Reference
      • POSTSearch points
      • POSTSearch batch points
      • POSTSearch point groups
      • POSTRecommend points
      • POSTRecommend batch points
      • POSTRecommend point groups
      • POSTDiscover points
      • POSTDiscover batch points
      • POSTQuery points
      • POSTQuery points in batch
      • POSTQuery point groups
      • POSTDistance matrix pairs
      • POSTDistance matrix offsets
LogoLogo
CloudGitHub
API ReferenceSearch

Query points

POST
/collections/:collection_name/points/query
POST
/collections/:collection_name/points/query
$# Query nearest by ID
$curl -X POST \
>  'http://localhost:6333/collections/collection_name/points/query' \
>  --header 'api-key: <api-key-value>' \
>  --header 'Content-Type: application/json' \
>  --data-raw '{
>  "query": "43cf51e2-8777-4f52-bc74-c2cbde0c8b04"
>}'
$
$# Recommend on the average of these vectors
$curl -X POST \
>  'http://localhost:6333/collections/collection_name/points/query' \
>  --header 'api-key: <api-key-value>' \
>  --header 'Content-Type: application/json' \
>  --data-raw '{
>  "query": {
>    "recommend": {
>      "positive": [
>        [
>          0.11,
>          0.35,
>          0.6
>        ]
>      ],
>      "negative": [
>        "43cf51e2-8777-4f52-bc74-c2cbde0c8b04",
>        [
>          0.01,
>          0.45,
>          0.67
>        ]
>      ]
>    }
>  }
>}'
$
$# Fusion query
$curl -X POST \
>  'http://localhost:6333/collections/collection_name/points/query' \
>  --header 'api-key: <api-key-value>' \
>  --header 'Content-Type: application/json' \
>  --data-raw '{
>  "prefetch": [
>    {
>      "query": {
>        "values": [
>          0.22,
>          0.8
>        ],
>        "indices": [
>          1,
>          42
>        ]
>      },
>      "using": "sparse",
>      "limit": 20
>    },
>    {
>      "query": [
>        0.01,
>        0.45,
>        0.67
>      ],
>      "using": "dense",
>      "limit": 20
>    }
>  ],
>  "query": {
>    "fusion": "rrf"
>  }
>}'
$
$# 2-stage query
$curl -X POST \
>  'http://localhost:6333/collections/collection_name/points/query' \
>  --header 'api-key: <api-key-value>' \
>  --header 'Content-Type: application/json' \
>  --data-raw '{
>  "prefetch": {
>    "query": [
>      1,
>      23,
>      45,
>      67
>    ],
>    "limit": 100
>  },
>  "query": [
>    [
>      0.1,
>      0.2,
>      0.3
>    ],
>    [
>      0.2,
>      0.1,
>      0.35
>    ],
>    [
>      0.8,
>      0.9,
>      0.53
>    ]
>  ],
>  "using": "colbert",
>  "limit": 10
>}'
$
$# Random sampling (as of 1.11.0)
$curl -X POST \
>  'http://localhost:6333/collections/collection_name/points/query' \
>  --header 'api-key: <api-key-value>' \
>  --header 'Content-Type: application/json' \
>  --data-raw '{
>  "query": {
>    "sample": "random"
>  }
>}'
$
$# Score boost depending on payload conditions (as of 1.14.0)
$curl -X POST \
>  'http://localhost:6333/collections/collection_name/points/query' \
>  --header 'api-key: <api-key-value>' \
>  --header 'Content-Type: application/json' \
>  --data-raw '{
>    "prefetch": {
>        "query": [0.2, 0.8, ...],  // <-- dense vector
>        "limit": 50
>    }
>    "query": {
>        "formula": {
>            "sum": [
>                "$score,
>                { "mult": [ 0.5, { "key": "tag", "match": { "any": ["h1", "h2", "h3", "h4"] } } ] },
>                { "mult": [ 0.25, { "key": "tag", "match": { "any": ["p", "li"] } } ] }
>            ]
>        }
>    }
>}'
$
$# Score boost geographically closer points (as of 1.14.0)
$curl -X POST \
>  'http://localhost:6333/collections/collection_name/points/query' \
>  --header 'api-key: <api-key-value>' \
>  --header 'Content-Type: application/json' \
>  --data-raw '{
>    "prefetch": { "query": [0.2, 0.8, ...], "limit": 50 },
>    "query": {
>        "formula": {
>            "sum": [
>                "$score",
>                {
>                    "gauss_decay": {
>                        "x": {
>                            "geo_distance": {
>                                "origin": { "lat": 52.504043, "lon": 13.393236 } // Berlin
>                                "to": "geo.location"
>                            }
>                        },
>                        "scale": 5000 // 5km
>                    }
>                }
>            ]
>        },
>        "defaults": { "geo.location": {"lat": 48.137154, "lon": 11.576124} } // Munich
>    }
>}'
200Successful
1{
2  "usage": {
3    "hardware": {
4      "cpu": 1,
5      "payload_io_read": 1,
6      "payload_io_write": 1,
7      "payload_index_io_read": 1,
8      "payload_index_io_write": 1,
9      "vector_io_read": 1,
10      "vector_io_write": 1
11    },
12    "inference": {
13      "models": {}
14    }
15  },
16  "time": 0.002,
17  "status": "ok",
18  "result": {
19    "points": [
20      {
21        "id": 42,
22        "version": 3,
23        "score": 0.75,
24        "payload": {},
25        "vector": {},
26        "shard_key": "region_1",
27        "order_value": 42
28      }
29    ]
30  }
31}

Universally query points. This endpoint covers all capabilities of search, recommend, discover, filters. But also enables hybrid and multi-stage queries.

Was this page helpful?
Previous

Query points in batch

Next
Built with

Authentication

api-keystring
API Key authentication via header

Path parameters

collection_namestringRequired
Name of the collection to query

Query parameters

consistencyinteger or enumOptional
Define read consistency guarantees for the operation
timeoutintegerOptional>=1
If set, overrides global timeout for this request. Unit is seconds.

Request

Describes the query to make to the collection
shard_keystring or uint64 or list of strings or uint64s or object or anyOptional
prefetchobject or list of objects or anyOptional

Sub-requests to perform first. If present, the query will be performed on the results of the prefetch(es).

querylist of doubles or object or list of lists of doubles or uint64 or string or object or anyOptional
Query to perform. If missing without prefetches, returns points ordered by their IDs.
usingstring or nullOptional
Define which vector name to use for querying. If missing, the default vector is used.
filterobject or anyOptional

Filter conditions - return only those points that satisfy the specified conditions.

paramsobject or anyOptional
Search params for when there is no prefetch
score_thresholddouble or nullOptional
Return points with scores better than this threshold.
limitinteger or nullOptional>=1
Max number of points to return. Default is 10.
offsetinteger or nullOptional>=0
Offset of the result. Skip this many points. Default is 0
with_vectorboolean or list of strings or anyOptional
Options for specifying which vectors to include into the response. Default is false.
with_payloadboolean or list of strings or object or anyOptional
Options for specifying which payload to include or not. Default is false.
lookup_fromobject or anyOptional

The location to use for IDs lookup, if not specified - use the current collection and the ‘using’ vector Note: the other collection vectors should have the same vector size as the ‘using’ vector in the current collection

Response

successful operation
usageobject or any
timedouble
Time spent to process this request
statusstring
resultobject