Skip to main content

GraphQL API

LICENSE Weaviate on Stackoverflow badge Weaviate issues on Github badge Weaviate version badge Weaviate total Docker pulls badge Go Report Card

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.

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.

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.