> This page is for version v1.19.x.
> For other versions, use one of these documentation indexes:
> - v1.20.x (default): https://api.qdrant.tech/v-1-20-x/llms.txt
> - v1.19.x: https://api.qdrant.tech/v-1-19-x/llms.txt
> - v1.18.x: https://api.qdrant.tech/v-1-18-x/llms.txt
> - v1.17.x: https://api.qdrant.tech/v-1-17-x/llms.txt
> - v1.16.x: https://api.qdrant.tech/v-1-16-x/llms.txt
> - v1.15.x: https://api.qdrant.tech/v-1-15-x/llms.txt
> - v1.14.x: https://api.qdrant.tech/v-1-14-x/llms.txt
> - v1.13.x: https://api.qdrant.tech/v-1-13-x/llms.txt
> - v1.12.x: https://api.qdrant.tech/v-1-12-x/llms.txt
> - v1.11.x: https://api.qdrant.tech/v-1-11-x/llms.txt
> - v1.10.x: https://api.qdrant.tech/v-1-10-x/llms.txt
> - v1.9.x: https://api.qdrant.tech/v-1-9-x/llms.txt
> - master: https://api.qdrant.tech/master/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.qdrant.tech/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.qdrant.tech/_mcp/server.

# Query point groups

POST http://localhost:6333/collections/{collection_name}/points/query/groups
Content-Type: application/json

Universally query points and group results by a specified payload field. This endpoint covers all capabilities of search, recommend, discover, filters. But also enables hybrid and multi-stage queries.

Reference: https://api.qdrant.tech/api-reference/search/query-points-groups

## Authentication

- `api-key` header (required) — Authorization key, either read-write or read-only
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `collection_name` (string, required) — Name of the collection to query

### Query parameters

- `consistency` (ReadConsistency, optional) — Define read consistency guarantees for the operation
- `timeout` (integer, optional) — If set, overrides global timeout for this request. Unit is seconds.

### Body (application/json)

This endpoint expects a QueryGroupsRequest.

- `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.
- `shard_key` (QueryGroupsRequestShardKey, optional)
- `prefetch` (QueryGroupsRequestPrefetch, optional) — Sub-requests to perform first. If present, the query will be performed on the results of the prefetch(es).
- `query` (QueryGroupsRequestQuery, optional) — Query to perform. If missing without prefetches, returns points ordered by their IDs.
- `using` (string, optional, nullable) — Define which vector name to use for querying. If missing, the default vector is used.
- `filter` (QueryGroupsRequestFilter, optional) — Filter conditions - return only those points that satisfy the specified conditions.
- `params` (QueryGroupsRequestParams, optional) — Search params for when there is no prefetch
- `score_threshold` (float, optional, nullable) — Return points with scores better than this threshold.
- `with_vector` (QueryGroupsRequestWithVector, optional) — Options for specifying which vectors to include into the response. Default is false.
- `with_payload` (QueryGroupsRequestWithPayload, optional) — Options for specifying which payload to include or not. Default is false.
- `lookup_from` (QueryGroupsRequestLookupFrom, optional) — 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
- `group_size` (integer, optional, nullable) — Maximum amount of points to return per group. Default is 3.
- `limit` (integer, optional, nullable) — Maximum amount of groups to return. Default is 10.
- `with_lookup` (QueryGroupsRequestWithLookup, optional) — Look for points in another collection using the group ids

## Response

### 200

successful operation

- `usage` (CollectionsCollectionNamePointsQueryGroupsPostResponsesContentApplicationJsonSchemaUsage, optional)
- `time` (float, optional) — Time spent to process this request
- `status` (string, optional)
- `result` (GroupsResult, optional)

## Errors

### 400 Client Request Error

error

- `time` (float, optional) — Time spent to process this request
- `status` (ErrorResponseStatus, optional)
- `result` (ErrorResponseResult, optional, nullable)

## Types

### QueryGroupsRequestShardKey

- ShardKeySelector: ShardKeySelector
- any

### QueryGroupsRequestPrefetch

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

- Prefetch: Prefetch
- list of Prefetch
- any

### QueryGroupsRequestQuery

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

- QueryInterface: QueryInterface
- any

### QueryGroupsRequestFilter

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

- Filter: Filter
- any

### QueryGroupsRequestParams

Search params for when there is no prefetch

- SearchParams: SearchParams
- any

### QueryGroupsRequestWithVector

Options for specifying which vectors to include into the response. Default is false.

- WithVector: WithVector
- any

### QueryGroupsRequestWithPayload

Options for specifying which payload to include or not. Default is false.

- WithPayloadInterface: WithPayloadInterface
- any

### QueryGroupsRequestLookupFrom

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

- LookupLocation: LookupLocation
- any

### QueryGroupsRequestWithLookup

Look for points in another collection using the group ids

- WithLookupInterface: WithLookupInterface
- any

### ReadConsistency

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
- ReadConsistencyType: enum
  - Allowed values: `majority`, `quorum`, `all`

### CollectionsCollectionNamePointsQueryGroupsPostResponsesContentApplicationJsonSchemaUsage

- Usage: Usage
- any

### GroupsResult

- `groups` (list of PointGroup, required)

### ErrorResponseStatus

- `error` (string, optional) — Description of the occurred error.

### ErrorResponseResult

### ShardKeySelector

- ShardKey: ShardKey
- list of ShardKey
- ShardKeyWithFallback: ShardKeyWithFallback

### Prefetch

- `prefetch` (PrefetchPrefetch, optional) — Sub-requests to perform first. If present, the query will be performed on the results of the prefetches.
- `query` (PrefetchQuery, optional) — Query to perform. If missing without prefetches, returns points ordered by their IDs.
- `using` (string, optional, nullable) — Define which vector name to use for querying. If missing, the default vector is used.
- `filter` (PrefetchFilter, optional) — Filter conditions - return only those points that satisfy the specified conditions.
- `params` (PrefetchParams, optional) — Search params for when there is no prefetch
- `score_threshold` (float, optional, nullable) — Return points with scores better than this threshold.
- `limit` (integer, optional, nullable) — Max number of points to return. Default is 10.
- `lookup_from` (PrefetchLookupFrom, optional) — 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

### QueryInterface

- VectorInput: VectorInput
- Query: Query

### Filter

- `should` (FilterShould, optional) — At least one of those conditions should match
- `min_should` (FilterMinShould, optional) — At least minimum amount of given conditions should match
- `must` (FilterMust, optional) — All conditions must match
- `must_not` (FilterMustNot, optional) — All conditions must NOT match

### SearchParams

Additional parameters of the search

- `hnsw_ef` (integer, optional, 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, optional, default: false) — Search without approximation. If set to true, search may run long but with exact results.
- `quantization` (SearchParamsQuantization, optional) — Quantization params
- `indexed_only` (boolean, optional, default: false) — 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` (SearchParamsAcorn, optional) — ACORN search params
- `idf` (SearchParamsIdf, optional) — Which population sparse vector IDF statistics are computed over. By default (or with explicit `"global"`) statistics are collection-wide. Only applicable to sparse vectors with the IDF modifier enabled.

