Skip to main content
Weaviate Docs (migrated from docs.weaviate.io) Docs

Search documentation

Type to search this documentation.

On this pageOverview

Aggregate data

Aggregate queries process the result set to return calculated results. Use aggregate queries for groups of objects or the entire result set.

Additional information

To run an Aggregate query, specify the following:

  • A target collection to search
  • One or more aggregated properties, such as:
    • A meta property
    • An object property
    • The groupedBy property
  • Select at least one sub-property for each selected property

For details, see Aggregate.

Retrieve the count meta property

Section titled “Retrieve the count meta property”

Return the number of objects matched by the query.

Python
jeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.aggregate.over_all(total_count=True)print(response.total_count)
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
response, err := client.GraphQL().Aggregate().  WithClassName("JeopardyQuestion").  WithFields(graphql.Field{    Name: "meta",    Fields: []graphql.Field{      {Name: "count"},    },  }).  Do(ctx)
Java
CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.aggregate.overAll(    a -> a.includeTotalCount(true));System.out.println(response.totalCount());
C#
var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Aggregate.OverAll(    totalCount: true);Console.WriteLine(response.TotalCount);
GraphQL
{
  Aggregate {
    JeopardyQuestion {
      meta {
        count
      }
    }
  }
}
Example response

The output is like this:

JSON
{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "meta": {
            "count": 10000
          }
        }
      ]
    }
  }
}

Aggregate text properties

Section titled “Aggregate text properties”

This example counts occurrence frequencies:

Python
from weaviate.classes.query import Metricsjeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.aggregate.over_all(    return_metrics=Metrics("answer").text(        top_occurrences_count=True,        top_occurrences_value=True,        min_occurrences=5  # Threshold minimum count    ))print(response.properties["answer"].top_occurrences)
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
response, err := client.GraphQL().Aggregate().
  WithClassName("JeopardyQuestion").
  WithFields(graphql.Field{
    Name: "answer",
    Fields: []graphql.Field{
      {Name: "count"},
      {Name: "type"},
      {Name: "topOccurrences",
        Fields: []graphql.Field{
          {Name: "occurs"},
          {Name: "value"},
        },
      },
    },
  }).
  Do(ctx)
Java
CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.aggregate.overAll(    a -> a.metrics(Aggregate.text("answer",        m -> m.topOccurrencesValue().topOccurrencesCount().minOccurrences(5) // Threshold minimum count    )));// TODOπ[g-despot] How to get topOccurences hereSystem.out.println(response.properties().get("answer"));
C#
var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Aggregate.OverAll(    returnMetrics:    [        Metrics            .ForProperty("answer")            .Text(                topOccurrencesCount: true,                topOccurrencesValue: true,                minOccurrences: 5 // Threshold minimum count            ),    ]);var answerMetrics = response.Properties["answer"] as Aggregate.Text;if (answerMetrics != null){    Console.WriteLine(JsonSerializer.Serialize(answerMetrics.TopOccurrences));}
GraphQL
{  Aggregate {    JeopardyQuestion {      answer {        count        type        topOccurrences {          occurs          value        }      }    }  }}
Example response

The output is like this:

JSON
{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "answer": {
            "count": 10000,
            "topOccurrences": [
              {
                "occurs": 19,
                "value": "Australia"
              },
              {
                "occurs": 18,
                "value": "Hawaii"
              },
              {
                "occurs": 16,
                "value": "Boston"
              },
              {
                "occurs": 15,
                "value": "French"
              },
              {
                "occurs": 15,
                "value": "India"
              }
            ],
            "type": "text"
          }
        }
      ]
    }
  }
}

Aggregate int properties

Section titled “Aggregate int properties”

This example shows aggregation with integers.

Python
from weaviate.classes.query import Metricsjeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.aggregate.over_all(    # Use `.number` for floats (`NUMBER` datatype in Weaviate)    return_metrics=Metrics("points").integer(sum_=True, maximum=True, minimum=True),)print(response.properties["points"].sum_)print(response.properties["points"].minimum)print(response.properties["points"].maximum)
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
response, err := client.GraphQL().Aggregate().  WithClassName("JeopardyQuestion").  WithFields(graphql.Field{    Name: "points",    Fields: []graphql.Field{      {Name: "count"},      {Name: "sum"},    },  }).  Do(ctx)
Java
CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.aggregate.overAll(    // Use .number for floats (NUMBER datatype in Weaviate)    a -> a.metrics(Aggregate.integer("points", m -> m.sum().max().min())));// TODOπ[g-despot] How to get sum, min and max hereSystem.out.println(response.properties().get("points"));System.out.println(response.properties().get("points"));System.out.println(response.properties().get("points"));
C#
var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Aggregate.OverAll(    // Use .Number for floats (NUMBER datatype in Weaviate)    returnMetrics:    [        Metrics.ForProperty("points").Integer(sum: true, maximum: true, minimum: true),    ]);var pointsMetrics = response.Properties["points"] as Aggregate.Integer;if (pointsMetrics != null){    Console.WriteLine($"Sum: {pointsMetrics.Sum}");    Console.WriteLine($"Max: {pointsMetrics.Maximum}");    Console.WriteLine($"Min: {pointsMetrics.Minimum}");}
GraphQL
{  Aggregate {    JeopardyQuestion {      points {        count        sum      }    }  }}
Example response

The output is like this:

JSON
{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "points": {
            "count": 10000,
            "sum": 6324100
          }
        }
      ]
    }
  }
}

Aggregate groupedBy properties

Section titled “Aggregate groupedBy properties”

To group your results, use groupBy in the query.

To retrieve aggregate data for each group, use the groupedBy properties.

Python
from weaviate.classes.aggregate import GroupByAggregatejeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.aggregate.over_all(    group_by=GroupByAggregate(prop="round"))# print rounds names and the count for eachfor group in response.groups:    print(f"Value: {group.grouped_by.value} Count: {group.total_count}")
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
response, err := client.GraphQL().Aggregate().  WithClassName("JeopardyQuestion").  WithGroupBy("round").  WithFields(    graphql.Field{      Name: "groupedBy",      Fields: []graphql.Field{        {Name: "value"},      },    },    graphql.Field{      Name: "meta",      Fields: []graphql.Field{        {Name: "count"},      },    },  ).  Do(ctx)
Java
CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.aggregate.overAll(    GroupBy.property("round"));// print rounds names and the count for eachfor (var group : response.groups()) {  System.out.printf("Value: %s Count: %d\n", group.groupedBy().value(),      group.totalCount());}
C#
var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Aggregate.OverAll(    groupBy: new Aggregate.GroupBy("round"));// print rounds names and the count for eachforeach (var group in response.Groups){    Console.WriteLine($"Value: {group.GroupedBy.Value} Count: {group.TotalCount}");}
GraphQL
{  Aggregate {    JeopardyQuestion(groupBy: "round") {      groupedBy {        value      }      meta {        count      }    }  }}
Example response

The output is like this:

JSON
{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "groupedBy": {
            "value": "Double Jeopardy!"
          },
          "meta": {
            "count": 5193
          }
        },
        {
          "groupedBy": {
            "value": "Jeopardy!"
          },
          "meta": {
            "count": 4522
          }
        },
        {
          "groupedBy": {
            "value": "Final Jeopardy!"
          },
          "meta": {
            "count": 285
          }
        }
      ]
    }
  }
}
Section titled “Aggregate with a similarity search”

