Aggregate{}

You can use Weaviate's Aggregation{} function to obtain meta information about collections of data. Meta information can be queried over all objects in a class or by groups in a class.

Aggregate{} syntax and query structure

This example shows how to aggregate over the entire database. Below you will find examples of how to dynamically retrieve objects using a vector search and then aggregating only the matches. The Aggregate{} function is structured as follows:

{
  Aggregate {
    <Class> (groupBy:[<property>]) { 
      groupedBy { # requires `groupBy` filter
          path
          value
      }
      meta {
        count
      }
      <propertyOfDatatypeString> {
          count
          type
          topOccurrences {
              value
              occurs
          }
      }
      <propertyOfDatatypeText> {
          count
          type
          topOccurrences {
              value
              occurs
          }
      }
      <propertyOfDatatypeNumberOrInteger> {
          count
          type
          minimum
          maximum
          mean
          median
          mode
          sum
      }
      <propertyOfDatatypeBoolean> {
          count
          type
          totalTrue
          totalFalse
          percentageTrue
          percentageFalse
      }
      <propertyWithReference>
        pointingTo
        type
    }
  }
}

An example query to obtain meta information about the data in the class Article can be queried as follows. Note that the data is not grouped yet, the meta information is about all the data objects found with the class Article.

GraphQL

  {
  Aggregate {
    Article {
      meta {
        count
      }
      inPublication {
        pointingTo
        type
      }
      wordCount {
        count
        maximum
        mean
        median
        minimum
        mode
        sum
        type
      }
    }
  }
}

Python

  import weaviate

client = weaviate.Client("http://localhost:8080")

result = client.query.aggregate("Article") \
    .with_fields('meta { count }') \
    .with_fields("wordCount {count maximum mean median minimum mode sum type}") \
    .do()

Javascript

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .aggregate()
      .withClassName('Article')
      .withFields('meta { count } wordCount {count maximum mean median minimum mode sum type}')
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

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

Java

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.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());
  }
}

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' \
    -d @- \
    http://localhost:8080/v1/graphql

🟢 Click here to try out this graphql example in the Weaviate Console.

The above query will result in something like the following:

{
  "data": {
    "Aggregate": {
      "Article": [
        {
          "inPublication": {
            "pointingTo": [
              "Publication"
            ],
            "type": "cref"
          },
          "meta": {
            "count": 1873
          },
          "wordCount": {
            "count": 1873,
            "maximum": 16585,
            "mean": 1131.15056,
            "median": 826.29351,
            "minimum": 221,
            "mode": 636,
            "sum": 2118645,
            "type": "int"
          }
        }
      ]
    }
  },
  "errors": null
}

GroupBy Argument

You can use a groupBy argument to get meta information about groups of data objects.

The groupBy{} argument is structured as follows for the Get{} function:

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

In the following example, the articles are grouped by the property isAccessible, where one group contains accessible articles, and the second group contains articles of which the isAccessible property is set to False.

GraphQL

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

Python

  import weaviate

client = weaviate.Client("http://localhost:8080")

result = client.query.aggregate("Article") \
    .with_group_by_filter(["isAccessible"]) \
    .with_fields('meta { count }') \
    .with_fields("wordCount {count maximum mean median minimum mode sum type}") \
    .do()

print(result)

Javascript

  // this query currently gives an inconsistent result from a plain graphql query, see https://github.com/semi-technologies/weaviate-javascript-client/issues/8

const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .aggregate()
      .withClassName('Article')
      .withGroupBy(["isAccessible"])
      .withFields('meta { count } wordCount {mean} groupedBy {value path}')
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {

  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)
  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("isAccessible").
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}

Java

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.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("isAccessible")
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

curl

  $ echo '{ 
  "query": "{
    Aggregate {
      Article(groupBy: [\"isAccessible\"]) {
        meta {
          count
        }
        wordCount {
          mean
        }
        groupedBy {
          value
          path
        }
      }
    }
  }"
}' | curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d @- \
  http://localhost:8080/v1/graphql

🟢 Click here to try out this graphql example in the Weaviate Console.

The above query will result in something like the following:

{
  "data": {
    "Aggregate": {
      "Article": [
        {
          "groupedBy": {
            "path": [
              "isAccessible"
            ],
            "value": "True"
          },
          "meta": {
            "count": 1523
          },
          "wordCount": {
            "mean": 636
          }
        },
        {
          "groupedBy": {
            "path": [
              "isAccessible"
            ],
            "value":"False"
          },
          "meta": {
            "count": 350
          },
          "wordCount": {
            "mean": 462
          }
        }
      ]
    }
  },
  "errors": null
}

Additional filters

Aggregate{} functions can be extended with search filters. Because the filters work on multiple core functions (like Get{}) there is a specific documentation page dedicated to filters.

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 are different from keyword based searches in the sense that they do not filter the result set, they just re-order them. Imagine having 1,000 objects and a vector search for "apple iphone". If there was no explicit limit every single object in the database would be a potential match. Some matches would have a very high score (certainty), the last matches would most likely have a very low score. But nevertheless all 1,000 objects could potentially be scored. The value in this search is in the order. If we only look at the top 10 results they will be very closely related to the query vector. Similarly the last 10 objects on the list would be very unrelated. However, the order is not visible within an aggregation.

As a result, whenever the goal is to aggregate vector search results, there needs to be something that limits that the search space. Otherwise the Aggregation results (over all matches) will look exactly like an Aggregation without any additional near<Media> parameter.

You can achieve such a restriction of the search space in two different ways:

Set an explicit objectLimit, e.g. objectLimit: 100. This tells Weaviate to retrieve the top 100 objects related to your vector search query, then aggregate them. This is useful when you know up front how many results you want to serve, for example in a recommendation scenario, where you want to produce 100 recommendations.
Set an explicit certainty, e.g. certainty: 0.7. This tells Weaviate to retrieve all possible matches that have a certainty of 0.7 or higher. This list has no fixed length, it depends on how many objects were 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.

If neither an objectLimit, nor a certainty is set the query will error.

API

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

nearObject

GraphQL

  {
  Aggregate {
    Article(nearObject:{
      id: "9199ee38-b0db-4800-b146-dea8cfc62351"
                           # prior to v1.14 use certainty: 0.7, 
                           # instead of distance
      distance: 0.6        # at least one of "objectLimit", 
    },                     # and/or "distance" must be set
    objectLimit: 200) {    # when using near<Media>
      meta {
        count
      }
      inPublication {
        pointingTo
        type
      }
      wordCount {
        count
        maximum
        mean
        median
        minimum
        mode
        sum
        type
      }
    }
  }
}

Python

  import weaviate

client = weaviate.Client('http://localhost:8080')

result = (
  client.query
  .aggregate('Article')
  .with_meta_count()
  .with_fields('wordCount {count maximum mean median minimum mode sum type} inPublication {pointingTo type}')
  .with_near_object({'id': '9199ee38-b0db-4800-b146-dea8cfc62351', 'distance': 0.6}) # prior to v1.14 use certainty instead of distance
  .with_object_limit(200)
  .do()
)

print(result)

Javascript

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .aggregate()
      .withClassName('Article')
      .withFields('meta { count } wordCount {count maximum mean median minimum mode sum type}')
      .withNearObject({ id: "abefd256-8574-442b-9293-9205193737ee", distance: 0.6 }) # prior to v1.14 use certainty instead of distance
      .withObjectLimit(100)
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  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("9ac36e33-6611-4fb3-bade-4b1e409c6564")

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

Java

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearObjectArgument;
import technology.semi.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("9199ee38-b0db-4800-b146-dea8cfc62351")
      .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());
  }
}

curl

  $ echo '{ 
    "query": "{
      Aggregate {
        Article(nearObject:{
          id: "9199ee38-b0db-4800-b146-dea8cfc62351"
          distance: 0.6 # prior to v1.14 use certainty instead
        },
        objectLimit: 200) {
          meta {
            count
          }
          inPublication {
            pointingTo
            type
          }
          wordCount {
            count
            maximum
            mean
            median
            minimum
            mode
            sum
            type
          }
        }
      }
    }"
  }' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

🟢 Click here to try out this graphql example in the Weaviate Console.

nearVector

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

Python

  import weaviate

client = weaviate.Client('http://localhost:8080')

result = (
  client.query
  .aggregate('Article')
  .with_meta_count()
  .with_fields('wordCount {count maximum mean median minimum mode sum type}')
  .with_near_vector({'vector': [0.1, 0.2, -0.3], 'certainty': 0.7})
  .with_object_limit(100)
  .do()
)

print(result)

Javascript

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .aggregate()
      .withClassName('Article')
      .withFields('meta { count } wordCount {count maximum mean median minimum mode sum type}')
      .withNearVector({ vector: [0.1, 0.2, -0.3], certainty: 0.7 })
      .withObjectLimit(100)
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

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

Java

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearVectorArgument;
import technology.semi.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());
  }
}

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' \
    -d @- \
    http://localhost:8080/v1/graphql

🟢 Click here to try out this graphql example in the Weaviate Console.

nearText

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

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

Python

  import weaviate

client = weaviate.Client('http://localhost:8080')

result = (
  client.query
  .aggregate('Article')
  .with_meta_count()
  .with_fields('wordCount {count maximum mean median minimum mode sum type} inPublication {pointingTo type}')
  .with_near_text({'concepts': ["apple iphone"], 'distance': 0.7})  # prior to v1.14 use "certainty" instead of "distance"
  .with_object_limit(200)  # at least one of "objectLimit", 
  .do()                    # and/or "distance" must be set
)                          # when using near media filters

print(result)

Javascript

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .aggregate()
      .withClassName('Article')
      .withFields('meta { count } wordCount {count maximum mean median minimum mode sum type}')
      .withNearText({ concepts: ["apple iphone"], distance: 0.7 })  // prior to v1.14 use "certainty" 
      .withObjectLimit(100)                                         // instead of "distance".`
      .do()                                                         // at least one of "objectLimit",
      .then(res => {                                                // and/or "distance" must be set
        console.log(res)                                            // when using near media filters
      })
      .catch(err => {
        console.error(err)
      });

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

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

Java

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import technology.semi.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());
  }
}

curl

  $ echo '{ 
    "query": "{
      Aggregate {
        Article(nearText:{
          concepts: ["apple iphone"]
          distance: 0.7 // prior to v1.14 use "certainty"
        },
        objectLimit: 200) {
          meta {
            count
          }
          inPublication {
            pointingTo
            type
          }
          wordCount {
            count
            maximum
            mean
            median
            minimum
            mode
            sum
            type
          }
        }
      }
    }"
  }' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

🟢 Click here to try out this graphql example in the Weaviate Console.

More Resources

If you can’t find the answer to your question here, please look at the:

Frequently Asked Questions. Or,
Knowledge base of old issues. Or,
For questions: Stackoverflow. Or,
For issues: Github. Or,
Ask your question in the Slack channel: Slack.

Edit on Github

Aggregate{} syntax and query structure
- GroupBy Argument
- Additional filters
Aggregating a Vector Search / Faceted Vector Search
- Limiting the search space
- API
More Resources

weaviate

Getting started

Architecture

Configuration

Vector Index (ANN) Plugins

Benchmarks

Modules

Retrievers & Vectorizers

Readers & Generators

Other Modules

Client libraries & CLI

Data schema

RESTful API references

GraphQL references

More resources

Tutorials

Aggregate{}

Aggregate{} syntax and query structure

GroupBy Argument

Additional filters

Aggregating a Vector Search / Faceted Vector Search

Limiting the search space

API

nearObject

nearVector

nearText

More Resources

Table of Contents

Weaviate Cluster Service

Products

Integrations

More resources?

Meetups

All Resources

Blog

Podcast

Newsletter

Documentation

Contributor Guide

Weaviate Cloud Service

Github

Slack

weaviate

Retrievers & Vectorizers

Readers & Generators

Other Modules

Aggregate{}

Aggregate{} syntax and query structure

GroupBy Argument

Additional filters

Aggregating a Vector Search / Faceted Vector Search

Limiting the search space

API

nearObject

nearVector

nearText

More Resources

Table of Contents