### WithVector

Options for specifying which vector to include

- boolean
- list of string

### WithPayloadInterface

Options for specifying which payload to include or not

- boolean
- list of string
- PayloadSelector: PayloadSelector

### 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, optional, nullable) — Optional name of the vector field within the collection. If not provided, the default vector field will be used.
- `shard_key` (LookupLocationShardKey, optional) — Specify in which shards to look for the points, if not specified - look in all shards

### WithLookupInterface

- string
- WithLookup: WithLookup

### Usage

Usage of the hardware resources, spent to process the request

- `hardware` (UsageHardware, optional)
- `inference` (UsageInference, optional)

### PointGroup

- `hits` (list of ScoredPoint, required) — Scored points that have the same value of the group_by key
- `id` (GroupId, required) — Value of the group_by key, shared across all the hits in the group
- `lookup` (PointGroupLookup, optional) — Record that has been looked up using the group id

### ShardKey

- string
- uint64

### ShardKeyWithFallback

- `target` (ShardKey, required)
- `fallback` (ShardKey, required)

### PrefetchPrefetch

Sub-requests to perform first. If present, the query will be performed on the results of the prefetches.

- Prefetch: Prefetch
- list of Prefetch
- any

### PrefetchQuery

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

- QueryInterface: QueryInterface
- any

### PrefetchFilter

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

- Filter: Filter
- any

### PrefetchParams

Search params for when there is no prefetch

- SearchParams: SearchParams
- any

### PrefetchLookupFrom

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

- LookupLocation: LookupLocation
- any

### VectorInput

- list of float
- SparseVector: SparseVector
- list of list of float
- ExtendedPointId: ExtendedPointId
- Document: Document
- Image: Image
- InferenceObject: InferenceObject

### Query

- NearestQuery: NearestQuery
- RecommendQuery: RecommendQuery
- DiscoverQuery: DiscoverQuery
- ContextQuery: ContextQuery
- OrderByQuery: OrderByQuery
- FusionQuery: FusionQuery
- RrfQuery: RrfQuery
- FormulaQuery: FormulaQuery
- SampleQuery: SampleQuery
- RelevanceFeedbackQuery: RelevanceFeedbackQuery

### FilterShould

At least one of those conditions should match

- Condition: Condition
- list of Condition
- any

### FilterMinShould

At least minimum amount of given conditions should match

- MinShould: MinShould
- any

### FilterMust

All conditions must match

- Condition: Condition
- list of Condition
- any

### FilterMustNot

All conditions must NOT match

