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

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

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

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

PythonGoJavaCurlGraphQL

  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.

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

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

finally:
    client.close()

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

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);
    Field meta = Field.builder()
      .name("meta")
      .fields(new Field[]{
        Field.builder().name("count").build()
      }).build();
    Field wordCount = Field.builder()
      .name("wordCount")
      .fields(new Field[]{
        Field.builder().name("mean").build(),
        Field.builder().name("maximum").build(),
        Field.builder().name("median").build(),
        Field.builder().name("minimum").build(),
        Field.builder().name("mode").build(),
        Field.builder().name("sum").build(),
        Field.builder().name("type").build()
      }).build();
    Field inPublication = Field.builder()
      .name("inPublication")
      .fields(new Field[]{
        Field.builder().name("pointingTo").build(),
        Field.builder().name("count").build()
      }).build();
    Result<GraphQLResponse> result = client.graphQL().aggregate()
      .withClassName("Article")
      .withFields(meta, wordCount, inPublication)
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

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

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

{
  "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"
          }
        }
      ]
    }
  }
}

meta { count } will return the query object count

As such, this Aggregate query will retrieve the total object count in a class.

PythonGoJavaCurlGraphQL

  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.

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

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

    print(response.total_count)

finally:
    client.close()

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

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("https", "WEAVIATE_INSTANCE_URL");
    // Replace with your instance URL

    WeaviateClient client = new WeaviateClient(config);
    Field meta = Field.builder()
      .name("meta")
      .fields(new Field[]{
        Field.builder().name("count").build()
      }).build();
    Result<GraphQLResponse> result = client.graphQL().aggregate()
      .withClassName(<ClassName>)
      .withFields(meta)
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

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

{ Aggregate { <ClassName> { meta { count } } } }

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.

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.

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

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

PythonGoJavaCurlGraphQL

  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.

import weaviate
import weaviate.classes as wvc
import os
from weaviate.classes.aggregate import GroupByAggregate

client = weaviate.connect_to_local()

try:
    # Coming soon

finally:
    client.close()

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

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);
    Field meta = Field.builder()
      .name("meta")
      .fields(new Field[]{
        Field.builder().name("count").build()
      }).build();
    Field wordCount = Field.builder()
      .name("wordCount")
      .fields(new Field[]{
        Field.builder().name("mean").build()
      }).build();
    Field groupedBy = Field.builder()
      .name("groupedBy")
      .fields(new Field[]{
        Field.builder().name("value").build(),
        Field.builder().name("path").build()
      }).build();

    Result<GraphQLResponse> result = client.graphQL().aggregate()
      .withClassName("Article")
      .withFields(meta, wordCount, groupedBy)
      .withGroupBy("inPublication")
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

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

{
  Aggregate {
    Article (groupBy:["inPublication"]) {
      meta {
        count
      }
      wordCount {
        mean
      }
      groupedBy {
        value
        path
      }
    }
  }
}

Expected response

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

Aggregate functions can be extended with conditional filters read more.

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

Not available with Aggregate

Aggregate queries are currently not available with different consistency levels.

Multi-tenancy

Added in v1.20

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.

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

See HOW-TO guide

For more information on using multi-tenancy, see the Multi-tenancy operations guide.

Aggregating a Vector Search / Faceted Vector Search

note

This feature was added in v1.13.0

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

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

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

nearObject

PythonGoJavaCurlGraphQL

  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.

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
    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,
            ),
        ]
    )

    print(response.total_count)
    print(response.properties)

finally:
    client.close()

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

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.argument.NearObjectArgument;
import io.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);
    Field meta = Field.builder()
      .name("meta")
      .fields(new Field[]{
        Field.builder().name("count").build()
      }).build();
    Field wordCount = Field.builder()
      .name("wordCount")
      .fields(new Field[]{
        Field.builder().name("mean").build(),
        Field.builder().name("maximum").build(),
        Field.builder().name("median").build(),
        Field.builder().name("minimum").build(),
        Field.builder().name("mode").build(),
        Field.builder().name("sum").build(),
        Field.builder().name("type").build()
      }).build();
    Field inPublication = Field.builder()
      .name("inPublication")
      .fields(new Field[]{
        Field.builder().name("pointingTo").build(),
        Field.builder().name("count").build()
      }).build();

    NearObjectArgument nearObject = NearObjectArgument.builder()
      // prior to v1.14 use certainty instead of distance
      .distance(0.6f) // at least one of certainty or objectLimit need to be set
      .id("00037775-1432-35e5-bc59-443baaef7d80")
      .build();

    Result<GraphQLResponse> result = client.graphQL().aggregate()
      .withClassName("Article")
      .withFields(meta, wordCount, inPublication)
      .withNearObject(nearObject)
      .withObjectLimit(100) // at least one of certainty or objectLimit need to be set
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

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

{
  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

Replace placeholder vector

To run this query, replace the placeholder vector with a real vector from the same vectorizer that used to generate object vectors.

PythonGoJavaCurlGraphQL

  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.

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
    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,
            ),
        ]
    )

    print(response.total_count)
    print(response.properties)

finally:
    client.close()

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

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.argument.NearVectorArgument;
import io.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);
    Field meta = Field.builder()
      .name("meta")
      .fields(new Field[]{
        Field.builder().name("count").build()
      }).build();
    Field wordCount = Field.builder()
      .name("wordCount")
      .fields(new Field[]{
        Field.builder().name("mean").build(),
        Field.builder().name("maximum").build(),
        Field.builder().name("median").build(),
        Field.builder().name("minimum").build(),
        Field.builder().name("mode").build(),
        Field.builder().name("sum").build(),
        Field.builder().name("type").build()
      }).build();
    Field inPublication = Field.builder()
      .name("inPublication")
      .fields(new Field[]{
        Field.builder().name("pointingTo").build(),
        Field.builder().name("count").build()
      }).build();

    Float[] vector = new Float[]{ 1.0f, 2.0f, -3.0f };
    NearVectorArgument nearVector = NearVectorArgument.builder()
      .certainty(0.7f) // at least one of certainty or objectLimit need to be set
      .vector(vector)
      .build();

    Result<GraphQLResponse> result = client.graphQL().aggregate()
      .withClassName("Article")
      .withFields(meta, wordCount, inPublication)
      .withNearVector(nearVector)
      .withObjectLimit(100) // at least one of certainty or objectLimit need to be set
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

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

{
  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

note

For nearText to be available, a text2vec-* module must be installed with Weaviate.

PythonGoJavaCurlGraphQL

  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.

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
    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,
            ),
        ]
    )

    print(response.total_count)
    print(response.properties)

finally:
    client.close()

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

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import io.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);
    Field meta = Field.builder()
      .name("meta")
      .fields(new Field[]{
        Field.builder().name("count").build()
      }).build();
    Field wordCount = Field.builder()
      .name("wordCount")
      .fields(new Field[]{
        Field.builder().name("mean").build(),
        Field.builder().name("maximum").build(),
        Field.builder().name("median").build(),
        Field.builder().name("minimum").build(),
        Field.builder().name("mode").build(),
        Field.builder().name("sum").build(),
        Field.builder().name("type").build()
      }).build();
    Field inPublication = Field.builder()
      .name("inPublication")
      .fields(new Field[]{
        Field.builder().name("pointingTo").build(),
        Field.builder().name("count").build()
      }).build();

    NearTextArgument nearText = NearTextArgument.builder()
      .distance(0.7f)  // prior to v1.14 use .certainty()
      .concepts(new String[]{ "pizza" })
      .build();

    Result<GraphQLResponse> result = client.graphQL().aggregate()
      .withClassName("Article")
      .withFields(meta, wordCount, inPublication)
      .withNearText(nearText)
      .withObjectLimit(100) // at least one of distance or objectLimit need to be set
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

# 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

{
  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

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.