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:
| Argument | Description | Required |
|---|---|---|
| Collection | Also called "class". The object collection to be retrieved from. | Yes |
| Properties | Properties to be retrieved | Yes |
| Conditional filters | Filter the objects to be retrieved | No |
| Search operators | Specify the search strategy (e.g. near text, hybrid, bm25) | No |
| Additional operators | Specify additional operators (e.g. limit, offset, sort) | No |
| Tenant name | Specify the tenant name | Yes, if multi-tenancy enabled. (Read more: what is multi-tenancy?) |
| Consistency level | Specify the consistency level | No |
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 type | Available properties |
|---|---|
| Text | count, type, topOccurrences (value, occurs) |
| Number | count, type, minimum, maximum, mean, median, mode, sum |
| Integer | count, type, minimum, maximum, mean, median, mode, sum |
| Boolean | count, type, totalTrue, totalFalse, percentageTrue, percentageFalse |
| Date | count, 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.
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.
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 limitationsgroupByworks with thenear<Media>operators, and withbm25andhybridsearches.- The
groupBypathis 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.
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
AggregateAggregate 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
}
}
}
}
For more information on using multi-tenancy, see the Multi-tenancy operations guide.
Aggregating a Vector Search / Faceted Vector Search
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: 100tells 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.7tells 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
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
To run this query, replace the placeholder vector with a real vector from the same vectorizer that used to generate object vectors.
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
For nearText to be available, a text2vec-* module must be installed with Weaviate.
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
Have a question or feedback? Here's how to reach us.
