--- title: "Recommend point groups" method: POST path: "/collections/{collection_name}/points/recommend/groups" tags: ["Search"] deprecated: true --- # Recommend point groups `POST /collections/{collection_name}/points/recommend/groups` > **Deprecated.** Look for the points which are closer to stored positive examples and at the same time further to negative examples, grouped by a given payload field. ## Path parameters - `collection_name` string, required ## Query parameters - `consistency` union — Read consistency parameter Defines how many replicas should be queried to get the result * `N` - send N random request and return points, which present on all of them * `majority` - send N/2+1 random request and return points, which present on all of them * `quorum` - send requests to all nodes and return points which present on majority of them * `all` - send requests to all nodes and return points which present on all of them Default value is `Factor(1)` - integer - 'majority' | 'quorum' | 'all' — * `majority` - send N/2+1 random request and return points, which present on all of them * `quorum` - send requests to all nodes and return points which present on majority of nodes * `all` - send requests to all nodes and return points which present on all nodes - `timeout` integer ## Request body - RecommendGroupsRequest - `shard_key` union — Specify in which shards to look for the points, if not specified - look in all shards - union - union - string - integer - ShardKey[] - union - string - integer - ShardKeyWithFallback - `target` union, required - string - integer - `fallback` union, required - string - integer - unknown - `positive` RecommendExample[] — Look for vectors closest to those - union - union — Type, used for specifying point ID in user interface - integer - string, uuid - number[] - SparseVector — Sparse vector structure - `indices` integer[], required — Indices must be unique - `values` number[], required — Values and indices must be the same length - `negative` RecommendExample[] — Try to avoid vectors like this - union - union — Type, used for specifying point ID in user interface - integer - string, uuid - number[] - SparseVector — Sparse vector structure - `indices` integer[], required — Indices must be unique - `values` number[], required — Values and indices must be the same length - `strategy` union — How to use positive and negative examples to find the results - 'average_vector' | 'best_score' | 'sum_scores' — How to use positive and negative examples to find the results, default is `average_vector`: * `average_vector` - Average positive and negative vectors and create a single query with the formula `query = avg_pos + avg_pos - avg_neg`. Then performs normal search. * `best_score` - Uses custom search objective. Each candidate is compared against all examples, its score is then chosen from the `max(max_pos_score, max_neg_score)`. If the `max_neg_score` is chosen then it is squared and negated, otherwise it is just the `max_pos_score`. * `sum_scores` - Uses custom search objective. Compares against all inputs, sums all the scores. Scores against positive vectors are added, against negatives are subtracted. - unknown - `filter` union — Look only for points which satisfies this conditions - Filter - `should` union — At least one of those conditions should match - union - FieldCondition — All possible payload filtering conditions - `key` string, required — Payload key - `match` union — Check if point has field with a given value - … - `range` union — Check if points value lies in a given range - … - `geo_bounding_box` union — Check if points geolocation lies in a given area - … - `geo_radius` union — Check if geo point is within a given radius - … - `geo_polygon` union — Check if geo point is within a given polygon - … - `values_count` union — Check number of values of the field - … - `is_empty` boolean, nullable — Check that the field is empty, alternative syntax for `is_empty: "field_name"` - `is_null` boolean, nullable — Check that the field is null, alternative syntax for `is_null: "field_name"` - IsEmptyCondition — Select points with empty payload for a specified field - `is_empty` PayloadField, required — Payload field - … - IsNullCondition — Select points with null payload for a specified field - `is_null` PayloadField, required — Payload field - … - HasIdCondition — ID-based filtering condition - `has_id` ExtendedPointId[], required - … - HasVectorCondition — Filter points which have specific vector assigned - `has_vector` string, required - NestedCondition - `nested` Nested, required — Select points with payload for a specified nested field - … - Filter — recursive - Condition[] - union - FieldCondition — All possible payload filtering conditions - … - IsEmptyCondition — Select points with empty payload for a specified field - … - IsNullCondition — Select points with null payload for a specified field - … - HasIdCondition — ID-based filtering condition - … - HasVectorCondition — Filter points which have specific vector assigned - … - NestedCondition - … - Filter — recursive - unknown - `min_should` union — At least minimum amount of given conditions should match - MinShould - `conditions` Condition[], required - union - … - `min_count` integer, required - unknown - `must` union — All conditions must match - union - FieldCondition — All possible payload filtering conditions - `key` string, required — Payload key - `match` union — Check if point has field with a given value - … - `range` union — Check if points value lies in a given range - … - `geo_bounding_box` union — Check if points geolocation lies in a given area - … - `geo_radius` union — Check if geo point is within a given radius - … - `geo_polygon` union — Check if geo point is within a given polygon - … - `values_count` union — Check number of values of the field - … - `is_empty` boolean, nullable — Check that the field is empty, alternative syntax for `is_empty: "field_name"` - `is_null` boolean, nullable — Check that the field is null, alternative syntax for `is_null: "field_name"` - IsEmptyCondition — Select points with empty payload for a specified field - `is_empty` PayloadField, required — Payload field - … - IsNullCondition — Select points with null payload for a specified field - `is_null` PayloadField, required — Payload field - … - HasIdCondition — ID-based filtering condition - `has_id` ExtendedPointId[], required - … - HasVectorCondition — Filter points which have specific vector assigned - `has_vector` string, required - NestedCondition - `nested` Nested, required — Select points with payload for a specified nested field - … - Filter — recursive - Condition[] - union - FieldCondition — All possible payload filtering conditions - … - IsEmptyCondition — Select points with empty payload for a specified field - … - IsNullCondition — Select points with null payload for a specified field - … - HasIdCondition — ID-based filtering condition - … - HasVectorCondition — Filter points which have specific vector assigned - … - NestedCondition - … - Filter — recursive - unknown - `must_not` union — All conditions must NOT match - union - FieldCondition — All possible payload filtering conditions - `key` string, required — Payload key - `match` union — Check if point has field with a given value - … - `range` union — Check if points value lies in a given range - … - `geo_bounding_box` union — Check if points geolocation lies in a given area - … - `geo_radius` union — Check if geo point is within a given radius - … - `geo_polygon` union — Check if geo point is within a given polygon - … - `values_count` union — Check number of values of the field - … - `is_empty` boolean, nullable — Check that the field is empty, alternative syntax for `is_empty: "field_name"` - `is_null` boolean, nullable — Check that the field is null, alternative syntax for `is_null: "field_name"` - IsEmptyCondition — Select points with empty payload for a specified field - `is_empty` PayloadField, required — Payload field - … - IsNullCondition — Select points with null payload for a specified field - `is_null` PayloadField, required — Payload field - … - HasIdCondition — ID-based filtering condition - `has_id` ExtendedPointId[], required - … - HasVectorCondition — Filter points which have specific vector assigned - `has_vector` string, required - NestedCondition - `nested` Nested, required — Select points with payload for a specified nested field - … - Filter — recursive - Condition[] - union - FieldCondition — All possible payload filtering conditions - … - IsEmptyCondition — Select points with empty payload for a specified field - … - IsNullCondition — Select points with null payload for a specified field - … - HasIdCondition — ID-based filtering condition - … - HasVectorCondition — Filter points which have specific vector assigned - … - NestedCondition - … - Filter — recursive - unknown - unknown - `params` union — Additional search params - SearchParams — Additional parameters of the search - `hnsw_ef` integer, nullable — Params relevant to HNSW index Size of the beam in a beam-search. Larger the value - more accurate the result, more time required for search. - `exact` boolean — Search without approximation. If set to true, search may run long but with exact results. - `quantization` union — Quantization params - QuantizationSearchParams — Additional parameters of the search - `ignore` boolean — If true, quantized vectors are ignored. Default is false. - `rescore` boolean, nullable — If true, use original vectors to re-score top-k results. Might require more time in case if original vectors are stored on disk. If not set, qdrant decides automatically apply rescoring or not. - `oversampling` number, double, nullable — Oversampling factor for quantization. Default is 1.0. Defines how many extra vectors should be pre-selected using quantized index, and then re-scored using original vectors. For example, if `oversampling` is 2.4 and `limit` is 100, then 240 vectors will be pre-selected using quantized index, and then top-100 will be returned after re-scoring. - unknown - `indexed_only` boolean — If enabled, the engine will only perform search among indexed or small segments. Using this option prevents slow searches in case of delayed index, but does not guarantee that all uploaded vectors will be included in search results - `acorn` union — ACORN search params - AcornSearchParams — ACORN-related search parameters - `enable` boolean — If true, then ACORN may be used for the HNSW search based on filters selectivity. Improves search recall for searches with multiple low-selectivity payload filters, at cost of performance. - `max_selectivity` number, double, nullable — Maximum selectivity of filters to enable ACORN. If estimated filters selectivity is higher than this value, ACORN will not be used. Selectivity is estimated as: `estimated number of points satisfying the filters / total number of points`. 0.0 for never, 1.0 for always. Default is 0.4. - unknown - unknown - `with_payload` union — Select which payload to return with the response. Default is false. - union — Options for specifying which payload to include or not - boolean — If `true` - return all payload, If `false` - do not return payload - string[] — Specify which fields to return - union — Specifies how to treat payload selector - PayloadSelectorInclude - `include` string[], required — Only include this payload keys - PayloadSelectorExclude - `exclude` string[], required — Exclude this fields from returning payload - unknown - `with_vector` union — Options for specifying which vectors to include into response. Default is false. - union — Options for specifying which vector to include - boolean — If `true` - return all vector, If `false` - do not return vector - string[] — Specify which vector to return - unknown - `score_threshold` number, float, nullable — Define a minimal score threshold for the result. If defined, less similar results will not be returned. Score of the returned result might be higher or smaller than the threshold depending on the Distance function used. E.g. for cosine similarity only higher scores will be returned. - `using` union — Define which vector to use for recommendation, if not specified - try to use default vector - string - unknown - `lookup_from` union — The location used to lookup vectors. If not specified - use current collection. Note: the other collection should have the same vector size as the current collection - LookupLocation — Defines a location to use for looking up the vector. Specifies collection and vector field name. - `collection` string, required — Name of the collection used for lookup - `vector` string, nullable — Optional name of the vector field within the collection. If not provided, the default vector field will be used. - `shard_key` union — Specify in which shards to look for the points, if not specified - look in all shards - union - union - string - integer - ShardKey[] - union - … - ShardKeyWithFallback - `target` union, required - … - `fallback` union, required - … - unknown - unknown - `group_by` string, required — Payload field to group by, must be a string or number field. If the field contains more than 1 value, all values will be used for grouping. One point can be in multiple groups. - `group_size` integer, required — Maximum amount of points to return per group - `limit` integer, required — Maximum amount of groups to return - `with_lookup` union — Look for points in another collection using the group ids - union - string - WithLookup - `collection` string, required — Name of the collection to use for points lookup - `with_payload` union — Options for specifying which payload to include (or not) - union — Options for specifying which payload to include or not - boolean — If `true` - return all payload, If `false` - do not return payload - string[] — Specify which fields to return - union — Specifies how to treat payload selector - … - unknown - `with_vectors` union — Options for specifying which vectors to include (or not) - union — Options for specifying which vector to include - boolean — If `true` - return all vector, If `false` - do not return vector - string[] — Specify which vector to return - unknown - unknown ## Response `200` successful operation - object - `usage` union - Usage — Usage of the hardware resources, spent to process the request - `hardware` union - HardwareUsage — Usage of the hardware resources, spent to process the request - `cpu` integer, required - `payload_io_read` integer, required - `payload_io_write` integer, required - `payload_index_io_read` integer, required - `payload_index_io_write` integer, required - `vector_io_read` integer, required - `vector_io_write` integer, required - unknown - `inference` union - InferenceUsage - `models` object, required - unknown - unknown - `time` number, float — Time spent to process this request - `status` string - `result` GroupsResult - `groups` PointGroup[], required - `hits` ScoredPoint[], required — Scored points that have the same value of the group_by key - `id` union, required — Type, used for specifying point ID in user interface - integer - string, uuid - `version` integer, required — Point version - `score` number, float, required — Points vector distance to the query vector - `payload` union — Payload - values assigned to the point - Payload - unknown - `vector` union — Vector of the point - union — Vector data stored in Point - number[] - array[] - … - object - unknown - `shard_key` union — Shard Key - union - string - integer - unknown - `order_value` union — Order-by value - union - integer - number, double - unknown - `id` union, required — Value of the group_by key, shared across all the hits in the group - string - integer - integer - `lookup` union — Record that has been looked up using the group id - Record — Point data - `id` union, required — Type, used for specifying point ID in user interface - integer - string, uuid - `payload` union — Payload - values assigned to the point - Payload - unknown - `vector` union — Vector of the point - union — Vector data stored in Point - … - unknown - `shard_key` union — Shard Key - union - … - unknown - `order_value` union - union - … - unknown - unknown ## Other responses - `default` — error - `4XX` — error ## Changes - **2025-11-17** `d09f337ca2f3` — 12 info - added the new optional request property `params/anyOf[#/components/schemas/SearchParams]/acorn` - added `#/components/schemas/MatchTextAny` to the `filter/anyOf[#/components/schemas/Filter]/min_should/anyOf[#/components/schemas/MinShould]/conditions/items/anyOf[#/components/schemas/FieldCondition]/match/anyOf[#/components/schemas/Match]/` request property `anyOf` list - added `#/components/schemas/MatchTextAny` to the `filter/anyOf[#/components/schemas/Filter]/must/anyOf[#/components/schemas/Condition]/anyOf[#/components/schemas/FieldCondition]/match/anyOf[#/components/schemas/Match]/` request property `anyOf` list - added `#/components/schemas/MatchTextAny` to the `filter/anyOf[#/components/schemas/Filter]/must/anyOf[subschema #2]/items/anyOf[#/components/schemas/FieldCondition]/match/anyOf[#/components/schemas/Match]/` request property `anyOf` list - …8 more - …earlier changes not shown [Full history](https://skmtc.dev/qdrant/apis/qdrant-api/changes/collections/:collection_name/points/recommend/groups/post.md) --- [API](https://skmtc.dev/qdrant/apis/qdrant-api.md) · [All operations](https://skmtc.dev/qdrant/apis/qdrant-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qdrant/qdrant-api/revisions/d09f337ca2f3/schema)