You can use Aggregate with a similarity search operator (one of the Near operators).

Use objectLimit to specify the maximum number of objects to aggregate.

Python
from weaviate.classes.query import Metricsjeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.aggregate.near_text(    query="animals in space",    object_limit=10,    return_metrics=Metrics("points").number(sum_=True),)print(response.properties["points"].sum_)
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
response, err := client.GraphQL().Aggregate().  WithClassName("JeopardyQuestion").  WithNearText(client.GraphQL().NearTextArgBuilder().    WithConcepts([]string{"animals in space"})).  WithObjectLimit(10).  WithFields(graphql.Field{    Name: "points",    Fields: []graphql.Field{      {Name: "sum"},    },  }).  Do(ctx)
Java
CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.aggregate.nearText("animals in space", a -> a    .distance(0)    , n -> n.includeTotalCount(false)        .metrics(Aggregate.number("points", m -> m.sum())));System.out.println(response.properties().get("points"));
C#
var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Aggregate.NearText(    "animals in space",    limit: 10,    returnMetrics: [Metrics.ForProperty("points").Number(sum: true)]);var pointsMetrics = response.Properties["points"] as Aggregate.Number;Console.WriteLine(JsonSerializer.Serialize(pointsMetrics));
GraphQL
{  Aggregate {    JeopardyQuestion(      nearText: {        concepts: ["animals in space"]      }      objectLimit: 10    ) {      points {        sum      }    }  }}
Example response

The output is like this:

JSON
{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "points": {
            "sum": 4600
          }
        }
      ]
    }
  }
}

Set a similarity distance

Section titled “Set a similarity distance”

You can use Aggregate with a similarity search operator (one of the Near operators).

Use distance to specify how similar the objects should be.

