Group Retrieval Documentation

Search by vector

Pass a query vector and specify the field to group by. Use group_count to control how many groups are returned, and group_topk to control how many results appear per group.

ret = collection.query_group_by(
    vector=[0.1, 0.2, 0.3, 0.4],
    group_by_field='document_id',  # Group results by the document_id field.
    group_count=2,                 # Return up to two groups.
    group_topk=2,                  # Return up to two results per group.
)
if ret:
    print('query_group_by success')
    print(len(ret))
    print('------------------------')
    for group in ret:
        print('group key:', group.group_id)
        for doc in group.docs:
            prefix = ' -'
            print(prefix, doc)

Expected output:

query_group_by success
4
------------------------
group key: paper-01
 - {"id": "2", "fields": {"document_id": "paper-01", "chunk_id": 2, "content": "xxxB"}, "score": 0.6807}
 - {"id": "1", "fields": {"document_id": "paper-01", "chunk_id": 1, "content": "xxxA"}, "score": 0.4289}
group key: paper-02
 - {"id": "3", "fields": {"document_id": "paper-02", "chunk_id": 1, "content": "xxxC"}, "score": 0.6553}
 - {"id": "5", "fields": {"document_id": "paper-02", "chunk_id": 3, "content": "xxxE"}, "score": 0.4401}

The response contains two groups (paper-01 and paper-02), each with up to two results ranked by similarity score.

Search by primary key

Use the id parameter to perform a grouped search based on the vector stored for a specific document.

ret = collection.query_group_by(
    id='1',
    group_by_field='name',
)
if ret:
    print('query_group_by success')
    print(len(ret))
    for group in ret:
        print('group:', group.group_id)
        for doc in group.docs:
            print(doc)
            print(doc.id)
            print(doc.vector)
            print(doc.fields)

Search with a filter

Combine a vector or primary key with a filter expression to narrow results before grouping. The filter must follow SQL WHERE clause syntax.

ret = collection.query(
    vector=[0.1, 0.2, 0.3, 0.4],   # Use id='...' instead to search by primary key.
    group_by_field='name',
    filter='age > 18',              # Return only documents where age is greater than 18.
    output_fields=['name', 'age'],  # Return only the name and age fields.
    include_vector=True
)

For the full filter syntax, see Conditional filtering.

Search with dense and sparse vectors

Include both vector and sparse_vector to combine dense and sparse retrieval. This enables keyword-aware semantic search, where the sparse vector encodes keyword weights alongside the dense semantic embedding.

ret = collection.query(
    vector=[0.1, 0.2, 0.3, 0.4],
    sparse_vector={1: 0.3, 20: 0.7},
    group_by_field='name',
)

For details on keyword-aware semantic search, see Keyword-aware semantic vector search.