Query points

POST

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

Path parameters

collection_namestringRequired

Name of the collection to query

Query parameters

consistencyinteger or enumOptional

Define read consistency guarantees for the operation

timeoutintegerOptional

If set, overrides global timeout for this request. Unit is seconds.

Request

This endpoint expects an object.

shard_keystring or integer or list of strings or integers 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 integer or string or object or anyOptional

Query to perform. If missing without prefetches, returns points ordered by their IDs.

usingstringOptional

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_thresholddoubleOptional

Return points with scores better than this threshold.

limitintegerOptional

Max number of points to return. Default is 10.

offsetintegerOptional

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

This endpoint returns an object.

timedoubleOptional

Time spent to process this request

statusstringOptional

resultobjectOptional

POST

1 # Query nearest by ID
2 curl  -X POST \
3   'http://localhost:6333/collections/collection_name/points/query' \
4   --header 'api-key: <api-key-value>' \
5   --header 'Content-Type: application/json' \
6   --data-raw '{
7   "query": "43cf51e2-8777-4f52-bc74-c2cbde0c8b04"
8 }'
9 
10 # Recommend on the average of these vectors
11 curl  -X POST \
12   'http://localhost:6333/collections/collection_name/points/query' \
13   --header 'api-key: <api-key-value>' \
14   --header 'Content-Type: application/json' \
15   --data-raw '{
16   "query": {
17     "recommend": {
18       "positive": [
19         [
20           0.11,
21           0.35,
22           0.6
23         ]
24       ],
25       "negative": [
26         "43cf51e2-8777-4f52-bc74-c2cbde0c8b04",
27         [
28           0.01,
29           0.45,
30           0.67
31         ]
32       ]
33     }
34   }
35 }'
36 
37 # Fusion query
38 curl  -X POST \
39   'http://localhost:6333/collections/collection_name/points/query' \
40   --header 'api-key: <api-key-value>' \
41   --header 'Content-Type: application/json' \
42   --data-raw '{
43   "prefetch": [
44     {
45       "query": {
46         "values": [
47           0.22,
48           0.8
49         ],
50         "indices": [
51           1,
52           42
53         ]
54       },
55       "using": "sparse",
56       "limit": 20
57     },
58     {
59       "query": [
60         0.01,
61         0.45,
62         0.67
63       ],
64       "using": "dense",
65       "limit": 20
66     }
67   ],
68   "query": {
69     "fusion": "rrf"
70   }
71 }'
72 
73 # 2-stage query
74 curl  -X POST \
75   'http://localhost:6333/collections/collection_name/points/query' \
76   --header 'api-key: <api-key-value>' \
77   --header 'Content-Type: application/json' \
78   --data-raw '{
79   "prefetch": {
80     "query": [
81       1,
82       23,
83       45,
84       67
85     ],
86     "limit": 100
87   },
88   "query": [
89     [
90       0.1,
91       0.2,
92       0.3
93     ],
94     [
95       0.2,
96       0.1,
97       0.35
98     ],
99     [
100       0.8,
101       0.9,
102       0.53
103     ]
104   ],
105   "using": "colbert",
106   "limit": 10
107 }'
108 
109 # Random sampling (as of 1.11.0)
110 curl  -X POST \
111   'http://localhost:6333/collections/collection_name/points/query' \
112   --header 'api-key: <api-key-value>' \
113   --header 'Content-Type: application/json' \
114   --data-raw '{
115   "query": {
116     "sample": "random"
117   }
118 }'

200Successful

1 {
2   "time": 0.002,
3   "status": "ok",
4   "result": {
5     "points": [
6       {
7         "id": 42,
8         "version": 3,
9         "score": 0.75,
10         "payload": {
11           "city": "London",
12           "color": "green"
13         },
14         "vector": [
15           0.875,
16           0.140625,
17           0.897599995136261
18         ],
19         "shard_key": "region_1",
20         "order_value": 42
21       }
22     ]
23   }
24 }

Built with

1	# Query nearest by ID
2	curl -X POST \
3	'http://localhost:6333/collections/collection_name/points/query' \
4	--header 'api-key: <api-key-value>' \
5	--header 'Content-Type: application/json' \
6	--data-raw '{
7	"query": "43cf51e2-8777-4f52-bc74-c2cbde0c8b04"
8	}'
9
10	# Recommend on the average of these vectors
11	curl -X POST \
12	'http://localhost:6333/collections/collection_name/points/query' \
13	--header 'api-key: <api-key-value>' \
14	--header 'Content-Type: application/json' \
15	--data-raw '{
16	"query": {
17	"recommend": {
18	"positive": [
19	[
20	0.11,
21	0.35,
22	0.6
23	]
24	],
25	"negative": [
26	"43cf51e2-8777-4f52-bc74-c2cbde0c8b04",
27	[
28	0.01,
29	0.45,
30	0.67
31	]
32	]
33	}
34	}
35	}'
36
37	# Fusion query
38	curl -X POST \
39	'http://localhost:6333/collections/collection_name/points/query' \
40	--header 'api-key: <api-key-value>' \
41	--header 'Content-Type: application/json' \
42	--data-raw '{
43	"prefetch": [
44	{
45	"query": {
46	"values": [
47	0.22,
48	0.8
49	],
50	"indices": [
51	1,
52	42
53	]
54	},
55	"using": "sparse",
56	"limit": 20
57	},
58	{
59	"query": [
60	0.01,
61	0.45,
62	0.67
63	],
64	"using": "dense",
65	"limit": 20
66	}
67	],
68	"query": {
69	"fusion": "rrf"
70	}
71	}'
72
73	# 2-stage query
74	curl -X POST \
75	'http://localhost:6333/collections/collection_name/points/query' \
76	--header 'api-key: <api-key-value>' \
77	--header 'Content-Type: application/json' \
78	--data-raw '{
79	"prefetch": {
80	"query": [
81	1,
82	23,
83	45,
84	67
85	],
86	"limit": 100
87	},
88	"query": [
89	[
90	0.1,
91	0.2,
92	0.3
93	],
94	[
95	0.2,
96	0.1,
97	0.35
98	],
99	[
100	0.8,
101	0.9,
102	0.53
103	]
104	],
105	"using": "colbert",
106	"limit": 10
107	}'
108
109	# Random sampling (as of 1.11.0)
110	curl -X POST \
111	'http://localhost:6333/collections/collection_name/points/query' \
112	--header 'api-key: <api-key-value>' \
113	--header 'Content-Type: application/json' \
114	--data-raw '{
115	"query": {
116	"sample": "random"
117	}
118	}'

1	{
2	"time": 0.002,
3	"status": "ok",
4	"result": {
5	"points": [
6	{
7	"id": 42,
8	"version": 3,
9	"score": 0.75,
10	"payload": {
11	"city": "London",
12	"color": "green"
13	},
14	"vector": [
15	0.875,
16	0.140625,
17	0.897599995136261
18	],
19	"shard_key": "region_1",
20	"order_value": 42
21	}
22	]
23	}
24	}