Java

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

A Java client library for Weaviate.


Installation and setup

To get the latest stable version of the Java client library, add this dependency to your project:

<dependency>
  <groupId>technology.semi.weaviate</groupId>
  <artifactId>client</artifactId>
  <version>3.1.1</version>
</dependency>

This API client is compatible with Java 8 and beyond.

You can use the client in your project as follows:

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.misc.model.Meta;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);
    Result<Meta> meta = client.misc().metaGetter().run();
    if (meta.getError() != null) {
      System.out.printf("meta.hostname: %s\n", meta.getResult().getHostname());
      System.out.printf("meta.version: %s\n", meta.getResult().getVersion());
      System.out.printf("meta.modules: %s\n", meta.getResult().getModules());
    } else {
      System.out.printf("Error: %s\n", meta.getError().getMessages());
    }
  }
}

Authentication

You can pass authentication credentials in a header to the client, which is added to the initialization of the client in your Java project:

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.misc.model.Meta;

public class App {
  public static void main(String[] args) {
    Map<String, String> headers = new HashMap<String, String>() { {
      put("Authorization", "Bearer <put your token here>");
    } };
    Config config = new Config("http", "localhost:8080", headers);
    WeaviateClient client = new WeaviateClient(config);
    Result<Meta> meta = client.misc().metaGetter().run();    
  }
}

References

All RESTful endpoints and GraphQL functions references covered by the Java client, and explained on those reference pages in the code blocks.

Design

Builder pattern

The Java client functions are designed with a ‘Builder pattern’. A pattern is used to build complex query objects. This means that a function (for example to retrieve data from Weaviate with a request similar to a RESTful GET request, or a more complex GraphQL query) is built with single objects to reduce complexity. Some builder objects are optional, others are required to perform specific functions. All is documented on the RESTful API reference pages and the GraphQL reference pages.

The code snippet above shows a simple query similar to RESTful GET /v1/meta. The client is initiated by requiring the package and connecting to the running instance. Then, a query is constructed by using the .metaGetter() on .misc(). The query will be sent with the .run() function, this object is thus required for every function you want to build and execute.

Migration Guides

From 2.4.0 to 3.0.0

Removed @Deprecated method Aggregate::withFields(Fields fields)

Before:

// import technology.semi.weaviate.client.v1.graphql.query.fields.Field;
// import technology.semi.weaviate.client.v1.graphql.query.fields.Fields;

Fields fields = Fields.builder().fields(new Field[]{name, description}).build();
client.graphQL().aggregate().withFields(fields)...

After:

client.graphQL().aggregate().withFields(name, description)...

Removed @Deprecated method Get::withFields(Fields fields)

Before:

// import technology.semi.weaviate.client.v1.graphql.query.fields.Field;
// import technology.semi.weaviate.client.v1.graphql.query.fields.Fields;

Fields fields = Fields.builder().fields(new Field[]{name, description}).build();
client.graphQL().get().withFields(fields)...

After:

client.graphQL().get().withFields(name, description)...

Removed @Deprecated method Get::withNearVector(Float[] vector)

Before:

client.graphQL().get().withNearVector(new Float[]{ 0f, 1f, 0.8f })...

After:

// import technology.semi.weaviate.client.v1.graphql.query.argument.NearVectorArgument;

NearVectorArgument nearVector = NearVectorArgument.builder().vector(new Float[]{ 0f, 1f, 0.8f }).certainty(0.8f).build();
client.graphQL().get().withNearVector(nearVector)...

All where filters use the same implementation

With batch delete feature, unified filters.WhereFilter implementation is introduced, which replaces classifications.WhereFilter, graphql.query.argument.WhereArgument and graphql.query.argument.WhereFilter.

GraphQL

Before:

// import technology.semi.weaviate.client.v1.graphql.query.argument.GeoCoordinatesParameter;
// import technology.semi.weaviate.client.v1.graphql.query.argument.WhereArgument;
// import technology.semi.weaviate.client.v1.graphql.query.argument.WhereOperator;

GeoCoordinatesParameter geo = GeoCoordinatesParameter.builder()
    .latitude(50.51f)
    .longitude(0.11f)
    .maxDistance(3000f)
    .build();
WhereArgument where = WhereArgument.builder()
    .valueGeoRange(geo)
    .operator(WhereOperator.WithinGeoRange)
    .path(new String[]{ "add "})
    .build();

client.graphQL().aggregate().withWhere(where)...

After:

// import technology.semi.weaviate.client.v1.filters.Operator;
// import technology.semi.weaviate.client.v1.filters.WhereFilter;

WhereFilter where = WhereFilter.builder()
    .valueGeoRange(WhereFilter.GeoRange.builder()
        .geoCoordinates(WhereFilter.GeoCoordinates.builder()
            .latitude(50.51f)
            .longitude(0.11f)
            .build()
        )
        .distance(WhereFilter.GeoDistance.builder()
            .max(3000f)
            .build()
        )
        .build()
    )
    .operator(Operator.WithinGeoRange)
    .path(new String[]{ "add" })
    .build();

client.graphQL().aggregate().withWhere(where)...    

Before:

// import technology.semi.weaviate.client.v1.graphql.query.argument.WhereArgument;
// import technology.semi.weaviate.client.v1.graphql.query.argument.WhereOperator;

WhereArgument where = WhereArgument.builder()
    .valueString("txt")
    .operator(WhereOperator.Equal)
    .path(new String[]{ "add" })
    .build();

client.graphQL().aggregate().withWhere(where)...

After:

// import technology.semi.weaviate.client.v1.filters.Operator;
// import technology.semi.weaviate.client.v1.filters.WhereFilter;

WhereFilter where = WhereFilter.builder()
    .valueString("txt")
    .operator(Operator.Equal)
    .path(new String[]{ "add" })
    .build();

client.graphQL().aggregate().withWhere(where)...

Before:

// import technology.semi.weaviate.client.v1.graphql.query.argument.WhereArgument;
// import technology.semi.weaviate.client.v1.graphql.query.argument.WhereFilter;
// import technology.semi.weaviate.client.v1.graphql.query.argument.WhereOperator;

WhereArgument where = WhereArgument.builder()
    .operands(new WhereFilter[]{
        WhereFilter.builder()
            .valueInt(10)
            .path(new String[]{ "wordCount" })
            .operator(WhereOperator.LessThanEqual)
            .build(),
        WhereFilter.builder()
            .valueString("word")
            .path(new String[]{ "word" })
            .operator(WhereOperator.LessThan)
            .build()
    })
    .operator(WhereOperator.And)
    .build();

client.graphQL().aggregate().withWhere(where)...

After:

// import technology.semi.weaviate.client.v1.filters.Operator;
// import technology.semi.weaviate.client.v1.filters.WhereFilter;

WhereFilter where = WhereFilter.builder()
    .operands(new WhereFilter[]{
        WhereFilter.builder()
            .valueInt(10)
            .path(new String[]{ "wordCount" })
            .operator(Operator.LessThanEqual)
            .build(),
        WhereFilter.builder()
            .valueString("word")
            .path(new String[]{ "word" })
            .operator(Operator.LessThan)
            .build(),
    })
    .operator(Operator.And)
    .build();

client.graphQL().aggregate().withWhere(where)...

Classification

Before:

// import technology.semi.weaviate.client.v1.classifications.model.GeoCoordinates;
// import technology.semi.weaviate.client.v1.classifications.model.Operator;
// import technology.semi.weaviate.client.v1.classifications.model.WhereFilter;
// import technology.semi.weaviate.client.v1.classifications.model.WhereFilterGeoRange;
// import technology.semi.weaviate.client.v1.classifications.model.WhereFilterGeoRangeDistance;

WhereFilter where = WhereFilter.builder()
    .valueGeoRange(WhereFilterGeoRange.builder()
        .geoCoordinates(GeoCoordinates.builder()
            .latitude(50.51f)
            .longitude(0.11f)
            .build())
        .distance(WhereFilterGeoRangeDistance.builder()
            .max(3000d)
            .build())
        .build())
    .operator(Operator.WithinGeoRange)
    .path(new String[]{ "geo" })
    .build();

client.classifications().scheduler().withTrainingSetWhereFilter(where)...

After:

// import technology.semi.weaviate.client.v1.filters.Operator;
// import technology.semi.weaviate.client.v1.filters.WhereFilter;

WhereFilter where = WhereFilter.builder()
    .valueGeoRange(WhereFilter.GeoRange.builder()
        .geoCoordinates(WhereFilter.GeoCoordinates.builder()
            .latitude(50.51f)
            .longitude(0.11f)
            .build())
        .distance(WhereFilter.GeoDistance.builder()
            .max(3000f)
            .build())
        .build())
    .operator(Operator.WithinGeoRange)
    .path(new String[]{ "geo" })
    .build();

client.classifications().scheduler().withTrainingSetWhereFilter(where)...

Change logs

3.1.1

  • Updated test dependencies to newest versions

3.1.0

  • Added support for nearText moveTo and moveAwayFrom parameters

3.0.0

  • Added support for near<Media> filters for Aggregate queries
  • Added suuport for objectLimit parameter in Aggregate queries
  • Added support for sort argument in GraphQL
  • Added support for batch delete by query REST endpoint
  • Deprecated withFields(Fields) method in favor of the withFields(Field[])
  • Added support for near<Media> filters for Explore queries
  • Added indexTimestamps setting support to invertedIndexConfig
  • Unified where filter support in all REST and GraphQL queries
  • Fixed valueDate parameter support in where filter

2.4.0

  • Added support for configurable stopwords
  • Added support for custom bm25 params
  • Added support for property tokenization field setting
  • Added support for Shards API

2.3.0

  • Added support for getting schema’s class details (GET /v1/schema/{className})
  • Added support for where argument in Aggregate queries

2.2.2

  • Fixed error parsing logic

2.2.1

  • Fixed a bug that prevented reference properties from being serialized to Json object

2.2.0

  • Added support for object check request (HEAD /v1/objects/{id})
  • Added support for rerank parameter in GraphQL ask argument

2.1.1

  • Added support for creating objects with custom vectors

2.1.0

  • Added support of the offset parameter in GraphQL and REST API

2.0.0

  • Introduced class builder approach for where and field clauses

1.2.1

  • Added support for boolean[] and date[] data types

1.2.0

  • Added support for Weaviate array data types
  • Fixed support for UTF-8 encoded characters

1.1.2

  • Added support of the spellcheck module.

1.1.1

  • The new version is compatible with Weaviate v1.6.0 (by supporting the new ZeroShot classification).

1.1.0

  • The new version is compatible with Weaviate v1.4.0 (supports the new img2vec-neural module).

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.