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)

Python Client v3

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

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

JS/TS Client v3

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

const result = await jeopardy.aggregate.overAll()

console.log(result.totalCount);

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)

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)

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

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

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)

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)

Python Client v3

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

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

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)

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

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

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

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)

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

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

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

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)

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

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

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

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)

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

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

JS/TS Client v3

// TS client support coming soon

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)

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)

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

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

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)

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