Get{}

Weaviate on Stackoverflow badge Weaviate issues on Github badge Weaviate total Docker pulls badge

💡 You are looking at older or release candidate documentation. The current Weaviate version is v1.15.2

The Get{} function is Weaviate's bread and butter. It is the most direct way to access data. Especially if combined with filters, you can easily browse your Weaviate.


Get{} syntax and query structure

A Get{} function is always based on the schema. For example, if you’ve created a schema with a class Articles which has the properties name, url and wordCount, you can query it as follows:

  {
  Get {
    Article {
      title
      url
      wordCount
    }
  }
}
  import weaviate

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

result = client.query.get("Article", ["title", "url", "wordCount"]).do()
print(result)
  const weaviate = require("weaviate-client");

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

client.graphql
      .get()
      .withClassName('Article')
      .withFields('title url wordCount')
      .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)
  fields := []graphql.Field{
    {Name: "title"},
    {Name: "url"},
    {Name: "wordCount"},
  }
  ctx := context.Background()
  result, err := client.GraphQL().Get().
    WithClassName("Article").
    WithFields(fields...).
    Do(ctx)
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  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 title = Field.builder().name("title").build();
    Field url = Field.builder().name("url").build();
    Field wordCount = Field.builder().name("wordCount").build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Article")
      .withFields(title, url, wordCount)
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{ 
  "query": "{
    Get {
      Article {
        title
        url
        wordCount
      }
    }
  }"
}' | 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": {
    "Get": {
      "Article": [{
        "title": "“Joker” Is a Viewing Experience of Rare, Numbing Emptiness",
        "url": "https://www.newyorker.com/culture/the-front-row/joker-is-a-viewing-experience-of-rare-numbing-emptiness",
        "wordCount": 1794
      }]
    }
  }
}

Query beacon references

If you’ve set a beacon reference in the schema, you can query it as follows:

  {
  Get {
    Article {
      title
      url
      wordCount
      inPublication {           # the reference
        ... on Publication {    # you always set the destination class
          name                  # the property related to target class
        }
      }
    }
  }
}
  import weaviate

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

query = "{Get {Article {title url wordCount inPublication {... on Publication {name }}}}}"

result = client.query.raw(query)

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

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

client.graphql
      .get()
      .withClassName('Article')
      .withFields('title url wordCount inPublication {... on Publication {name}}')
      .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)
  ctx := context.Background()
  fields := []graphql.Field{
    {Name: "title"},
    {Name: "url"},
    {Name: "wordCount"},
    {Name: "inPublication", Fields: []graphql.Field{
      {Name: "... on Publication", Fields: []graphql.Field{
        {Name: "name"},
      }},
    }},
  }
  result, err := client.GraphQL().Get().
    WithClassName("Article").
    WithFields(fields...).
    Do(ctx)
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  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 title = Field.builder().name("title").build();
    Field url = Field.builder().name("url").build();
    Field wordCount = Field.builder().name("wordCount").build();
    Field inPublication = Field.builder()
      .name("inPublication")
      .fields(new Field[]{
        Field.builder()
          .name("... on Publication")
          .fields(new Field[]{
            Field.builder().name("name").build()
          })
          .build()
      })
      .build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Article")
      .withFields(title, url, wordCount, inPublication)
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{ 
    "query": "{
      Get {
        Article {
          title
          url
          wordCount
          inPublication {           
            ... on Publication {    
              name                  
            }
          }
        }
      }
    }"
  }' | 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": {
    "Get": {
      "Article": [{
        "title": "“Joker” Is a Viewing Experience of Rare, Numbing Emptiness",
        "url": "https://www.newyorker.com/culture/the-front-row/joker-is-a-viewing-experience-of-rare-numbing-emptiness",
        "wordCount": 1794,
        "inPublication": [
          {
            "name": "New Yorker"
          }
        ]
      }]
    }
  }
}

Additional properties

