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

Return the number of objects matched by the query.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#GraphQL

  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.

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

print(response.total_count)

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

const result = await jeopardy.aggregate.overAll()

console.log(result.totalCount);

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

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

CollectionHandle<Map<String, Object>> jeopardy =
    client.collections.use("JeopardyQuestion");
var response = jeopardy.aggregate.overAll(
    a -> a.includeTotalCount(true)
);

System.out.println(response.totalCount());

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

Console.WriteLine(response.TotalCount);

{
  Aggregate {
    JeopardyQuestion {
      meta {
        count
      }
    }
  }
}

Example response

The output is like this:

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

Aggregate text properties

This example counts occurrence frequencies:

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#GraphQL

  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.

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)

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

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)

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

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"));

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));
}

{
  Aggregate {
    JeopardyQuestion {
      answer {
        count
        type
        topOccurrences {
          occurs
          value
        }
      }
    }
  }
}

Example response

The output is like this:

{
  "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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#GraphQL

  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.

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)

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

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

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

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"));

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}");
}

{
  Aggregate {
    JeopardyQuestion {
      points {
        count
        sum
      }
    }
  }
}

Example response

The output is like this:

{
  "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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#GraphQL

  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.

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}")

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

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

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

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)

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

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());
}

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}");
}

{
  Aggregate {
    JeopardyQuestion(groupBy: "round") {
      groupedBy {
        value
      }
      meta {
        count
      }
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "groupedBy": {
            "value": "Double Jeopardy!"
          },
          "meta": {
            "count": 5193
          }
        },
        {
          "groupedBy": {
            "value": "Jeopardy!"
          },
          "meta": {
            "count": 4522
          }
        },
        {
          "groupedBy": {
            "value": "Final Jeopardy!"
          },
          "meta": {
            "count": 285
          }
        }
      ]
    }
  }
}

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

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#GraphQL

  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.

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

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

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)

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

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"));

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

{
  Aggregate {
    JeopardyQuestion(
      nearText: {
        concepts: ["animals in space"]
      }
      objectLimit: 10
    ) {
      points {
        sum
      }
    }
  }
}

Example response

The output is like this:

{
  "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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#GraphQL

  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.

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

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']);

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)

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

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"));

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

{
  Aggregate {
    JeopardyQuestion(
      nearText: {
        concepts: ["animals in space"]
        distance: 0.19
      }
    ) {
      points {
        sum
      }
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "points": {
            "sum": 2500
          }
        }
      ]
    }
  }
}

Aggregate with a hybrid search

You can use Aggregate with a hybrid search 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).

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#GraphQL

  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.

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

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 client support coming soon

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

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"));

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

{
  Aggregate {
    JeopardyQuestion(
      hybrid: {
        query: "animals in space"
        bm25SearchOperator: {
          operator: Or
          minimumOrTokensMatch: 2
        }
      }
      objectLimit: 10
    ) {
      points {
        sum
      }
    }
  }
}

Example response

The output is like this:

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

Filter results

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

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#GraphQL

  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.

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)

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

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

// Coming soon

// 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());

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

{
  Aggregate {
    JeopardyQuestion(where: {
      path: ["round"]
      operator: Equal
      valueText: "Final Jeopardy!"
    }) {
      meta {
        count
      }
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Aggregate": {
      "JeopardyQuestion": [
        {
          "meta": {
            "count": 285
          }
        }
      ]
    }
  }
}

Related pages

• Connect to Weaviate
• API References: GraphQL: Aggregate

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.