Retrieves the most relevant chunks per document in a single grouped query. Results are organized by a field you specify — for example, document_id — so each group surfaces only its best-matching chunks. This is especially useful in retrieval-augmented generation (RAG) pipelines, where you want one representative result per source document rather than multiple fragments from the same file.
Prerequisites
Before you begin, ensure that you have:
A cluster. See Create a cluster.
An API key. See Manage API keys.
Endpoint
POST https://{Endpoint}/v1/collections/{CollectionName}/query_group_byUsage notes
Specify either
vectororidin the request body. At least one is required.group_by_fielddoes not support schema-free fields. Only fields with a defined schema are accepted.group_countandgroup_topkare best-effort parameters. The service makes a reasonable attempt to honor them, but exact results are not guaranteed.group_topkhas lower priority thangroup_count.
Examples
All examples use the group_by_demo collection. For details on how this collection is set up, see Grouped vector search.
Replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with your cluster endpoint before running the examples.
Search by vector
Submit a dense vector to find the top matching chunk per group:
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vector": [0.1, 0.2, 0.3, 0.4], // Dense query vector
"group_by_field": "document_id", // Field to group results by
"group_topk": 1, // Chunks to return per group
"group_count": 3, // Maximum number of groups
"include_vector": true
}' \
https://YOUR_CLUSTER_ENDPOINT/v1/collections/group_by_demo/query_group_byThe response groups results under output, with each entry containing a group_id and a docs array:
{
"code": 0,
"request_id": "d6df634a-683d-445e-abe0-d547091d6b3a",
"message": "Success",
"output": [
{
"docs": [
{
"id": "4",
"vector": [0.621783971786499, 0.5220040082931519, 0.8403469920158386, 0.995602011680603],
"fields": {
"document_id": "paper-02",
"content": "xxxD",
"chunk_id": 2
},
"score": 0.028402328
}
],
"group_id": "paper-02"
},
{
"docs": [
{
"id": "1",
"vector": [0.26870301365852356, 0.8718249797821045, 0.6066280007362366, 0.6342290043830872],
"fields": {
"document_id": "paper-01",
"content": "xxxA",
"chunk_id": 1
},
"score": 0.08141637
}
],
"group_id": "paper-01"
},
{
"docs": [
{
"id": "6",
"vector": [0.661965012550354, 0.730430006980896, 0.6105219721794128, 0.22164000570774078],
"fields": {
"document_id": "paper-03",
"content": "xxxF",
"chunk_id": 1
},
"score": 0.2513085
}
],
"group_id": "paper-03"
}
]
}Search by primary key
Use the vector stored for a specific primary key as the query:
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"id": "1", // Primary key; its stored vector is used as the query
"group_by_field": "document_id",
"group_topk": 1,
"group_count": 3,
"include_vector": true
}' \
https://YOUR_CLUSTER_ENDPOINT/v1/collections/group_by_demo/query_group_bySearch with a conditional filter
Add a filter to narrow the candidate set before grouping. The filter must follow SQL WHERE clause syntax:
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"filter": "chunk_id > 1", // Only consider chunks where chunk_id > 1
"group_by_field": "document_id",
"group_topk": 1,
"group_count": 3,
"include_vector": true
}' \
https://YOUR_CLUSTER_ENDPOINT/v1/collections/group_by_demo/queryFor filter syntax details, see Conditional filtering.
Search with dense and sparse vectors
Combine a dense vector and a sparse vector for hybrid retrieval:
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vector": [0.1, 0.2, 0.3, 0.4], // Dense vector
"sparse_vector": {"1": 0.4, "10000": 0.6, "222222": 0.8}, // Sparse vector
"group_by_field": "document_id",
"group_topk": 1,
"group_count": 3,
"include_vector": true
}' \
https://YOUR_CLUSTER_ENDPOINT/v1/collections/group_by_demo/queryRequest parameters
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
{Endpoint} | path | str | Yes | The cluster endpoint. Find it on the cluster details page in the console. |
{CollectionName} | path | str | Yes | The name of the collection. |
dashvector-auth-token | header | str | Yes | The API key. |
group_by_field | body | str | Yes | The field to group results by. Schema-free fields are not supported. |
group_count | body | int | No | The maximum number of groups to return. Best-effort; exact count is not guaranteed. |
group_topk | body | int | No | The maximum number of results per group. Best-effort; lower priority than group_count. |
vector | body | array | No | The dense query vector. Required if id is not specified. |
sparse_vector | body | dict | No | The sparse query vector. |
id | body | str | No | The primary key. The similarity search uses the vector stored for this key. Required if vector is not specified. |
filter | body | str | No | A conditional filter using SQL WHERE clause syntax. See Conditional filtering. |
include_vector | body | bool | No | Specifies whether to include vectors in the response. Default: false. |
output_fields | body | array | No | The fields to include in each result. All fields are returned by default. Pass [] to return no fields. |
partition | body | str | No | The name of the partition to search within. |
Response parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
code | int | The status code. See Status codes. | 0 |
message | str | The status message. | success |
request_id | str | The request ID. | 19215409-ea66-4db9-8764-26ce2eb5bb99 |
output | array | The grouped results. Each entry contains a group_id and a docs array. See the Group section in Data types. | — |