For every Get{} request you can get additional information about the returned data object(s) by using additional properties. You can recognize these properties because they are in the object _additional{}. Additional properties can help you interpret query results and can for example be used for projection and visualization of the retrieved data. An overview of all additional properties and how to use them is documented here.

Vector Search Operators

To combine Get { } with a vector search argument, here is an overview of the supported arguments and links to their detailed documentation:

ArgumentDescriptionRequired Modules (at least one of)Learn More
nearObjectFind the nearest neighbors of an object referenced by its idnone - works out of the boxLearn more
nearVectorFind the nearest neighbors to any vectornone - works out of the boxLearn more
nearTextVectorize a text query and perform a vector search based on ittext2vec-transformers, text2vec-contextionary, text2vec-openai, multi2vec-clipTransformers, Contextionary, OpenAI, CLIP
nearImageVectorize an image and perform a vector search based on itmulti2vec-clip, img2vec-neuralCLIP, Img2Vec

Filters

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

Sorting

Note: Support for sorting was added in v1.13.0.

You can sort results by any primitive property, typically a text, string, number, or int property. When aquery has a natural order (e.g. because of a near<Media> vector search), adding a sort operator will override the order.

Cost of Sorting / Architecture

Weaviate’s sorting implementation is built in a way that id does not lead to massive memory spikes, e.g. it does not need to load all objects to be sorted into memory completely. Only the property value being sorted is kept in memory.

When this feature was introduced (v1.13.0), Weaviate does have any datastructures on disk specific to sorting, such as a column-oriented storage mechanism. As a result when an object should be sorted, the whole object is identified on disk and the relevant property extracted. This works reasonably well for small scales (10s or 100s of thousand objects), but comes with a high cost at large lists of objects to be sorted (millions+). A column-oriented storage mechanism may be introduced in the future to overcome this performance limitation.

Sorting API

  {
  Get {
    Article(sort: [{
      path: ["title"]     # Path to the property that should be used
      order: asc          # Sort order, possible values: asc, desc 
    }]) {
      title
      url
      wordCount
    }
  }
}
  import weaviate

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

# one sorting configurations
result = (
  client.query
  .get("Article", ["title", "url", "wordCount"])
  .with_sort({ path: ["title"], order: "asc" })
  .do()
)
print(result)

# multiple sorting configurations
result = (
  client.query
  .get("Article", ["title", "url", "wordCount"])
  .with_sort([
    { path: ["title"], order: "asc" },
    { path: ["wordCount"], order: "desc" },
  ])
  .do()
)
print(result)

# or

result = (
  client.query
  .get("Article", ["title", "url", "wordCount"])
  .with_sort({ path: ["title"], order: "asc" })
  .with_sort({ path: ["wordCount"], order: "desc" })
  .do()
)
print(result)
  const weaviate = require("weaviate-client");

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

client.graphql
      .get()
      .withClassName('Article')
      .withSort([{ path: ["title"], order: "asc" }])
      .withFields('title url wordCount')
      .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"}

  byTitleAsc := graphql.Sort{
    Path: []string{"title"}, Order: graphql.Asc,
  }

  ctx := context.Background()
  result, err := client.GraphQL().Get().
    WithClassName("Article").
    WithSort(byTitleAsc).
    WithFields(title, url, wordCount).
    Do(ctx)
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  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.SortArgument;
import technology.semi.weaviate.client.v1.graphql.query.argument.SortOrder;
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 title = Field.builder().name("title").build();
    Field url = Field.builder().name("url").build();
    Field wordCount = Field.builder().name("wordCount").build();

    SortArgument byTitleAsc = client.graphQL().arguments().sortArgBuilder()
      .path(new String[]{ "title" })
      .order(SortOrder.asc)
      .build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Article")
      .withSort(byTitleAsc)
      .withFields(title, url, wordCount)
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{ 
  "query": "{
    Get {
      Article(sort: [{
        path: [\"title\"]
        order: asc
      }]) {
        title
        url
        wordCount
      }
    }
  }"
}' | 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:

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