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.

Python Client v4

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

print(response.total_count)

  API docs

Python Client v3

response = (
    client.query
    .aggregate("JeopardyQuestion")
    .with_meta_count()
    .do()
)

print(json.dumps(response, indent=2))

  API docs  Deprecated (v3)

JS/TS Client v3

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

const result = await jeopardy.aggregate.overAll()

console.log(result.totalCount);

  API docs

JS/TS Client v2

result = await client
  .graphql
  .aggregate()
  .withClassName('JeopardyQuestion')
  .withFields('meta { count }')
  .do();

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

Go

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

  API docs

GraphQL

{
  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 in the question property:

Python Client v4

from weaviate.classes.query import Metrics

jeopardy = client.collections.get("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)

  API docs

Python Client v3

response = (
    client.query
    .aggregate("JeopardyQuestion")
    .with_fields("answer { count type topOccurrences (limit: 5) { occurs value } }")  # `limit` here sets a minimum count threshold
    .do()
)

print(json.dumps(response, indent=2))

  API docs  Deprecated (v3)

JS/TS Client v3

const jeopardy = client.collections.get('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));

  API docs

JS/TS Client v2

result = await client
  .graphql
  .aggregate()
  .withClassName('JeopardyQuestion')
  .withFields('answer { count type topOccurrences { occurs value } }')
  .do();

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

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)

  API docs

GraphQL

{
  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 sums the points property.

Python Client v4

from weaviate.classes.query import Metrics

jeopardy = client.collections.get("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)

  API docs

Python Client v3

response = (
    client.query
    .aggregate("JeopardyQuestion")
    .with_fields("points { count sum }")
    .do()
)
print(json.dumps(response, indent=2))

  API docs  Deprecated (v3)

JS/TS Client v3

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

const result = await jeopardy.aggregate.overAll({
  returnMetrics: jeopardy.metrics.aggregate('points')
  .integer(['sum','maximum','minimum'])
})

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

  API docs

JS/TS Client v2

result = await client
  .graphql
  .aggregate()
  .withClassName('JeopardyQuestion')
  .withFields('points { count sum }')
  .do();

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

Go

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

  API docs

GraphQL

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

Python Client v4

from weaviate.classes.aggregate import GroupByAggregate

jeopardy = client.collections.get("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}")

  API docs

Python Client v3

response = (
    client.query
    .aggregate("JeopardyQuestion")
    .with_group_by_filter(["round"])
    .with_fields("groupedBy { value }")
    .with_meta_count()
    .do()
)
print(json.dumps(response, indent=2))

  API docs  Deprecated (v3)

JS/TS Client v3

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

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

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

  API docs

JS/TS Client v2

result = await client
  .graphql
  .aggregate()
  .withClassName('JeopardyQuestion')
  .withGroupBy(['round'])
  .withFields('groupedBy { value } meta { count }')
  .do();

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

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)

  API docs

GraphQL

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

Python Client v4

from weaviate.classes.query import Metrics

jeopardy = client.collections.get("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_)

  API docs

Python Client v3

response = (
    client.query
    .aggregate("JeopardyQuestion")
    .with_near_text({
        "concepts": ["animals in space"]
    })
    .with_object_limit(10)
    .with_fields("points { sum }")
    .do()
)
print(json.dumps(response, indent=2))

  API docs  Deprecated (v3)

JS/TS Client v3

const jeopardy = client.collections.get('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);

  API docs

JS/TS Client v2

result = await client
  .graphql
  .aggregate()
  .withClassName('JeopardyQuestion')
  .withNearText({
    concepts: ['animals in space'],
  })
  .withObjectLimit(10)
  .withFields('points { sum }')
  .do();

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

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)

  API docs

GraphQL

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

Python Client v4

from weaviate.classes.query import Metrics

jeopardy = client.collections.get("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_)

  API docs

Python Client v3

response = (
    client.query
    .aggregate("JeopardyQuestion")
    .with_near_text({
        "concepts": ["animals in space"],
        "distance": 0.19
    })
    .with_fields("points { sum }")
    .do()
)

print(json.dumps(response, indent=2))

  API docs  Deprecated (v3)

JS/TS Client v3

const jeopardy = client.collections.get('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']);

  API docs

JS/TS Client v2

result = await client
  .graphql
  .aggregate()
  .withClassName('JeopardyQuestion')
  .withNearText({
    concepts: ['animals in space'],
    distance: 0.19,
  })
  .withFields('points { sum }')
  .do();

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

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)

  API docs

GraphQL

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

Python Client v4

from weaviate.classes.query import Metrics

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.aggregate.hybrid(
    query="animals in space",
    object_limit=10,
    return_metrics=Metrics("points").number(sum_=True),
)

print(response.properties["points"].sum_)

  API docs

Python Client v3

response = (
    client.query
    .aggregate("JeopardyQuestion")
    .with_hybrid({
        "query": "animals in space"
    })
    .with_object_limit(10)
    .with_fields("points { sum }")
    .do()
)
print(json.dumps(response, indent=2))

  API docs  Deprecated (v3)

JS/TS Client v3

const jeopardy = client.collections.get("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)

  API docs

JS/TS Client v2

result = await client
  .graphql
  .aggregate()
  .withClassName('JeopardyQuestion')
  .withNearText({
    concepts: ['animals in space'],
  })
  .withObjectLimit(10)
  .withFields('points { sum }')
  .do();

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

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)

  API docs

GraphQL

{
  Aggregate {
    JeopardyQuestion(
      hybrid: {
        query: "animals in space"
      }
      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.

Python Client v4

from weaviate.classes.query import Filter

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

print(response.total_count)

  API docs

Python Client v3

response = (
    client.query
    .aggregate("JeopardyQuestion")
    .with_where({
        "path": ["round"],
        "operator": "Equal",
        "valueText": "Final Jeopardy!"
    })
    .with_meta_count()
    .do()
)

print(json.dumps(response, indent=2))

  API docs  Deprecated (v3)

JS/TS Client v3

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

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

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

  API docs

JS/TS Client v2

result = await client
  .graphql
  .aggregate()
  .withClassName('JeopardyQuestion')
  .withWhere({
    path: ['round'],
    operator: 'Equal',
    valueText: 'Final Jeopardy!',
  })
  .withFields('meta { count }')
  .do();

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

Go

// Add this line to imports: "github.com/weaviate/weaviate-go-client/v4/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)

  API docs

GraphQL

{
  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
• Documentation feedback