Skip to main content

Search (GraphQL | gRPC)

API

Weaviate offers GraphQL and gRPC APIs for queries.

We recommend using a Weaviate client library, which abstracts away the underlying API calls and makes it easier to integrate Weaviate into your application.

However, you can query Weaviate directly using GraphQL with a POST request to the /graphql endpoint, or write your own gRPC calls based on the gRPC protobuf specification.

All references

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

GraphQL API

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

Query structure

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 follow a defined structure. Queries are structured as follows:

{
<Function> {
<Collection> {
<property>
_<underscore-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.

gRPC API

Starting with Weaviate v1.19.0, a gRPC interface is being progressively added to Weaviate.

gRPC is a high-performance, open-source universal RPC framework that is contract-based and can be used in any environment. It is based on HTTP/2 and Protocol Buffers, and is therefore very fast and efficient.

Read more about the gRPC API here.