Skip to main content
Go to documentation:
⌘U
Weaviate Database

Develop AI applications using Weaviate's APIs and tools

Deploy

Deploy, configure, and maintain Weaviate Database

Query Agent

Run agentic search over your Weaviate Cloud collections

Weaviate Cloud

Manage and scale Weaviate in the cloud

Engram

Persistent memory for LLM agents and applications

Additional resources

Integrations
Weaviate Academy

Need help?

Weaviate LogoAsk AI Assistant⌘K
Support
Community Forum
Contributor guide
The GraphQL API is deprecated

Weaviate Cloud switches off the GraphQL API on May 1, 2027. Clusters that have not used GraphQL in the last 30 days have it switched off from December 1, 2026. New Weaviate Cloud clusters are already created with GraphQL disabled. Self-hosted Weaviate keeps GraphQL until at least May 1, 2027. The first minor release after that date disables it by default, and you can switch it back on. It is removed in a later release.

Use a client library, the web client or the REST Search API instead. See Migrating from the GraphQL API.

Overview

This page covers aggregation queries. They are collectively referred to as Aggregate queries within.

An Aggregate query can aggregate over an entire collection, or the results of a search.

Parameters​

An Aggregate query requires the target collection to be specified. Each query can include any of the following types of arguments:

ArgumentDescriptionRequired
CollectionAlso called "class". The object collection to be retrieved from.Yes
PropertiesProperties to be retrievedYes
Conditional filtersFilter the objects to be retrievedNo
Search operatorsSpecify the search strategy (e.g. near text, hybrid, bm25)No
Additional operatorsSpecify additional operators (e.g. limit, offset, sort)No
Tenant nameSpecify the tenant nameYes, if multi-tenancy enabled. (Read more: what is multi-tenancy?)
Consistency levelSpecify the consistency levelNo

Available properties​

Each data type has its own set of available aggregated properties. The following table shows the available properties for each data type.

Data typeAvailable properties
Textcount, type, topOccurrences (value, occurs)
Numbercount, type, minimum, maximum, mean, median, mode, sum
Integercount, type, minimum, maximum, mean, median, mode, sum
Booleancount, type, totalTrue, totalFalse, percentageTrue, percentageFalse
Datecount, type, minimum, maximum, mean, median, mode
See a GraphQL Aggregate format
{
Aggregate {
<Class> (groupBy:[<property>]) {
groupedBy { # requires `groupBy` filter
path
value
}
meta {
count
}
<propertyOfDatatypeText> {
count
type
topOccurrences (limit: <n_minimum_count>) {
value
occurs
}
}
<propertyOfDatatypeNumberOrInteger> {
count
type
minimum
maximum
mean
median
mode
sum
}
<propertyOfDatatypeBoolean> {
count
type
totalTrue
totalFalse
percentageTrue
percentageFalse
}
<propertyWithReference>
pointingTo
type
}
}
}

Below is an example query to obtain meta information about the Article collection. Note that the data is not grouped here, and results relate to all data objects in the Article collection.

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.
import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
collection = client.collections.use("Article")
response = collection.aggregate.over_all(
total_count=True,
return_metrics=wvc.query.Metrics("wordCount").integer(
count=True,
maximum=True,
mean=True,
median=True,
minimum=True,
mode=True,
sum_=True,
),
)

print(response.total_count)
print(response.properties)

finally:
client.close()
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.aggregate.overAll({
returnMetrics: jeopardy.metrics.aggregate('points')
.integer(['sum','maximum','minimum'])
})

console.log(JSON.stringify(result.properties, null, 2));
package main

