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/TypeScriptGoJava v6 (Beta)C# (Beta)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)

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/TypeScriptGoJava v6 (Beta)C# (Beta)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,
        min_occurrences=5  # Threshold minimum count
    )
)

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)

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(
    metrics: Metrics.ForProperty("answer")
        .Text(
            topOccurrencesCount: true,
            topOccurrencesValue: true,
            minOccurrences: 5 // Corresponds to topOccurrencesCutoff
        )
);

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/TypeScriptGoJava v6 (Beta)C# (Beta)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)

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)
    metrics: 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/TypeScriptGoJava v6 (Beta)C# (Beta)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)

CollectionHandle<Map<String, Object>> jeopardy = client.collections.use("JeopardyQuestion");
var response = jeopardy.aggregate.overAll(
    // TODO[g-despot] Why is metrics needed here?
    c -> c.metrics(),
    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 only works with near<Media> operators.
• 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).

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

PythonJavaScript/TypeScriptGoJava v6 (Beta)C# (Beta)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)

CollectionHandle<Map<String, Object>> jeopardy = client.collections.use("JeopardyQuestion");
var response = jeopardy.aggregate.nearText(
    "animals in space",
    a -> a
        .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.NearText(
    ["animals in space"],
    limit: 10,
    metrics: 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

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

Use distance to specify how similar the objects should be.

PythonJavaScript/TypeScriptGoJava v6 (Beta)C# (Beta)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)

CollectionHandle<Map<String, Object>> jeopardy = client.collections.use("JeopardyQuestion");
var response = jeopardy.aggregate.nearText(
  // TODO[g-despot] Should be distance instead of objectLimit
    "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,
    metrics: 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.

PythonJavaScript/TypeScriptGoJava v6 (Beta)C# (Beta)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)

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)

CollectionHandle<Map<String, Object>> jeopardy = client.collections.use("JeopardyQuestion");
var response = jeopardy.aggregate.hybrid(
    "animals in space",
    a -> a
        // TODO 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,
    metrics: 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/TypeScriptGoJava v6 (Beta)C# (Beta)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)

// 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
        // .where(Where.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").Equal("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

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.