Skip to main content

GraphQL API

GraphQL​

Weaviate's basic query language is GraphQL. GraphQL is a query language built on using graph data structures. It is an efficient method of data retrieval and mutation, since it mitigates the common over-fetching and under-fetching problems of other query languages.

GraphQL is case-sensitive

GraphQL is case-sensitive (reference), so make sure to use the correct casing when writing your queries.

All references​

All references have their individual subpages. Click on one of the references below for more information.

Query structure​

You can query Weaviate for semantic kinds based on standard GraphQL queries. The examples below only contain the GraphQL query. You can POST a GraphQL query to Weaviate as follows:

curl http://localhost/v1/graphql -X POST -H 'Content-type: application/json' -d '{GraphQL query}'

A GraphQL JSON object is defined as:

{
    "query": "{ # GRAPHQL QUERY }"
}

GraphQL queries follows a defined structure, defined to interact with your data in Weaviate as good as possible. Queries are structured as follows:

{
  <Function> {
      <Class> {
        <property>
        _<underscore-property>
      }
  }
}
  • There are three functions currently defined in Weaviate's GraphQL: Get{}, Aggregate{} and Explore{}. Get{} functions are used to easily retrieve data from your Weaviate instance, while Aggregate{} is used to obtain meta information about data objects and its properties. With Explore{} you can browse through the data to with semantic search, and a slightly different query structure than above is used (there is no <className> defined, since you are searching in a fuzzy way):
{
  Explore (<search arguments>) {
      beacon
      certainty
      className
  }
}
  • Class is the name of the class you want to fetch, defined in the schema.
  • With including a property (lowercase) list in the query, you specify exactly which property values you want to return. If the property is a reference to another object (beacon), then use the following structure:
{
  <Function> {
    <Class> {
      <property>
      <propertyWithReference>
        ... on <ClassOfBeacon> {
          <property>
          _additional {
            <additionalProperty>
          }
        }
      _additional {
        <additionalProperty>
      }
    }
  }
}
  • To obtain meta information about a data object (for example for interpretation or visualization purposes), use an additional property.

Limitations​

GraphQL integer data currently only supports int32, and does not support int64. This means that currently integer data fields in Weaviate with integer values larger than int32, will not be returned using GraphQL queries. We are working on solving this issue. As current workaround is to use a string instead.

Consistency level​

GraphQL (Get) queries are run with a tunable consistency level.