import (
"context"
"fmt"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
"github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
cfg := weaviate.Config{
Host: "localhost:8080",
Scheme: "http",
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}

title := graphql.Field{Name: "title"}
url := graphql.Field{Name: "url"}
wordCount := graphql.Field{
Name: "wordCount", Fields: []graphql.Field{
{Name: "mean"},
{Name: "maximum"},
{Name: "median"},
{Name: "minimum"},
{Name: "mode"},
{Name: "sum"},
{Name: "type"},
},
}
inPublication := graphql.Field{
Name: "inPublication", Fields: []graphql.Field{
{Name: "pointingTo"},
{Name: "count"},
},
}

result, err := client.GraphQL().Aggregate().
WithClassName("Article").
WithFields(title, url, wordCount, inPublication).
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", result)
}
echo '{
"query": "{
Aggregate {
Article {
meta {
count
}
inPublication {
pointingTo
type
}
wordCount {
count
maximum
mean
median
minimum
mode
sum
type
}
}
}
}"
}' | curl \
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer learn-weaviate' \
-d @- \
https://edu-demo.weaviate.network/v1/graphql
{
Aggregate {
Article {
meta {
count
}
inPublication {
pointingTo
type
}
wordCount {
count
maximum
mean
median
minimum
mode
sum
type
}
}
}
}

The above query will result in something like the following:

{
"data": {
"Aggregate": {
"Article": [
{
"inPublication": {
"pointingTo": [
"Publication"
],
"type": "cref"
},
"meta": {
"count": 4403
},
"wordCount": {
"count": 4403,
"maximum": 16852,
"mean": 966.0113558937088,
"median": 680,
"minimum": 109,
"mode": 575,
"sum": 4253348,
"type": "int"
}
}
]
}
}
}

Get object count in collection​

Use meta { count } to retrieve the total number of objects in a collection.

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.
import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
collection = client.collections.use("Article")
response = collection.aggregate.over_all(total_count=True)

print(response.total_count)

finally:
client.close()
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.aggregate.overAll()

console.log(result.totalCount);
package main

import (
"context"
"fmt"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
"github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
cfg := weaviate.Config{
Host: "WEAVIATE_INSTANCE_URL", // Replace with your instance URL
Scheme: "https",
}
client := weaviate.New(cfg)

meta := graphql.Field{
Name: "meta", Fields: []graphql.Field{
{Name: "count"},
},
}

result, err := client.GraphQL().Aggregate().
WithClassName("<ClassName>").
WithFields(meta).
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", result)
}
echo '{
"query": "{
Aggregate {
<ClassName> {
meta {
count
}
}
}
}"
}' | curl \
-X POST \
-H 'Content-Type: application/json' \
-d @- \
https://WEAVIATE_INSTANCE_URL/v1/graphql # Replace WEAVIATE_INSTANCE_URL with your instance URL
{ Aggregate { <ClassName> { meta { count } } } }

groupBy argument​

You can use a groupBy argument to get meta information about groups of data objects, from those matching a query. The groups can be based on a property of the data objects.

groupBy limitations
  • groupBy works with the near<Media> operators, and with bm25 and hybrid searches.
  • The groupBy path is limited to one property or cross-reference. Nested paths are not supported.

The groupBy argument is structured as follows for the Aggregate function:

{
Aggregate {
<Class> ( groupBy: ["<propertyName>"] ) {
groupedBy {
path
value
}
meta {
count
}
<propertyName> {
count
}
}
}
}

In the following example, the articles are grouped by the property inPublication, referring to the article's publisher.

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.
import weaviate
import weaviate.classes as wvc
import os
from weaviate.classes.aggregate import GroupByAggregate

client = weaviate.connect_to_local()

try:
# Coming soon

finally:
client.close()
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.aggregate.groupBy.overAll({
groupBy: { property: 'round' }
})

console.log(JSON.stringify(result, null, 2));
package main

import (
"context"
"fmt"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
"github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {

cfg := weaviate.Config{
Host: "localhost:8080",
Scheme: "http",
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
meta := graphql.Field{
Name: "meta", Fields: []graphql.Field{
{Name: "count"},
},
}
wordCount := graphql.Field{
Name: "wordCount", Fields: []graphql.Field{
{Name: "mean"},
},
}
groupedBy := graphql.Field{
Name: "groupedBy", Fields: []graphql.Field{
{Name: "value"},
{Name: "path"},
},
}

result, err := client.GraphQL().Aggregate().
WithFields(meta, wordCount, groupedBy).
WithClassName("Article").
WithGroupBy("inPublication").
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", result)
}
echo '{
"query": "{
Aggregate {
Article(groupBy: [\"inPublication\"]) {
meta {
count
}
wordCount {
mean
}
groupedBy {
value
path
}
}
}
}"
}' | curl \
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer learn-weaviate' \
-d @- \
https://edu-demo.weaviate.network/v1/graphql
{
Aggregate {
Article (groupBy:["inPublication"]) {
meta {
count
}
wordCount {
mean
}
groupedBy {
value
path
}
}
}
}
Expected response
{
"data": {
"Aggregate": {
"Article": [
{
"groupedBy": {
"path": [
"inPublication"
],
"value": "weaviate://localhost/Publication/16476dca-59ce-395e-b896-050080120cd4"
},
"meta": {
"count": 829
},
"wordCount": {
"mean": 604.6537997587454
}
},
{
"groupedBy": {
"path": [
"inPublication"
],
"value": "weaviate://localhost/Publication/c9a0e53b-93fe-38df-a6ea-4c8ff4501783"
},
"meta": {
"count": 618
},
"wordCount": {
"mean": 917.1860841423949
}
},
...
]
}
}
}

Additional filters​

Aggregate functions can be extended with conditional filters read more.

topOccurrences property​

Aggregating data makes the topOccurrences property available. Note that the counts are not dependent on tokenization. The topOccurrences count is based on occurrences of the entire property, or one of the values if the property is an array.

You can optionally specify a limit parameter to limit the returned objects. For example, limit: 5 will return the top 5 most frequent occurrences.

Consistency levels​

Not available with Aggregate

Aggregate queries are currently not available with different consistency levels.

Multi-tenancy​

Where multi-tenancy is configured, the Aggregate function can be configured to aggregate results from a specific tenant.

You can do so by specifying the tenant parameter in the query as shown below, or in the client.

{
Aggregate {
Article (
tenant: "tenantA"
) {
meta {
count
}
}
}
}
See HOW-TO guide

For more information on using multi-tenancy, see the Multi-tenancy operations guide.

You can combine a vector search (e.g. nearObject, nearVector, nearText, nearImage, etc.) with an aggregation. Internally, this is a two-step process where the vector search first finds the desired objects, then the results are aggregated.

Limiting the search space​

Vector searches rank objects by similarity but do not exclude any objects. Thus, for a search operator to impact aggregation, you must limit the search space by setting either objectLimit or certainty for the query:

  • objectLimit, e.g. objectLimit: 100 tells Weaviate to aggregate the first 100 objects retrieved by the vector search query. This is useful when you know upfront how many results you want to serve, for example, in a recommendation scenario where you want to produce 100 recommendations.

  • certainty, e.g. certainty: 0.7 tells Weaviate to aggregate all vector search results with a certainty score of 0.7 or higher. This list has no fixed length, it depends on how many objects are good matches. This is useful in user-facing search scenarios, such as e-commerce. The user might be interested in all search results semantically similar to "apple iphone" and then generate facets.

The aggregation query will fail if neither objectLimit nor certainty is set.

Examples​

Below are examples for nearObject, nearVector, and nearText. Any near<Media> will work.

nearObject​

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.
import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
collection = client.collections.use("Article")
response = collection.aggregate.near_object(
near_object="00037775-1432-35e5-bc59-443baaef7d80",
distance=0.6,
object_limit=200,
total_count=True,
return_metrics=[
wvc.query.Metrics("wordCount").integer(
count=True,
maximum=True,
mean=True,
median=True,
minimum=True,
mode=True,
sum_=True,
),
]
)

print(response.total_count)
print(response.properties)

finally:
client.close()
const collection = client.collections.use('JeopardyQuestion');
const someObjects = await collection.query.fetchObjects({ limit: 1 });
const objectId = someObjects.objects[0].uuid;

const result = await collection.aggregate.nearObject(
objectId,
{
objectLimit: 200,
distance: 0.6,
returnMetrics: collection.metrics.aggregate('points')
.integer(['count', 'sum', 'maximum', 'minimum', 'mean', 'median', 'mode']),
}
)

console.log(result.totalCount);
console.log(JSON.stringify(result.properties, null, 2));
package main

import (
"context"
"fmt"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
"github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
cfg := weaviate.Config{
Host: "localhost:8080",
Scheme: "http",
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}

title := graphql.Field{Name: "title"}
url := graphql.Field{Name: "url"}
wordCount := graphql.Field{
Name: "wordCount", Fields: []graphql.Field{
{Name: "mean"},
{Name: "maximum"},
{Name: "median"},
{Name: "minimum"},
{Name: "mode"},
{Name: "sum"},
{Name: "type"},
},
}
inPublication := graphql.Field{
Name: "inPublication", Fields: []graphql.Field{
{Name: "pointingTo"},
{Name: "count"},
},
}

// nearObject
withNearObject := client.GraphQL().NearObjectArgBuilder().
WithDistance(0.85). // At least one of distance or objectLimit need to be set
WithID("00037775-1432-35e5-bc59-443baaef7d80")

result, err := client.GraphQL().
Aggregate().
WithFields(title, url, wordCount, inPublication).
WithNearObject(nearObject).
WithClassName("Article").
WithObjectLimit(100). // At least one of certainty or objectLimit need to be set
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", result)
}
echo '{
"query": "{
Aggregate {
Article(nearObject:{
id: \"00037775-1432-35e5-bc59-443baaef7d80\"
distance: 0.6
},
objectLimit: 200) {
meta {
count
}
inPublication {
pointingTo
type
}
wordCount {
count
maximum
mean
median
minimum
mode
sum
type
}
}
}
}"
}' | curl \
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer learn-weaviate' \
-d @- \
https://edu-demo.weaviate.network/v1/graphql
{
Aggregate {
Article(
nearObject: {
id: "00037775-1432-35e5-bc59-443baaef7d80"
# prior to v1.14, use `certainty` instead of `distance`
distance: 0.6
},
# at least one of "objectLimit" and/or "distance" must be set when using near<Media>
objectLimit: 200
) {
meta {
count
}
inPublication {
pointingTo
type
}
wordCount {
count
maximum
mean
median
minimum
mode
sum
type
}
}
}
}

nearVector​

Replace placeholder vector

To run this query, replace the placeholder vector with a real vector from the same vectorizer that used to generate object vectors.

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.
import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
collection = client.collections.use("Article")
response = collection.aggregate.near_vector(
near_vector=some_vector,
distance=0.7,
object_limit=100,
total_count=True,
return_metrics=[
wvc.query.Metrics("wordCount").integer(
count=True,
maximum=True,
mean=True,
median=True,
minimum=True,
mode=True,
sum_=True,
),
]
)

print(response.total_count)
print(response.properties)

finally:
client.close()
const collection = client.collections.use('JeopardyQuestion');
const someObjects = await collection.query.fetchObjects({ limit: 1, includeVector: true });
const someVector = someObjects.objects[0].vectors.default;

const result = await collection.aggregate.nearVector(
someVector,
{
objectLimit: 200,
distance: 0.7,
returnMetrics: collection.metrics.aggregate('points')
.integer(['count', 'sum', 'maximum', 'minimum', 'mean', 'median', 'mode']),
}
)

console.log(result.totalCount);
console.log(JSON.stringify(result.properties, null, 2));
package main