- Condition: Condition
- list of Condition
- any

### SearchParamsQuantization

Quantization params

- QuantizationSearchParams: QuantizationSearchParams
- any

### SearchParamsAcorn

ACORN search params

- AcornSearchParams: AcornSearchParams
- any

### SearchParamsIdf

Which population sparse vector IDF statistics are computed over. By default (or with explicit `"global"`) statistics are collection-wide. Only applicable to sparse vectors with the IDF modifier enabled.

- IdfParams: IdfParams
- any

### PayloadSelector

Specifies how to treat payload selector

- PayloadSelectorInclude: PayloadSelectorInclude
- PayloadSelectorExclude: PayloadSelectorExclude

### LookupLocationShardKey

Specify in which shards to look for the points, if not specified - look in all shards

- ShardKeySelector: ShardKeySelector
- any

### WithLookup

- `collection` (string, required) — Name of the collection to use for points lookup
- `with_payload` (WithLookupWithPayload, optional, default: true) — Options for specifying which payload to include (or not)
- `with_vectors` (WithLookupWithVectors, optional) — Options for specifying which vectors to include (or not)

### UsageHardware

- HardwareUsage: HardwareUsage
- any

### UsageInference

- InferenceUsage: InferenceUsage
- any

### ScoredPoint

Search result

- `id` (ExtendedPointId, required) — Type, used for specifying point ID in user interface
- `version` (uint64, required) — Point version
- `score` (float, required) — Points vector distance to the query vector
- `payload` (ScoredPointPayload, optional) — Payload - values assigned to the point
- `vector` (ScoredPointVector, optional) — Vector of the point
- `shard_key` (ScoredPointShardKey, optional) — Shard Key
- `order_value` (ScoredPointOrderValue, optional) — Order-by value

### GroupId

Value of the group_by key, shared across all the hits in the group

- string
- uint64
- long

### PointGroupLookup

Record that has been looked up using the group id

- Record: Record
- any

### SparseVector

Sparse vector structure

- `indices` (list of uint, required) — Indices must be unique
- `values` (list of float, required) — Values and indices must be the same length

### ExtendedPointId

Type, used for specifying point ID in user interface

- uint64
- string

### Document

WARN: Work-in-progress, unimplemented Text document for embedding. Requires inference infrastructure, unimplemented.

- `text` (string, required) — Text of the document. This field will be used as input for the embedding model.
- `model` (string, required) — Name of the model used to generate the vector. List of available models depends on a provider.
- `options` (DocumentOptions, optional) — Additional options for the model, will be passed to the inference service as-is. See model cards for available options.

### Image

WARN: Work-in-progress, unimplemented Image object for embedding. Requires inference infrastructure, unimplemented.

- `image` (any, required) — Image data: base64 encoded image or an URL
- `model` (string, required) — Name of the model used to generate the vector. List of available models depends on a provider.
- `options` (map from string to any, optional, nullable) — Parameters for the model Values of the parameters are model-specific

### InferenceObject

WARN: Work-in-progress, unimplemented Custom object for embedding. Requires inference infrastructure, unimplemented.

- `object` (any, required) — Arbitrary data, used as input for the embedding model. Used if the model requires more than one input or a custom input.
- `model` (string, required) — Name of the model used to generate the vector. List of available models depends on a provider.
- `options` (map from string to any, optional, nullable) — Parameters for the model Values of the parameters are model-specific

### NearestQuery

- `nearest` (VectorInput, required)
- `mmr` (NearestQueryMmr, optional) — Perform MMR (Maximal Marginal Relevance) reranking after search, using the same vector in this query to calculate relevance.

### RecommendQuery

- `recommend` (RecommendInput, required)

### DiscoverQuery

- `discover` (DiscoverInput, required)

### ContextQuery

- `context` (ContextInput, required)

### OrderByQuery

- `order_by` (OrderByInterface, required)

### FusionQuery

- `fusion` (enum, required) — Fusion algorithm allows to combine results of multiple prefetches. Available fusion algorithms: * `rrf` - Reciprocal Rank Fusion (with default parameters) * `dbsf` - Distribution-Based Score Fusion
  - Allowed values: `rrf`, `dbsf`

### RrfQuery

- `rrf` (Rrf, required) — Parameters for Reciprocal Rank Fusion

### FormulaQuery

- `formula` (Expression, required)
- `defaults` (map from string to any, optional, default: {})

### SampleQuery

- `sample` (enum, required)
  - Allowed values: `random`

### RelevanceFeedbackQuery

- `relevance_feedback` (RelevanceFeedbackInput, required)

### Condition

- FieldCondition: FieldCondition
- IsEmptyCondition: IsEmptyCondition
- IsNullCondition: IsNullCondition
- HasIdCondition: HasIdCondition
- HasVectorCondition: HasVectorCondition
- SliceCondition: SliceCondition
- NestedCondition: NestedCondition
- Filter: Filter

