Installation and setup

The JavaScript client library package can be easily installed using npm.

$ npm install weaviate-client

Now you can use the client in your JavaScript scripts as follows:

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

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

client
  .schema
  .getter()
  .do()
  .then(res => {
    console.log(res);
  })
  .catch(err => {
    console.error(err)
  });

Authentication

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

const client = weaviate.client({
    scheme: 'http',
    host: 'localhost:8080',
    headers: {authorization: 'Bearer <put your token here>'}
  });

References

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

Design

Builder pattern

The JavaScript client is 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/schema. The client is initiated with requiring the package and connecting to the running instance. Then, a query is constructed with getting the .schema with .getter(). The query will be sent with the .do() function, this object is thus required for every function you want to build and execute.

General notes

• All methods use ES6 Promises to deal with asynchronous code. So you need to use .then() at the end of the function, or have async/await support.
• In the case of an error, the Promise rejects with the specific error message. (If using async/await a rejected promises acts like a thrown exception).
• Internally the client uses isomorphic-fetch to do the REST calls, so the client should work from both the browser as well as NodeJS backend applications without any required changes.

Change logs

v2.12.0

• Added support for backup API
• Added method withObjects to objectsBatcher
• Added method withReferences to referencesBatcher

v2.11.1

• Fixed fetching db version

v2.11.0

• Added support for class namespaced API calls
• Added support for distance user-facing similarity metric

v2.10.1

• Updated README.md file with proper project links

v2.10.0

• Added support for nearText moveTo and moveAwayFrom parameters

v2.9.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

v2.8.0

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

v2.7.0

• Added support for getting schema’s class details (GET /v1/schema/{className})

v2.6.0

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

v2.5.0

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

v2.4.0

• Added support of the spellcheck module

v2.3.0

• Added img2vec-neural module (Weaviate v1.4.0) support.

v2.2.0

• Added QnA-transformers module support.

v2.1.0

This release adds nearObject using withNearObject() in GraphQL "Get" and "Explore".

v2.0.0

This change contains breaking changes over previous version as it is aligned with the new API of Weaviate v1. Use the client version v2.0.0 and up for Weaviate instances running v1.0.0 and up. Use client version v1.1.x for Weaviate version 0.23.y. Changes (and migration guide):

• .withKind() removed

  Due to the removal of semantic Kinds (“things/actions”) in Weaviate, the .withKind() method is removed on all builders

• .withSchema() -> .withProperties()

  Due to the renaming of object.schema to object.properties in Weaviate, all .withSchema({"foo": "bar"}) methods were renamed to .withProperties({"foo": "bar"})

• .withInterpretation() => .withAdditional('interpretation') on Getter/GetterById

  This change reflects two changes in Weaviate: First up, “Underscore Properties” are now called “Additional Properties”, furthermore the presence of such properties may depend on modules and is thus now dynamic. As such, the desired additional property is now passed in as a string.

  Note: There is one exception: .withVector() can still be used, as the field vector has been “upgraded” from an underscore/additional property to a regular property

• .withExplore() -> .withNearText()

  Following the renaming of explore to nearText in Weaviate the builder method was renamed accordingly. Additionally, the new method .withNearVector({vector: [...]}) was introduced to allow for nearVector searches.

  Note: GraphQL Explore { } queries in Weaviate v1 were changed to no longer be specific to text searches. As a result the client builder methods .withConcepts(), .withMoveTo() and .withMoveAwayFrom() were replaced with .withNearText({concepts: [...], ...}). Similarly to GraphQL Get { }, the new method .withNearVector({vector: [...]})

• .withK(3) -> .withSettings({k: 3}) in classification builder

  To reflect the API changes in the classification builder the kNN-specific method .withK(), was replaced with a more generic .withSettings({}) which takes any classification type-specific settings, such as {k: 3} for kNN or {tfidfCutoffPercentile: 80} for text2vec-contextual

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.