---
title: "Aggregate data"
description: "Aggregate data (count, sum, average) with code examples in Python, TypeScript, Go, Java, and C#."
url: https://docs.weaviate.io/weaviate/search/aggregate
---

# 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](https://docs.weaviate.io/weaviate/api/graphql/aggregate).

## Retrieve the `count` meta property

Return the number of objects matched by the query.

**Python**

```py
jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.aggregate.over_all(total_count=True)

print(response.total_count)
```

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.aggregate.overAll()

console.log(result.totalCount);
```

**Go (v5)**

```go
response, err := client.GraphQL().Aggregate().
  WithClassName("JeopardyQuestion").
  WithFields(graphql.Field{
    Name: "meta",
    Fields: []graphql.Field{
      {Name: "count"},
    },
  }).
  Do(ctx)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
result, err := jeopardy.Aggregate.OverAll(ctx, aggregate.OverAll{
  TotalCount: true,
})
if err != nil {
  // handle error
  panic(err)
}
if result.TotalCount != nil {
  fmt.Printf("object count: %d\n", *result.TotalCount)
}
```

**Java**

```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#**

```csharp
var jeopardy = client.Collections.Use("JeopardyQuestion");
var response = await jeopardy.Aggregate.OverAll(
    totalCount: true
);

Console.WriteLine(response.TotalCount);
```

**GraphQL**

```graphql
{
  Aggregate {
    JeopardyQuestion {
      meta {
        count
      }
    }
  }
}
```

**Example response**

The output is like this:

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

## Aggregate `text` properties

This example counts occurrence frequencies:

**Python**

```py
from weaviate.classes.query import Metrics

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.aggregate.over_all(
    return_metrics=Metrics("answer").text(
        top_occurrences_count=True,
        top_occurrences_value=True,
        limit=5  # Maximum number of top occurrences to return
    )
)

print(response.properties["answer"].top_occurrences)
```

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.aggregate.overAll({
  returnMetrics: jeopardy.metrics.aggregate('answer')
  .text(
    ['topOccurrencesValue', 'topOccurrencesOccurs'],
    5 // minOccurrences - threshold minimum count
  )
})

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

**Go (v5)**

```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)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
result, err := jeopardy.Aggregate.OverAll(ctx, aggregate.OverAll{
  Text: []aggregate.Text{
    {Property: "category", Count: true, TopOccurrences: true},
  },
})
if err != nil {
  // handle error
  panic(err)
}
category := result.Text["category"]
for _, occ := range category.TopOccurrences {
  fmt.Printf("%s occurs %d times\n", occ.Value, occ.OccursTimes)
}
```

**Java**

```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 here
System.out.println(response.properties().get("answer"));
```

**C#**

```csharp
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**

```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

This example shows aggregation with integers.

**Python**

```py
from weaviate.classes.query import Metrics

jeopardy = 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**

```ts
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));
```

**Go (v5)**

```go
response, err := client.GraphQL().Aggregate().
  WithClassName("JeopardyQuestion").
  WithFields(graphql.Field{
    Name: "points",
    Fields: []graphql.Field{
      {Name: "count"},
      {Name: "sum"},
    },
  }).
  Do(ctx)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
result, err := jeopardy.Aggregate.OverAll(ctx, aggregate.OverAll{
  Integer: []aggregate.Integer{
    {Property: "points", Count: true, Sum: true, Min: true, Max: true, Mean: true},
  },
})
if err != nil {
  // handle error
  panic(err)
}
points := result.Integer["points"]
if points.Sum != nil {
  fmt.Printf("total points: %d\n", *points.Sum)
}
```

**Java**

```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 here
System.out.println(response.properties().get("points"));
System.out.println(response.properties().get("points"));
System.out.println(response.properties().get("points"));
```

**C#**

```csharp
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**

```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

To group your results, use `groupBy` in the query.

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

**Python**

```py
from weaviate.classes.aggregate import GroupByAggregate

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.aggregate.over_all(
    group_by=GroupByAggregate(prop="round")
)

# print rounds names and the count for each
for group in response.groups:
    print(f"Value: {group.grouped_by.value} Count: {group.total_count}")
```

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

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

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

**Go (v5)**

```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)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
result, err := jeopardy.Aggregate.OverAll.GroupBy(ctx,
  aggregate.OverAll{
    Integer: []aggregate.Integer{
      {Property: "points", Count: true, Sum: true},
    },
  },
  aggregate.GroupBy{Property: "category", Limit: 10},
)
if err != nil {
  // handle error
  panic(err)
}
for _, group := range result.Groups {
  fmt.Printf("group %v\n", group.Value)
  if points := group.Integer["points"]; points.Count != nil {
    fmt.Printf("  count: %d\n", *points.Count)
  }
}
```

**Java**

```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 each
for (var group : response.groups()) {
  System.out.printf("Value: %s Count: %d\n", group.groupedBy().value(),
      group.totalCount());
}
```

**C#**

```csharp
var jeopardy = client.Collections.Use("JeopardyQuestion");
var response = await jeopardy.Aggregate.OverAll(
    groupBy: new Aggregate.GroupBy("round")
);

// print rounds names and the count for each
foreach (var group in response.Groups)
{
    Console.WriteLine($"Value: {group.GroupedBy.Value} Count: {group.TotalCount}");
}
```

**GraphQL**

```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
          }
        }
      ]
    }
  }
}
```

> [!NOTE]
>
> **`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.

## Aggregate with a `similarity search`

You can use `Aggregate` with a [similarity search](https://docs.weaviate.io/weaviate/search/similarity) operator (one of the `Near` operators).

You must limit the search space. Set `objectLimit`, or set a `distance` (or `certainty`) on the search operator. If you set neither, the request fails with `must provide certainty or objectLimit with vector search`.

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

**Python**

```py
from weaviate.classes.query import Metrics

jeopardy = 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**

```ts
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);
```

**Go (v5)**

```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)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
result, err := jeopardy.Aggregate.NearText(ctx, aggregate.NearText{
  Query: query.NearText{
    Concepts: []string{"animals in space"},
  },
  ObjectLimit: 10,
  Integer: []aggregate.Integer{
    {Property: "points", Sum: true},
  },
})
if err != nil {
  // handle error
  panic(err)
}
if sum := result.Integer["points"].Sum; sum != nil {
  fmt.Printf("%d\n", *sum)
}
```

**Java**

```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#**

```csharp
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**

```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`

Use `distance` to specify how similar the objects should be. A `distance` limits the search space, so a query that sets it does not also need an `objectLimit`.

**Python**

```py
from weaviate.classes.query import Metrics

jeopardy = 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**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

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

console.log(result.properties['points']);
```

**Go (v5)**

```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)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
result, err := jeopardy.Aggregate.NearText(ctx, aggregate.NearText{
  Query: query.NearText{
    Concepts: []string{"animals in space"},
    Similarity: query.Distance(0.19),
  },
  Integer: []aggregate.Integer{
    {Property: "points", Sum: true},
  },
})
if err != nil {
  // handle error
  panic(err)
}
if sum := result.Integer["points"].Sum; sum != nil {
  fmt.Printf("%d\n", *sum)
}
```

**Java**

```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#**

```csharp
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**

```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
          }
        }
      ]
    }
  }
}
```

## Aggregate with a `hybrid search`

You can use `Aggregate` with a [hybrid search](https://docs.weaviate.io/weaviate/search/hybrid) operator. As with a similarity search, you must limit the search space: set `objectLimit`, or bound the vector leg with `max vector distance` (`distance` argument for hybrid).

**Python**

```py
from weaviate.classes.query import Metrics, BM25Operator

jeopardy = 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**

```ts
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 (v5)**

```go
// Go client support coming soon
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
result, err := jeopardy.Aggregate.Hybrid(ctx, aggregate.Hybrid{
  Query: query.Hybrid{
    Query:             "animals in space",
    KeywordSimilarity: query.AllTokensMatch,
  },
  ObjectLimit: 10,
  Integer: []aggregate.Integer{
    {Property: "points", Sum: true},
  },
})
if err != nil {
  // handle error
  panic(err)
}
if sum := result.Integer["points"].Sum; sum != nil {
  fmt.Printf("%d\n", *sum)
}
```

**Java**

```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#**

```csharp
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**

```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

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

**Python**

```py
from weaviate.classes.query import Filter

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.aggregate.over_all(
    filters=Filter.by_property("round").equal("Final Jeopardy!"),
)

print(response.total_count)
```

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.aggregate.overAll({
  filters: jeopardy.filter.byProperty('round').equal('Final Jeopardy!')
})

console.log(JSON.stringify(result.totalCount, null, 2));
```

**Go (v5)**

```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)
```

**Go (v6)**

```go
// Coming soon
```

**Java**

```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#**

```csharp
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**

```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
          }
        }
      ]
    }
  }
}
```

## Related pages

- [Connect to Weaviate](https://docs.weaviate.io/weaviate/connections)
- [API References: GraphQL: Aggregate](https://docs.weaviate.io/weaviate/api/graphql/aggregate)