### MinShould

- `conditions` (list of Condition, required)
- `min_count` (integer, required)

### QuantizationSearchParams

Additional parameters of the search

- `ignore` (boolean, optional, default: false) — If true, quantized vectors are ignored. Default is false.
- `rescore` (boolean, optional, 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` (double, optional, nullable) — Oversampling factor for quantization. Default is 1.0. Defines how many extra vectors should be preselected 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 preselected using quantized index, and then top-100 will be returned after re-scoring.

### AcornSearchParams

ACORN-related search parameters

- `enable` (boolean, optional, default: false) — 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` (double, optional, 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.

### IdfParams

Population over which sparse vector IDF statistics are computed for scoring — the *IDF corpus*. * `"global"` — collection-wide statistics, same as omitting the parameter. - `{ "corpus": <filter> }` — document count and per-term document frequencies are computed over the points matching the corpus filter only. The corpus is independent of the retrieval filter and is usually broader than it.

- IdfScope: enum
  - Allowed values: `global`
- IdfCorpusParams: IdfCorpusParams

### PayloadSelectorInclude

- `include` (list of string, required) — Only include this payload keys

### PayloadSelectorExclude

- `exclude` (list of string, required) — Exclude this fields from returning payload

### WithLookupWithPayload

Options for specifying which payload to include (or not)

- WithPayloadInterface: WithPayloadInterface
- any

### WithLookupWithVectors

Options for specifying which vectors to include (or not)

- WithVector: WithVector
- any

### 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)

### InferenceUsage

- `models` (map from string to ModelUsage, required)

### ScoredPointPayload

Payload - values assigned to the point

- Payload: map from string to any
- any

### ScoredPointVector

Vector of the point

- VectorStructOutput: VectorStructOutput
- any

### ScoredPointShardKey

Shard Key

- ShardKey: ShardKey
- any

### ScoredPointOrderValue

Order-by value

- OrderValue: OrderValue
- any

### Record

Point data

- `id` (ExtendedPointId, required) — Type, used for specifying point ID in user interface
- `payload` (RecordPayload, optional) — Payload - values assigned to the point
- `vector` (RecordVector, optional) — Vector of the point
- `shard_key` (RecordShardKey, optional) — Shard Key
- `order_value` (RecordOrderValue, optional)

### DocumentOptions

Option variants for text documents. Ether general-purpose options or BM25-specific options. BM25-specific will only take effect if the `qdrant/bm25` is specified as a model.

- map from string to any
- Bm25Config: Bm25Config

### NearestQueryMmr

Perform MMR (Maximal Marginal Relevance) reranking after search, using the same vector in this query to calculate relevance.

- Mmr: Mmr
- any

### RecommendInput

- `positive` (list of VectorInput, optional, nullable) — Look for vectors closest to the vectors from these points
- `negative` (list of VectorInput, optional, nullable) — Try to avoid vectors like the vector from these points
- `strategy` (RecommendInputStrategy, optional) — How to use the provided vectors to find the results

### DiscoverInput

- `target` (VectorInput, required)
- `context` (DiscoverInputContext, required) — Search space will be constrained by these pairs of vectors

### ContextInput

- ContextPair: ContextPair
- list of ContextPair
- any

### OrderByInterface

- string
- OrderBy: OrderBy

### Rrf

Parameters for Reciprocal Rank Fusion

- `k` (integer, optional, nullable) — K parameter for reciprocal rank fusion
- `weights` (list of float, optional, nullable) — Weights for each prefetch source. Higher weight gives more influence on the final ranking. If not specified, all prefetches are weighted equally. The number of weights should match the number of prefetches.

### Expression

- float
- string
- Condition: Condition
- GeoDistance: GeoDistance
- DatetimeExpression: DatetimeExpression
- DatetimeKeyExpression: DatetimeKeyExpression
- MultExpression: MultExpression
- SumExpression: SumExpression
- NegExpression: NegExpression
- AbsExpression: AbsExpression
- DivExpression: DivExpression
- SqrtExpression: SqrtExpression
- PowExpression: PowExpression
- ExpExpression: ExpExpression
- Log10Expression: Log10Expression
- LnExpression: LnExpression
- LinDecayExpression: LinDecayExpression
- ExpDecayExpression: ExpDecayExpression
- GaussDecayExpression: GaussDecayExpression

### RelevanceFeedbackInput

- `target` (VectorInput, required)
- `feedback` (list of FeedbackItem, required)
- `strategy` (FeedbackStrategy, required)

### FieldCondition

All possible payload filtering conditions

- `key` (string, required) — Payload key
- `match` (FieldConditionMatch, optional) — Check if point has field with a given value
- `range` (FieldConditionRange, optional) — Check if points value lies in a given range
- `geo_bounding_box` (FieldConditionGeoBoundingBox, optional) — Check if points geolocation lies in a given area
- `geo_radius` (FieldConditionGeoRadius, optional) — Check if geo point is within a given radius
- `geo_polygon` (FieldConditionGeoPolygon, optional) — Check if geo point is within a given polygon
- `values_count` (FieldConditionValuesCount, optional) — Check number of values of the field
- `is_empty` (boolean, optional, nullable) — Check that the field is empty, alternative syntax for `is_empty: "field_name"`
- `is_null` (boolean, optional, 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` (list of ExtendedPointId, required)

### HasVectorCondition

Filter points which have specific vector assigned

- `has_vector` (string, required)

### SliceCondition

Select points that fall into one of `total` disjoint deterministic slices of the id space, for parallel scans and reproducible sampling.

- `slice` (Slice, required) — One of `total` disjoint deterministic slices of the id space. A point belongs to the slice iff `hash(id) % total == index`, where `hash` is SipHash-2-4 with a zero key over the canonical id bytes: 8 little-endian bytes for numeric ids, the 16 RFC 4122 bytes for UUIDs. For a fixed `total`, slices `0..total` are disjoint and together cover all points; membership is uniform regardless of the id scheme and stable across queries, segments, platforms and Qdrant versions. Slices with different `total` values are correlated (same hash, no salt): e.g. slice `0` of `total: 4` is a strict subset of slice `0` of `total: 2`. This keeps a smaller sample contained in a larger one.

### NestedCondition

- `nested` (Nested, required) — Select points with payload for a specified nested field

### IdfCorpusParams

IDF statistics computed over the points matching a corpus filter.

- `corpus` (Filter, required)

### ModelUsage

- `tokens` (uint64, required)

### VectorStructOutput

Vector data stored in Point

- list of float
- list of list of float
- map from string to VectorOutput

### OrderValue

- long
- double

### RecordPayload

Payload - values assigned to the point

- Payload: map from string to any
- any

### RecordVector

Vector of the point

- VectorStructOutput: VectorStructOutput
- any

### RecordShardKey

Shard Key

- ShardKey: ShardKey
- any

### RecordOrderValue

- OrderValue: OrderValue
- any

### Bm25Config

Configuration of the local bm25 models.

- `k` (double, optional, default: 1.2) — Controls term frequency saturation. Higher values mean term frequency has more impact. Default is 1.2
- `b` (double, optional, default: 0.75) — Controls document length normalization. Ranges from 0 (no normalization) to 1 (full normalization). Higher values mean longer documents have less impact. Default is 0.75.
- `avg_len` (double, optional, default: 256) — Expected average document length in the collection. Default is 256.
- `tokenizer` (enum, optional)
  - Allowed values: `prefix`, `whitespace`, `word`, `multilingual`
- `language` (string, optional, nullable) — Defines which language to use for text preprocessing. This parameter is used to construct default stopwords filter and stemmer. To disable language-specific processing, set `stemmer` to `{"type": "none"}` and configure an empty stopword set. The legacy `"language": "none"` hack is deprecated and may be rejected in a future release. If not specified, English is assumed.
- `lowercase` (boolean, optional, nullable) — Lowercase the text before tokenization. Default is `true`.
- `ascii_folding` (boolean, optional, nullable) — If true, normalize tokens by folding accented characters to ASCII (e.g., "ação" -> "acao"). Default is `false`.
- `stopwords` (Bm25ConfigStopwords, optional) — Configuration of the stopwords filter. Supports list of pre-defined languages and custom stopwords. Default: initialized for specified `language` or English if not specified.
- `stemmer` (Bm25ConfigStemmer, optional) — Configuration of the stemmer. Processes tokens to their root form. Default: initialized Snowball stemmer for specified `language` or English if not specified.
- `min_token_len` (integer, optional, nullable) — Minimum token length to keep. If token is shorter than this, it will be discarded. Default is `None`, which means no minimum length.
- `max_token_len` (integer, optional, nullable) — Maximum token length to keep. If token is longer than this, it will be discarded. Default is `None`, which means no maximum length.

### Mmr

Maximal Marginal Relevance (MMR) algorithm for re-ranking the points.

- `diversity` (float, optional, nullable) — Tunable parameter for the MMR algorithm. Determines the balance between diversity and relevance. A higher value favors diversity (dissimilarity to selected results), while a lower value favors relevance (similarity to the query vector). Must be in the range [0, 1]. Default value is 0.5.
- `candidates_limit` (integer, optional, nullable) — The maximum number of candidates to consider for re-ranking. If not specified, the `limit` value is used.

### RecommendInputStrategy

How to use the provided vectors to find the results

- RecommendStrategy: enum
  - Allowed values: `average_vector`, `best_score`, `sum_scores`
- any

### DiscoverInputContext

Search space will be constrained by these pairs of vectors

- ContextPair: ContextPair
- list of ContextPair
- any

### ContextPair

- `positive` (VectorInput, required)
- `negative` (VectorInput, required)

### OrderBy

- `key` (string, required) — Payload key to order by
- `direction` (OrderByDirection, optional) — Direction of ordering: `asc` or `desc`. Default is ascending.
- `start_from` (OrderByStartFrom, optional) — Which payload value to start scrolling from. Default is the lowest value for `asc` and the highest for `desc`

### GeoDistance

- `geo_distance` (GeoDistanceParams, required)

### DatetimeExpression

- `datetime` (string, required)

### DatetimeKeyExpression

- `datetime_key` (string, required)

### MultExpression

- `mult` (list of Expression, required)

### SumExpression

- `sum` (list of Expression, required)

### NegExpression

- `neg` (Expression, required)

### AbsExpression

- `abs` (Expression, required)

### DivExpression

- `div` (DivParams, required)

### SqrtExpression

- `sqrt` (Expression, required)

### PowExpression

- `pow` (PowParams, required)

### ExpExpression

- `exp` (Expression, required)

### Log10Expression

- `log10` (Expression, required)

### LnExpression

- `ln` (Expression, required)

### LinDecayExpression

- `lin_decay` (DecayParamsExpression, required)

### ExpDecayExpression

- `exp_decay` (DecayParamsExpression, required)

### GaussDecayExpression

- `gauss_decay` (DecayParamsExpression, required)

### FeedbackItem

- `example` (VectorInput, required)
- `score` (float, required)

### FeedbackStrategy

- NaiveFeedbackStrategy: NaiveFeedbackStrategy

### FieldConditionMatch

Check if point has field with a given value

- Match: Match
- any

### FieldConditionRange

Check if points value lies in a given range

- RangeInterface: RangeInterface
- any

### FieldConditionGeoBoundingBox

Check if points geolocation lies in a given area

- GeoBoundingBox: GeoBoundingBox
- any

### FieldConditionGeoRadius

Check if geo point is within a given radius

- GeoRadius: GeoRadius
- any

### FieldConditionGeoPolygon

Check if geo point is within a given polygon

- GeoPolygon: GeoPolygon
- any

### FieldConditionValuesCount

Check number of values of the field

- ValuesCount: ValuesCount
- any

### PayloadField

Payload field

- `key` (string, required) — Payload field name

### Slice

One of `total` disjoint deterministic slices of the id space. A point belongs to the slice iff `hash(id) % total == index`, where `hash` is SipHash-2-4 with a zero key over the canonical id bytes: 8 little-endian bytes for numeric ids, the 16 RFC 4122 bytes for UUIDs. For a fixed `total`, slices `0..total` are disjoint and together cover all points; membership is uniform regardless of the id scheme and stable across queries, segments, platforms and Qdrant versions. Slices with different `total` values are correlated (same hash, no salt): e.g. slice `0` of `total: 4` is a strict subset of slice `0` of `total: 2`. This keeps a smaller sample contained in a larger one.

- `total` (uint, required) — Total number of disjoint slices the id space is split into
- `index` (uint, required) — Which slice to select, must be in `0..total`

### Nested

Select points with payload for a specified nested field

- `key` (string, required)
- `filter` (Filter, required)

### VectorOutput

Vector Data stored in Point

- list of float
- SparseVector: SparseVector
- list of list of float

### Bm25ConfigStopwords

Configuration of the stopwords filter. Supports list of pre-defined languages and custom stopwords. Default: initialized for specified `language` or English if not specified.

- StopwordsInterface: StopwordsInterface
- any

### Bm25ConfigStemmer

Configuration of the stemmer. Processes tokens to their root form. Default: initialized Snowball stemmer for specified `language` or English if not specified.

- StemmingAlgorithm: StemmingAlgorithm
- any

### OrderByDirection

Direction of ordering: `asc` or `desc`. Default is ascending.

- Direction: enum
  - Allowed values: `asc`, `desc`
- any

### OrderByStartFrom

Which payload value to start scrolling from. Default is the lowest value for `asc` and the highest for `desc`

- StartFrom: StartFrom
- any

### GeoDistanceParams

- `origin` (GeoPoint, required) — Geo point payload schema
- `to` (string, required) — Payload field with the destination geo point

### DivParams

- `left` (Expression, required)
- `right` (Expression, required)
- `by_zero_default` (float, optional, nullable)

### PowParams

- `base` (Expression, required)
- `exponent` (Expression, required)

### DecayParamsExpression

- `x` (Expression, required)
- `target` (DecayParamsExpressionTarget, optional) — The target value to start decaying from. Defaults to 0.
- `scale` (float, optional, nullable) — The scale factor of the decay, in terms of `x`. Defaults to 1.0. Must be a non-zero positive number.
- `midpoint` (float, optional, nullable) — The midpoint of the decay. Should be between 0 and 1.Defaults to 0.5. Output will be this value when `|x - target| == scale`.

### NaiveFeedbackStrategy

- `naive` (NaiveFeedbackStrategyParams, required)

### Match

Match filter request

- MatchValue: MatchValue
- MatchText: MatchText
- MatchTextAny: MatchTextAny
- MatchPhrase: MatchPhrase
- MatchPrefix: MatchPrefix
- MatchAny: MatchAny
- MatchExcept: MatchExcept

### RangeInterface

- Range: Range
- DatetimeRange: DatetimeRange

### GeoBoundingBox

Geo filter request Matches coordinates inside the rectangle, described by coordinates of lop-left and bottom-right edges

- `top_left` (GeoPoint, required) — Geo point payload schema
- `bottom_right` (GeoPoint, required) — Geo point payload schema

### GeoRadius

Geo filter request Matches coordinates inside the circle of `radius` and center with coordinates `center`

- `center` (GeoPoint, required) — Geo point payload schema
- `radius` (double, required) — Radius of the area in meters

### GeoPolygon

Geo filter request Matches coordinates inside the polygon, defined by `exterior` and `interiors`

- `exterior` (GeoLineString, required) — Ordered sequence of GeoPoints representing the line
- `interiors` (list of GeoLineString, optional, nullable) — Interior lines (if present) bound holes within the surface each GeoLineString must consist of a minimum of 4 points, and the first and last points must be the same.

### ValuesCount

Values count filter request

- `lt` (integer, optional, nullable) — point.key.length() \< values\_count.lt
- `gt` (integer, optional, nullable) — point.key.length() > values_count.gt
- `gte` (integer, optional, nullable) — point.key.length() >= values_count.gte
- `lte` (integer, optional, nullable) — point.key.length() \<= values\_count.lte

### StopwordsInterface

- Language: enum
  - Allowed values: `arabic`, `azerbaijani`, `basque`, `bengali`, `catalan`, `chinese`, `danish`, `dutch`, `english`, `finnish`, `french`, `german`, `greek`, `hebrew`, `hinglish`, `hungarian`, `indonesian`, `italian`, `japanese`, `kazakh`, `nepali`, `norwegian`, `portuguese`, `romanian`, `russian`, `slovene`, `spanish`, `swedish`, `tajik`, `turkish`
- StopwordsSet: StopwordsSet

### StemmingAlgorithm

Different stemming algorithms with their configs.

- SnowballParams: SnowballParams
- DisabledStemmerParams: DisabledStemmerParams

### StartFrom

- long
- double
- datetime

### GeoPoint

Geo point payload schema

- `lon` (double, required)
- `lat` (double, required)

### DecayParamsExpressionTarget

The target value to start decaying from. Defaults to 0.

- Expression: Expression
- any

### NaiveFeedbackStrategyParams

- `a` (float, required)
- `b` (float, required)
- `c` (float, required)

### MatchValue

Exact match of the given value

- `value` (ValueVariants, required)

### MatchText

Full-text match of the strings.

- `text` (string, required)

### MatchTextAny

Full-text match of at least one token of the string.

- `text_any` (string, required)

### MatchPhrase

Full-text phrase match of the string.

- `phrase` (string, required)

### MatchPrefix

Match keyword values that start with the given string. Byte-wise (hence, for valid UTF-8, character-wise) and case-sensitive, consistent with exact keyword matching. Served efficiently by a keyword index created with the `prefix` option.

- `prefix` (string, required)

### MatchAny

Exact match on any of the given values

- `any` (AnyVariants, required)

### MatchExcept

Should have at least one value not matching the any given values

- `except` (AnyVariants, required)

### Range

Range filter request

- `lt` (double, optional, nullable) — point.key \< range.lt
- `gt` (double, optional, nullable) — point.key > range.gt
- `gte` (double, optional, nullable) — point.key >= range.gte
- `lte` (double, optional, nullable) — point.key \<= range.lte

### DatetimeRange

Range filter request

- `lt` (datetime, optional, nullable) — point.key \< range.lt
- `gt` (datetime, optional, nullable) — point.key > range.gt
- `gte` (datetime, optional, nullable) — point.key >= range.gte
- `lte` (datetime, optional, nullable) — point.key \<= range.lte

### GeoLineString

Ordered sequence of GeoPoints representing the line

- `points` (list of GeoPoint, required)

### StopwordsSet

- `languages` (list of enum, optional, nullable) — Set of languages to use for stopwords. Multiple pre-defined lists of stopwords can be combined.
  - Allowed values: `arabic`, `azerbaijani`, `basque`, `bengali`, `catalan`, `chinese`, `danish`, `dutch`, `english`, `finnish`, `french`, `german`, `greek`, `hebrew`, `hinglish`, `hungarian`, `indonesian`, `italian`, `japanese`, `kazakh`, `nepali`, `norwegian`, `portuguese`, `romanian`, `russian`, `slovene`, `spanish`, `swedish`, `tajik`, `turkish`
- `custom` (list of string, optional, nullable) — Custom stopwords set. Will be merged with the languages set.

### SnowballParams

- `type` (enum, required)
  - Allowed values: `snowball`
- `language` (enum, required) — Languages supported by snowball stemmer.
  - Allowed values: `arabic`, `armenian`, `danish`, `dutch`, `english`, `finnish`, `french`, `german`, `greek`, `hungarian`, `italian`, `norwegian`, `portuguese`, `romanian`, `russian`, `spanish`, `swedish`, `tamil`, `turkish`

### DisabledStemmerParams

- `type` (enum, required) — Tag selecting the explicit "no stemming" algorithm.
  - Allowed values: `none`

### ValueVariants

- string
- long
- boolean

### AnyVariants

- list of string
- list of long

## Examples

**Request**

```json
{
  "group_by": "string"
}
```

**Response**

```json
{
  "usage": {
    "hardware": {
      "cpu": 1,
      "payload_index_io_read": 1,
      "payload_index_io_write": 1,
      "payload_io_read": 1,
      "payload_io_write": 1,
      "vector_io_read": 1,
      "vector_io_write": 1
    },
    "inference": {
      "models": {}
    }
  },
  "time": 0.002,
  "status": "ok",
  "result": {
    "groups": [
      {
        "hits": [
          {
            "id": 42,
            "version": 3,
            "score": 0.75,
            "payload": {
              "city": "London",
              "color": "green"
            },
            "vector": [
              0.875,
              0.140625,
              0.897599995136261
            ],
            "shard_key": "region_1",
            "order_value": 42
          }
        ],
        "id": "string",
        "lookup": {
          "id": 42,
          "order_value": 42,
          "payload": {
            "city": "London",
            "color": "green"
          },
          "shard_key": "region_1",
          "vector": [
            0.875,
            0.140625,
            0.897599995136261
          ]
        }
      }
    ]
  }
}
```

**SDK Code**

```java
import java.util.List;

import static io.qdrant.client.QueryFactory.nearest;

import io.qdrant.client.grpc.Points.QueryPointGroups;
import io.qdrant.client.grpc.Points.QueryPoints;


QdrantClient client =
    new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());

client
    .queryGroupsAsync(
        QueryPointGroups.newBuilder()
            .setCollectionName("{collection_name}")
            .setGroupBy("document_id")
            .setGroupSize(5)
            .setLimit(10)
            .setQuery(nearest(List.of(0.01f, 0.45f, 0.67f)))
            .build())
    .get();

```

```go
package client

import (
	"context"
	"fmt"

	"github.com/qdrant/go-client/qdrant"
)

func queryGroups() {
	client, err := qdrant.NewClient(&qdrant.Config{
		Host: "localhost",
		Port: 6334,
	})
	if err != nil {
		panic(err)
	}

	groupSize := uint64(5)
	results, err := client.QueryGroups(context.Background(), &qdrant.QueryPointGroups{
		CollectionName: "{collection_name}",
		Query:          qdrant.NewQuery(0.01, 0.45, 0.67),
		GroupBy:        "document_id",
		GroupSize:      &groupSize,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println("Query results: ", results)
}

```

```csharp
using Qdrant.Client;

var client = new QdrantClient("localhost", 6334);

await client.QueryGroupsAsync(
  collectionName: "{collection_name}",
  groupBy: "document_id",
  groupSize: 5,
  limit: 10,
  query: new float[] {
    0.01f, 0.45f, 0.67f
  }
);

```

```typescript
import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.queryGroups("{collection_name}", {
    query: [0.01, 0.45, 0.67],
    group_by: "document_id",
    limit: 10,
    group_size: 5,
});

```

```rust
use qdrant_client::Qdrant;
use qdrant_client::qdrant::{Query, QueryPointGroupsBuilder};

let client = Qdrant::from_url("http://localhost:6334").build()?;

client.query_groups(
    QueryPointGroupsBuilder::new("{collection_name}", "document_id")
        .query(Query::from(vec![0.01, 0.45, 0.67]))
        .limit(10u64)
        .group_size(5u64)
).await?;

```

```python
from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.query_points_groups(
    collection_name="{collection_name}",
    query=[0.01, 0.45, 0.67],
    group_by="document_id",
    limit=10,
    group_size=5,
)
```

```ruby
require 'uri'
require 'net/http'

url = URI("http://localhost:6333/collections/collection_name/points/query/groups")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"group_by\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'http://localhost:6333/collections/collection_name/points/query/groups', [
  'body' => '{
  "group_by": "string"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```swift
import Foundation

let headers = [
  "api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["group_by": "string"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "http://localhost:6333/collections/collection_name/points/query/groups")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```