import (
"context"
"fmt"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
"github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
cfg := weaviate.Config{
Host: "localhost:8080",
Scheme: "http",
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}

title := graphql.Field{Name: "title"}
url := graphql.Field{Name: "url"}
wordCount := graphql.Field{
Name: "wordCount", Fields: []graphql.Field{
{Name: "mean"},
{Name: "maximum"},
{Name: "median"},
{Name: "minimum"},
{Name: "mode"},
{Name: "sum"},
{Name: "type"},
},
}
inPublication := graphql.Field{
Name: "inPublication", Fields: []graphql.Field{
{Name: "pointingTo"},
{Name: "count"},
},
}

// nearVector
nearVector := &graphql.NearVectorArgumentBuilder{}
nearVector.WithCertainty(0.85). // At least one of certainty or objectLimit need to be set
WithVector([]float32{0.1, 0.2, -0.3})

result, err := client.GraphQL().
Aggregate().
WithFields(title, url, wordCount, inPublication).
WithNearVector(nearVector).
WithClassName("Article").
WithObjectLimit(100). // At least one of certainty or objectLimit need to be set
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", result)
}
echo '{
"query": "{
Aggregate {
Article(nearVector:{
vector: [0.1, 0.2, -0.3]
certainty: 0.7
},
objectLimit: 200) {
meta {
count
}
inPublication {
pointingTo
type
}
wordCount {
count
maximum
mean
median
minimum
mode
sum
type
}
}
}
}"
}' | curl \
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer learn-weaviate' \
-d @- \
https://edu-demo.weaviate.network/v1/graphql
{
Aggregate {
Article(nearVector:{
vector: [0.1, 0.2, -0.3]
certainty: 0.7 # at least one of "objectLimit",
}, # and/or "certainty" must be set
objectLimit: 200) { # when using near<Media>
meta {
count
}
inPublication {
pointingTo
type
}
wordCount {
count
maximum
mean
median
minimum
mode
sum
type
}
}
}
}

nearText​

note

For nearText to be available, a text2vec-* module must be installed with Weaviate.

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.
import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
collection = client.collections.use("Article")
response = collection.aggregate.near_text(
query="apple iphone",
object_limit=200,
total_count=True,
return_metrics=[
wvc.query.Metrics("wordCount").integer(
count=True,
maximum=True,
mean=True,
median=True,
minimum=True,
mode=True,
sum_=True,
),
]
)

print(response.total_count)
print(response.properties)

finally:
client.close()
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.aggregate.nearText('animals in space', {
objectLimit: 10,
returnMetrics: jeopardy.metrics.aggregate('points').number(['sum'])
})

console.log(result.properties['points'].sum);
package main

import (
"context"
"fmt"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
"github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
cfg := weaviate.Config{
Host: "localhost:8080",
Scheme: "http",
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}

title := graphql.Field{Name: "title"}
url := graphql.Field{Name: "url"}
wordCount := graphql.Field{
Name: "wordCount", Fields: []graphql.Field{
{Name: "mean"},
{Name: "maximum"},
{Name: "median"},
{Name: "minimum"},
{Name: "mode"},
{Name: "sum"},
{Name: "type"},
},
}
inPublication := graphql.Field{
Name: "inPublication", Fields: []graphql.Field{
{Name: "pointingTo"},
{Name: "count"},
},
}

// nearText
nearText := &graphql.NearTextArgumentBuilder{}
nearText.WithDistance(0.85). // prior to v1.14 use WithCertainty()
WithConcepts([]string{"apple iphone"})

result, err := client.GraphQL().
Aggregate().
WithFields(title, url, wordCount, inPublication).
WithNearText(nearText).
WithClassName("Article").
WithObjectLimit(100). // at least one of distance or objectLimit need to be set
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", result)
}
# See the notes from the GraphQL example
echo '{
"query": "{
Aggregate {
Article(nearText:{
concepts: [\"apple iphone\"]
distance: 0.7
},
objectLimit: 200) {
meta {
count
}
inPublication {
pointingTo
type
}
wordCount {
count
maximum
mean
median
minimum
mode
sum
type
}
}
}
}"
}' | curl \
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer learn-weaviate' \
-H "X-OpenAI-Api-Key: $OPENAI_API_KEY" \
-d @- \
https://edu-demo.weaviate.network/v1/graphql
{
Aggregate {
Article(nearText:{
concepts: ["apple iphone"]
distance: 0.7 # prior to v1.14 use "certainty" instead of "distance"
},
objectLimit: 200) { # at least one of "objectLimit",
meta { # and/or "distance" must be set
count # when using near media filters
}
inPublication {
pointingTo
type
}
wordCount {
count
maximum
mean
median
minimum
mode
sum
type
}
}
}
}

Questions and feedback​