Python
from weaviate.classes.query import Metricsjeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.aggregate.near_text(    query="animals in space",    distance=0.19,    return_metrics=Metrics("points").number(sum_=True),)print(response.properties["points"].sum_)
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
response, err := client.GraphQL().Aggregate().  WithClassName("JeopardyQuestion").  WithNearText(client.GraphQL().NearTextArgBuilder().    WithConcepts([]string{"animals in space"}).    WithDistance(0.19)).  WithFields(graphql.Field{    Name: "points",    Fields: []graphql.Field{      {Name: "sum"},    },  }).  Do(ctx)
Java
CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.aggregate.nearText("animals in space",    a -> a.objectLimit(10)        //.distance(0.19f)        .metrics(Aggregate.number("points", m -> m.sum())));System.out.println(response.properties().get("points"));
C#
var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Aggregate.NearText(    ["animals in space"],    distance: 0.19,    returnMetrics: [Metrics.ForProperty("points").Number(sum: true)]);var pointsMetrics = response.Properties["points"] as Aggregate.Number;Console.WriteLine(JsonSerializer.Serialize(pointsMetrics));
GraphQL
{  Aggregate {    JeopardyQuestion(      nearText: {        concepts: ["animals in space"]        distance: 0.19      }    ) {      points {        sum      }    }  }}
Example response

The output is like this:

JSON
{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "points": {
            "sum": 2500
          }
        }
      ]
    }
  }
}
Section titled “Aggregate with a hybrid search”

You can use Aggregate with a hybrid search operator.

Python
from weaviate.classes.query import Metrics, BM25Operatorjeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.aggregate.hybrid(    query="animals in space",    bm25_operator=BM25Operator.and_(),  # Additional parameters available, such as `bm25_operator`, `filter` etc.    object_limit=10,    return_metrics=Metrics("points").number(sum_=True),)print(response.properties["points"].sum_)
JavaScript/TypeScript
const jeopardy = client.collections.use("JeopardyQuestion")

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

console.log(response.properties['points'].sum)
Go
response, err := client.GraphQL().Aggregate().  WithClassName("JeopardyQuestion").  WithNearText(client.GraphQL().NearTextArgBuilder().    WithConcepts([]string{"animals in space"})).  WithObjectLimit(10).  WithFields(graphql.Field{    Name: "points",    Fields: []graphql.Field{      {Name: "sum"},    },  }).  Do(ctx)
Java
CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.aggregate.hybrid("animals in space", a -> a    // TODO[g-despot] what about bm25Operator?    // .bm25Operator(...) // Additional parameters available, such as    // `bm25_operator`, `filter` etc.    .objectLimit(10)    .metrics(Aggregate.number("points", m -> m.sum())));System.out.println(response.properties().get("points"));
C#
var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Aggregate.Hybrid(    "animals in space",    // Additional parameters are available, such as `bm25Operator`, `filters`, etc.    objectLimit: 10,    returnMetrics: [Metrics.ForProperty("points").Number(sum: true)]);var pointsMetrics = response.Properties["points"] as Aggregate.Number;Console.WriteLine(JsonSerializer.Serialize(pointsMetrics));
GraphQL
{  Aggregate {    JeopardyQuestion(      hybrid: {        query: "animals in space"        bm25SearchOperator: {          operator: Or          minimumOrTokensMatch: 2        }      }      objectLimit: 10    ) {      points {        sum      }    }  }}
Example response

The output is like this:

JSON
{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "points": {
            "sum": 6700
          }
        }
      ]
    }
  }
}

Filter results

Section titled “Filter results”

For more specific results, use a filter to narrow your search.

Python
from weaviate.classes.query import Filterjeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.aggregate.over_all(    filters=Filter.by_property("round").equal("Final Jeopardy!"),)print(response.total_count)
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
// Add this line to imports: "github.com/weaviate/weaviate-go-client/v5/weaviate/filters"response, err := client.GraphQL().Aggregate().  WithClassName("JeopardyQuestion").  WithWhere(filters.Where().    WithPath([]string{"round"}).    WithOperator(filters.Equal).    WithValueString("Final Jeopardy!")).  WithFields(graphql.Field{    Name: "meta",    Fields: []graphql.Field{      {Name: "count"},    },  }).  Do(ctx)
Java
// TODO[g-despot] Why is where not available on overAll()?CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.aggregate.overAll(a -> a    // .filters(Filter.property("round").eq("Final Jeopardy!"))    .includeTotalCount(true));System.out.println(response.totalCount());
C#
var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Aggregate.OverAll(    filters: Filter.Property("round").IsEqual("Final Jeopardy!"),    totalCount: true);Console.WriteLine(response.TotalCount);
GraphQL
{  Aggregate {    JeopardyQuestion(where: {      path: ["round"]      operator: Equal      valueText: "Final Jeopardy!"    }) {      meta {        count      }    }  }}
Example response

The output is like this:

JSON
{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "meta": {
            "count": 285
          }
        }
      ]
    }
  }
}
Section titled “Related pages”

Questions and feedback

Section titled “Questions and feedback”

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.

Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu