Skip to main content
Weaviate Docs (migrated from docs.weaviate.io) Docs

Search documentation

Type to search this documentation.

On this pageOverview

Aggregate

Overview

Section titled “Overview”

This page covers aggregation queries. They are collectively referred to as Aggregate queries within.

An Aggregate query can aggregate over an entire collection, or the results of a search.

Parameters

Section titled “Parameters”

An Aggregate query requires the target collection to be specified. Each query can include any of the following types of arguments:

Argument Description Required
Collection Also called "class". The object collection to be retrieved from. Yes
Properties Properties to be retrieved Yes
Conditional filters Filter the objects to be retrieved No
Search operators Specify the search strategy (e.g. near text, hybrid, bm25) No
Additional operators Specify additional operators (e.g. limit, offset, sort) No
Tenant name Specify the tenant name Yes, if multi-tenancy enabled. (Read more: what is multi-tenancy?)
Consistency level Specify the consistency level No

Available properties

Section titled “Available properties”

Each data type has its own set of available aggregated properties. The following table shows the available properties for each data type.

Data type Available properties
Text count, type, topOccurrences (value, occurs)
Number count, type, minimum, maximum, mean, median, mode, sum
Integer count, type, minimum, maximum, mean, median, mode, sum
Boolean count, type, totalTrue, totalFalse, percentageTrue, percentageFalse
Date count, type, minimum, maximum, mean, median, mode
See a GraphQL Aggregate format
GraphQL
{
  Aggregate {
    <Class> (groupBy:[<property>]) {
      groupedBy { # requires `groupBy` filter
          path
          value
      }
      meta {
        count
      }
      <propertyOfDatatypeText> {
          count
          type
          topOccurrences (limit: <n_minimum_count>) {
              value
              occurs
          }
      }
      <propertyOfDatatypeNumberOrInteger> {
          count
          type
          minimum
          maximum
          mean
          median
          mode
          sum
      }
      <propertyOfDatatypeBoolean> {
          count
          type
          totalTrue
          totalFalse
          percentageTrue
          percentageFalse
      }
      <propertyWithReference>
        pointingTo
        type
    }
  }
}

Below is an example query to obtain meta information about the Article collection. Note that the data is not grouped here, and results relate to all data objects in the Article collection.

Python
collection = client.collections.use("Article")
response = collection.aggregate.over_all(
    total_count=True,
    return_metrics=wvc.query.Metrics("wordCount").integer(
        count=True,
        maximum=True,
        mean=True,
        median=True,
        minimum=True,
        mode=True,
        sum_=True,
    ),
)

print(response.total_count)
print(response.properties)
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
  "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  title := graphql.Field{Name: "title"}
  url := graphql.Field{Name: "url"}
  wordCount := graphql.Field{
    Name: "wordCount", Fields: []graphql.Field{
      {Name: "mean"},
      {Name: "maximum"},
      {Name: "median"},
      {Name: "minimum"},
      {Name: "mode"},
      {Name: "sum"},
      {Name: "type"},
    },
  }
  inPublication := graphql.Field{
    Name: "inPublication", Fields: []graphql.Field{
      {Name: "pointingTo"},
      {Name: "count"},
    },
  }

  result, err := client.GraphQL().Aggregate().
    WithClassName("Article").
    WithFields(title, url, wordCount, inPublication).
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
Curl
echo '{
    "query": "{
      Aggregate {
        Article {
          meta {
            count
          }
          inPublication {
            pointingTo
            type
          }
          wordCount {
            count
            maximum
            mean
            median
            minimum
            mode
            sum
            type
          }
        }
      }
    }"
  }' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer learn-weaviate' \
    -d @- \
    https://edu-demo.weaviate.network/v1/graphql
GraphQL
{
  Aggregate {
    Article {
      meta {
        count
      }
      inPublication {
        pointingTo
        type
      }
      wordCount {
        count
        maximum
        mean
        median
        minimum
        mode
        sum
        type
      }
    }
  }
}

The above query will result in something like the following:

JSON
{
  "data": {
    "Aggregate": {
      "Article": [
        {
          "inPublication": {
            "pointingTo": [
              "Publication"
            ],
            "type": "cref"
          },
          "meta": {
            "count": 4403
          },
          "wordCount": {
            "count": 4403,
            "maximum": 16852,
            "mean": 966.0113558937088,
            "median": 680,
            "minimum": 109,
            "mode": 575,
            "sum": 4253348,
            "type": "int"
          }
        }
      ]
    }
  }
}

Get object count in collection

Section titled “Get object count in collection”

Use meta { count } to retrieve the total number of objects in a collection.

Python
collection = client.collections.use("Article")
response = collection.aggregate.over_all(total_count=True)

print(response.total_count)
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
  "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "WEAVIATE_INSTANCE_URL",  // Replace with your instance URL
    Scheme: "https",
  }
  client := weaviate.New(cfg)

  meta := graphql.Field{
    Name: "meta", Fields: []graphql.Field{
      {Name: "count"},
    },
  }

  result, err := client.GraphQL().Aggregate().
    WithClassName("<ClassName>").
    WithFields(meta).
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
Curl
echo '{
  "query": "{
    Aggregate {
      <ClassName> {
        meta {
          count
        }
      }
    }
  }"
}' | curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d @- \
  https://WEAVIATE_INSTANCE_URL/v1/graphql  # Replace WEAVIATE_INSTANCE_URL with your instance URL
GraphQL
{ Aggregate { <ClassName> { meta { count } } } }

groupBy argument

Section titled “groupBy argument”

You can use a groupBy argument to get meta information about groups of data objects, from those matching a query. The groups can be based on a property of the data objects.

The groupBy argument is structured as follows for the Aggregate function:

GraphQL
{
  Aggregate {
    <Class> ( groupBy: ["<propertyName>"] ) {
      groupedBy {
          path
          value
      }
      meta {
        count
      }
      <propertyName> {
        count
      }
    }
  }
}

In the following example, the articles are grouped by the property inPublication, referring to the article's publisher.

Python
from weaviate.classes.aggregate import GroupByAggregate
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
  "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {

  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }
  meta := graphql.Field{
    Name: "meta", Fields: []graphql.Field{
      {Name: "count"},
    },
  }
  wordCount := graphql.Field{
    Name: "wordCount", Fields: []graphql.Field{
      {Name: "mean"},
    },
  }
  groupedBy := graphql.Field{
    Name: "groupedBy", Fields: []graphql.Field{
      {Name: "value"},
      {Name: "path"},
    },
  }

  result, err := client.GraphQL().Aggregate().
    WithFields(meta, wordCount, groupedBy).
    WithClassName("Article").
    WithGroupBy("inPublication").
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
Curl
echo '{
  "query": "{
    Aggregate {
      Article(groupBy: [\"inPublication\"]) {
        meta {
          count
        }
        wordCount {
          mean
        }
        groupedBy {
          value
          path
        }
      }
    }
  }"
}' | curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer learn-weaviate' \
  -d @- \
  https://edu-demo.weaviate.network/v1/graphql
GraphQL
{
  Aggregate {
    Article (groupBy:["inPublication"]) {
      meta {
        count
      }
      wordCount {
        mean
      }
      groupedBy {
        value
        path
      }
    }
  }
}
Expected response
JSON
{
  "data": {
    "Aggregate": {
      "Article": [
        {
          "groupedBy": {
            "path": [
              "inPublication"
            ],
            "value": "weaviate://localhost/Publication/16476dca-59ce-395e-b896-050080120cd4"
          },
          "meta": {
            "count": 829
          },
          "wordCount": {
            "mean": 604.6537997587454
          }
        },
        {
          "groupedBy": {
            "path": [
              "inPublication"
            ],
            "value": "weaviate://localhost/Publication/c9a0e53b-93fe-38df-a6ea-4c8ff4501783"
          },
          "meta": {
            "count": 618
          },
          "wordCount": {
            "mean": 917.1860841423949
          }
        },
        ...
      ]
    }
  }
}

Additional filters

Section titled “Additional filters”

Aggregate functions can be extended with conditional filters read more.

topOccurrences property

Section titled “topOccurrences property”

Aggregating data makes the topOccurrences property available. Note that the counts are not dependent on tokenization. The topOccurrences count is based on occurrences of the entire property, or one of the values if the property is an array.

You can optionally specify a limit parameter to limit the returned objects. For example, limit: 5 will return the top 5 most frequent occurrences.

Consistency levels

Section titled “Consistency levels”

Multi-tenancy

Section titled “Multi-tenancy”

Where multi-tenancy is configured, the Aggregate function can be configured to aggregate results from a specific tenant.

You can do so by specifying the tenant parameter in the query as shown below, or in the client.

GraphQL
{
  Aggregate {
    Article (
      tenant: "tenantA"
    ) {
      meta {
        count
      }
    }
  }
}

Aggregating a Vector Search / Faceted Vector Search

Section titled “Aggregating a Vector Search / Faceted Vector Search”

You can combine a vector search (e.g. nearObject, nearVector, nearText, nearImage, etc.) with an aggregation. Internally, this is a two-step process where the vector search first finds the desired objects, then the results are aggregated.

Limiting the search space

Section titled “Limiting the search space”

Vector searches rank objects by similarity but do not exclude any objects. Thus, for a search operator to impact aggregation, you must limit the search space by setting either objectLimit or certainty for the query:

  • objectLimit, e.g. objectLimit: 100 tells Weaviate to aggregate the first 100 objects retrieved by the vector search query. This is useful when you know upfront how many results you want to serve, for example, in a recommendation scenario where you want to produce 100 recommendations.

  • certainty, e.g. certainty: 0.7 tells Weaviate to aggregate all vector search results with a certainty score of 0.7 or higher. This list has no fixed length, it depends on how many objects are good matches. This is useful in user-facing search scenarios, such as e-commerce. The user might be interested in all search results semantically similar to "apple iphone" and then generate facets.

The aggregation query will fail if neither objectLimit nor certainty is set.

Examples

Section titled “Examples”

Below are examples for nearObject, nearVector, and nearText. Any near<Media> will work.

nearObject

Section titled “nearObject”
Python
collection = client.collections.use("Article")
response = collection.aggregate.near_object(
    near_object="00037775-1432-35e5-bc59-443baaef7d80",
    distance=0.6,
    object_limit=200,
    total_count=True,
    return_metrics=[
        wvc.query.Metrics("wordCount").integer(
            count=True,
            maximum=True,
            mean=True,
            median=True,
            minimum=True,
            mode=True,
            sum_=True,
        ),
JavaScript/TypeScript
const collection = client.collections.use('JeopardyQuestion');const someObjects = await collection.query.fetchObjects({ limit: 1 });const objectId = someObjects.objects[0].uuid;const result = await collection.aggregate.nearObject(  objectId,  {    objectLimit: 200,    distance: 0.6,    returnMetrics: collection.metrics.aggregate('points')      .integer(['count', 'sum', 'maximum', 'minimum', 'mean', 'median', 'mode']),  })console.log(result.totalCount);console.log(JSON.stringify(result.properties, null, 2));
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
  "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  title := graphql.Field{Name: "title"}
  url := graphql.Field{Name: "url"}
  wordCount := graphql.Field{
    Name: "wordCount", Fields: []graphql.Field{
      {Name: "mean"},
      {Name: "maximum"},
      {Name: "median"},
      {Name: "minimum"},
      {Name: "mode"},
      {Name: "sum"},
      {Name: "type"},
    },
  }
  inPublication := graphql.Field{
    Name: "inPublication", Fields: []graphql.Field{
      {Name: "pointingTo"},
      {Name: "count"},
    },
  }

  // nearObject
  withNearObject := client.GraphQL().NearObjectArgBuilder().
    WithDistance(0.85). // At least one of distance or objectLimit need to be set
    WithID("00037775-1432-35e5-bc59-443baaef7d80")

  result, err := client.GraphQL().
    Aggregate().
    WithFields(title, url, wordCount, inPublication).
    WithNearObject(nearObject).
    WithClassName("Article").
    WithObjectLimit(100). // At least one of certainty or objectLimit need to be set
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
Curl
echo '{
    "query": "{
      Aggregate {
        Article(nearObject:{
          id: \"00037775-1432-35e5-bc59-443baaef7d80\"
          distance: 0.6
        },
        objectLimit: 200) {
          meta {
            count
          }
          inPublication {
            pointingTo
            type
          }
          wordCount {
            count
            maximum
            mean
            median
            minimum
            mode
            sum
            type
          }
        }
      }
    }"
  }' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer learn-weaviate' \
    -d @- \
    https://edu-demo.weaviate.network/v1/graphql
GraphQL
{
  Aggregate {
    Article(
      nearObject: {
        id: "00037775-1432-35e5-bc59-443baaef7d80"
        # prior to v1.14, use `certainty` instead of `distance`
        distance: 0.6
      },
      # at least one of "objectLimit" and/or "distance" must be set when using near<Media>
      objectLimit: 200
    ) {
      meta {
        count
      }
      inPublication {
        pointingTo
        type
      }
      wordCount {
        count
        maximum
        mean
        median
        minimum
        mode
        sum
        type
      }
    }
  }
}

nearVector

Section titled “nearVector”
Python
collection = client.collections.use("Article")
response = collection.aggregate.near_vector(
    near_vector=some_vector,
    distance=0.7,
    object_limit=100,
    total_count=True,
    return_metrics=[
        wvc.query.Metrics("wordCount").integer(
            count=True,
            maximum=True,
            mean=True,
            median=True,
            minimum=True,
            mode=True,
            sum_=True,
        ),
JavaScript/TypeScript
const collection = client.collections.use('JeopardyQuestion');const someObjects = await collection.query.fetchObjects({ limit: 1, includeVector: true });const someVector = someObjects.objects[0].vectors.default;const result = await collection.aggregate.nearVector(  someVector,  {    objectLimit: 200,    distance: 0.7,    returnMetrics: collection.metrics.aggregate('points')      .integer(['count', 'sum', 'maximum', 'minimum', 'mean', 'median', 'mode']),  })console.log(result.totalCount);console.log(JSON.stringify(result.properties, null, 2));
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
  "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  title := graphql.Field{Name: "title"}
  url := graphql.Field{Name: "url"}
  wordCount := graphql.Field{
    Name: "wordCount", Fields: []graphql.Field{
      {Name: "mean"},
      {Name: "maximum"},
      {Name: "median"},
      {Name: "minimum"},
      {Name: "mode"},
      {Name: "sum"},
      {Name: "type"},
    },
  }
  inPublication := graphql.Field{
    Name: "inPublication", Fields: []graphql.Field{
      {Name: "pointingTo"},
      {Name: "count"},
    },
  }

  // nearVector
  nearVector := &graphql.NearVectorArgumentBuilder{}
  nearVector.WithCertainty(0.85). // At least one of certainty or objectLimit need to be set
          WithVector([]float32{0.1, 0.2, -0.3})

  result, err := client.GraphQL().
    Aggregate().
    WithFields(title, url, wordCount, inPublication).
    WithNearVector(nearVector).
    WithClassName("Article").
    WithObjectLimit(100). // At least one of certainty or objectLimit need to be set
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
Curl
echo '{
    "query": "{
      Aggregate {
        Article(nearVector:{
          vector: [0.1, 0.2, -0.3]
          certainty: 0.7
        },
        objectLimit: 200) {
          meta {
            count
          }
          inPublication {
            pointingTo
            type
          }
          wordCount {
            count
            maximum
            mean
            median
            minimum
            mode
            sum
            type
          }
        }
      }
    }"
  }' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer learn-weaviate' \
    -d @- \
    https://edu-demo.weaviate.network/v1/graphql
GraphQL
{
  Aggregate {
    Article(nearVector:{
      vector: [0.1, 0.2, -0.3]
      certainty: 0.7       # at least one of "objectLimit",
    },                     # and/or "certainty" must be set
    objectLimit: 200) {    # when using near<Media>
      meta {
        count
      }
      inPublication {
        pointingTo
        type
      }
      wordCount {
        count
        maximum
        mean
        median
        minimum
        mode
        sum
        type
      }
    }
  }
}

nearText

Section titled “nearText”
Python
collection = client.collections.use("Article")
response = collection.aggregate.near_text(
    query="apple iphone",
    object_limit=200,
    total_count=True,
    return_metrics=[
        wvc.query.Metrics("wordCount").integer(
            count=True,
            maximum=True,
            mean=True,
            median=True,
            minimum=True,
            mode=True,
            sum_=True,
        ),
JavaScript/TypeScript
const jeopardy = client.collections.use('JeopardyQuestion');
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
  "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  title := graphql.Field{Name: "title"}
  url := graphql.Field{Name: "url"}
  wordCount := graphql.Field{
    Name: "wordCount", Fields: []graphql.Field{
      {Name: "mean"},
      {Name: "maximum"},
      {Name: "median"},
      {Name: "minimum"},
      {Name: "mode"},
      {Name: "sum"},
      {Name: "type"},
    },
  }
  inPublication := graphql.Field{
    Name: "inPublication", Fields: []graphql.Field{
      {Name: "pointingTo"},
      {Name: "count"},
    },
  }

  // nearText
  nearText := &graphql.NearTextArgumentBuilder{}
  nearText.WithDistance(0.85).  // prior to v1.14 use WithCertainty()
          WithConcepts([]string{"apple iphone"})

  result, err := client.GraphQL().
    Aggregate().
    WithFields(title, url, wordCount, inPublication).
    WithNearText(nearText).
    WithClassName("Article").
    WithObjectLimit(100). // at least one of distance or objectLimit need to be set
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
Curl
# See the notes from the GraphQL example
echo '{
    "query": "{
      Aggregate {
        Article(nearText:{
          concepts: [\"apple iphone\"]
          distance: 0.7
        },
        objectLimit: 200) {
          meta {
            count
          }
          inPublication {
            pointingTo
            type
          }
          wordCount {
            count
            maximum
            mean
            median
            minimum
            mode
            sum
            type
          }
        }
      }
    }"
  }' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer learn-weaviate' \
    -H "X-OpenAI-Api-Key: $OPENAI_API_KEY" \
    -d @- \
    https://edu-demo.weaviate.network/v1/graphql
GraphQL
{
  Aggregate {
    Article(nearText:{
      concepts: ["apple iphone"]
      distance: 0.7        # prior to v1.14 use "certainty" instead of "distance"
    },
    objectLimit: 200) {    # at least one of "objectLimit",
      meta {               # and/or "distance" must be set
        count              # when using near media filters
      }
      inPublication {
        pointingTo
        type
      }
      wordCount {
        count
        maximum
        mean
        median
        minimum
        mode
        sum
        type
      }
    }
  }
}

Questions and feedback

Section titled “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.

:::

Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu