Skip to main content

TS/JS client v3 (Beta)

TypeScript client version

The current TypeScript client version is v2.1.1.


The TypeScript client v3 is in beta release. To comment on the beta client, contact us in the [Community forum](https://forum.weaviate.io).

The Weaviate TypeScript client supports TypeScript and JavaScript. The TypeScript client v3 is currently in beta.

The upcoming v3 client currently supports server side development (Node.js hosted). See v3 packages for details. If your application is browser based, consider using the TypeScript client v2.

If you are migrating a project from the Weaviate TypeScript client v2 to the v3 client, see the migration page for additional details.

Client configuration​

This section details how install and configure the v3 TypeScript client.

Install the package​

The v3 client package has a new name, weaviate-client. Use npm to install the TypeScript client library package:

npm install weaviate-client --tag beta

Import the Client​

The v3 client uses ES Modules. Most of the sample code in the documentation also uses the ES Module style.

If your code requires CommonJS compatibility, use the CommonJS import style:

import weaviate from 'weaviate-client'

TypeScript setup​

Edit your project's configuration files to make these changes:

  • Add "type": "module" to package.json
  • Add the following code to tsconfig.json
tsconfig.json file
{
    "compilerOptions": {
      "target": "esnext",
      "module": "esnext", 
      "moduleResolution": "Node16",
      "esModuleInterop": true,
      "lib": [ "es2018" ],
  }
}

Connect a client​

The v3 client provides helper functions to connect your application to your Weaviate instance.

Embedded Weaviate is not supported in the v3 client. The v2 client supports embedded Weaviate.

Connect to Weaviate​

import weaviate from 'weaviate-client'

const client = await weaviate.connectToWCS(
  'WEAVIATE_INSTANCE_URL', { // Replace WEAVIATE_INSTANCE_URL with your instance URL
    authCredentials: new weaviate.ApiKey('WEAVIATE_INSTANCE_API_KEY'), 
    headers: {
      'X-OpenAI-Api-Key': process.env.OPENAI_API_KEY || '',  // Replace with your inference API key
    }
  } 
)

console.log(client)

Close client method​

The client uses a keep-alive header to maintain long-lived connections to Weaviate.

After you establish the connection to your Weaviate instance, subsequent calls are faster. When you finish your client operations, close the connection to free server resources.

Use the client.close() method to close the connection instead of waiting for the connection to time out.

Authentication​

If you use an API key to authenticate, instantiate the client like this:

import weaviate, { WeaviateClient } from 'weaviate-client';

// Instantiate the client with the auth config
const client: WeaviateClient = await weaviate.connectToWCS(
  'WEAVIATE_INSTANCE_URL', // Replace WEAVIATE_INSTANCE_URL with your instance URL
  {
    authCredentials: new weaviate.ApiKey('WEAVIATE_INSTANCE_API_KEY'), // Add your WCS API KEY here
  } 
)

console.log(client)

To include custom headers, such as API keys for third party services, add the custom headers to the headers section when you initialize the client:

import weaviate, { WeaviateClient } from 'weaviate-client';

const client: WeaviateClient = await weaviate.connectToWCS(
  'WEAVIATE_INSTANCE_URL', // Replace WEAVIATE_INSTANCE_URL with your instance URL
  {
    authCredentials: new weaviate.ApiKey('WEAVIATE_INSTANCE_API_KEY'), // Add your WCS API KEY here
    headers: {
      someHeaderName: 'header-value', 
    }
  } 
)

The client sends the headers every it makes a request to the Weaviate instance.

Changes in v3​

This section highlights some features of the v3 TypeScript client.

Design philosophy​

The v3 client interacts with collections as the primary way to work with objects in your Weaviate database.

Your application code creates an object that represents a collection. This object enables search and CRUD operations to be performed against it.

This example returns objects from the JeopardyQuestion collection.

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects()

console.log(JSON.stringify(result, null, 2));

Node support only​

The gRPC protocol is fast and provides other internal benefits. Unfortunately, gRPC does not support browser-based client development.

The v3 client uses gRPC to connect to your Weaviate instance. The client supports Node.js, server-based development. It does not support browser-based web client development.

To develop a browser-based application, use the v2 client.

Batch Inserts​

The insertMany() method makes it easier to bulk insert a large number of objects.

For inserts of over 5000 objects, use insertMany() as part of a batch process:

const questions = client.collections.get("CollectionName")

const batchSize = 1000; // define your batch size

async function insertBatch() {
  try {
    await questions.data.insertMany(dataBatch);
    console.log('Batch inserted successfully');
  } catch (error) {
    console.error('Error inserting batch:', error);
  }
}

async function batchInsert() {
  for (let i = 0; i < dataArray.length; i += batchSize) {
    const batch = dataArray.slice(i, i + batchSize);
    await insertBatch(batch);
  }
}

const dataObject = [...]; // your data
await batchInsert(dataObject);

Iterator Method​

The cursor API has a new iterator method. To repeat an action over an entire collection, use iterator().

const articles = client.collections.get('Article')

for await (const article of articles.iterator()) {
  // do something with article. 
  console.log(article) // we print each object in the collection
}

Generics​

TypeScript users can define custom Generics. Generics make it easier to manipulate objects and their properties. Compile time type checks help to ensure that operations like insert() and create() are safe and error free.

import weaviate from 'weaviate-client';

type Article = {
  title: string;
  body: string;
  wordcount: number;
}

const collection = client.collections.get<Article>('Article');
await collection.insert({ // compiler error since 'body' field is missing in '.insert'
  title: 'TS is awesome!',
  wordcount: 9001
})

Async operations​

All client v3 methods, with the exception of collection.use(), use ES6 Promises with asynchronous code. This means you have to use .then() after function calls, or wrap your code async/await blocks.

When there is an asynchronous code error, a promise returns the specific error message. If you use async and await, a rejected promises acts like a thrown exception

Type Safety​

The v3 client enables strong typing with custom TypeScript types and user-defined generics.

You can find the type definitions in the folder that stores your Weaviate client package. The package is stored in a folder under the node/ directory. Custom type definitions are stored in sub-folder for each bundle.

For example, the index.d.ts file stores type definitions for the cjs bundle:

node/cjs/index.d.ts

The v3 client also adds internal features that make JavaScript development more type-safe.

Example code​

Here are some resources to help you get started using the client.

Recipes​

The recipes repository on Github has sample code for common use cases.

Demo applications​

There are demo applications written in TypeScript and JavaScript here:

Client releases​

These charts show the Weaviate client releases associated with Weaviate core releases.

Current Weaviate core minor releases​

Weaviate VersionRelease DatePythonTypeScriptGoJava
1.24.102024-04-194.5.62.1.14.13.14.6.0
1.24.92024-04-17''''''''
1.24.82024-04-08''''''''
1.24.72024-04-05''''''''
1.24.62024-03-264.5.4''''''
1.24.52024-03-21''''''''
1.24.42024-03-154.5.1''''''
1.24.32024-03-14''''''''
1.24.22024-03-13''''''''
1.24.12024-03-014.5.02.1.04.12.04.5.1

Weaviate core major releases​

Weaviate VersionRelease DatePythonTypeScriptGoJava
1.24.02024-02-274.5.02.1.04.12.04.5.1
1.23.02023-12-183.26.02.0.0''4.4.2
1.22.02023-10-273.25.0''4.10.04.3.0
1.21.02023-08-173.22.11.4.04.9.04.2.1
1.20.02023-07-063.22.0''''4.2.0
1.19.02023-05-043.17.01.1.014.7.14.0.1
1.18.02023-03-073.13.02.14.54.6.23.6.4
1.17.02022-12-203.9.02.14.04.5.03.5.0
1.16.02022-10-313.8.02.13.04.4.03.4.0
1.15.02022-09-07''2.12.04.3.03.3.0
1.14.02022-07-073.6.02.11.04.2.03.2.0
1.13.02022-05-033.4.22.9.04.0.02.4.0
1.12.02022-04-053.4.02.8.03.0.0''
1.11.02022-03-143.2.52.7.02.6.02.3.0
1.10.02022-01-27''2.5.02.4.12.1.1
1.9.02021-12-10''''2.4.02.1.0
1.8.02021-11-30''''''''
1.7.02021-09-013.1.12.4.02.3.01.1.0
1.6.02021-08-112.4.02.3.02.2.0''
1.5.02021-07-13''''''''
1.4.02021-06-09''''''''
1.3.02021-04-23''2.1.02.1.01.0.0
1.2.02021-03-152.2.02.0.01.1.0-
1.1.02021-02-102.1.0''''-
1.0.02021-01-142.0.0''''-
  1. The TypeScript client replaced the JavaScript client on 2023-03-17.↩

Client change logs​

See the client change logs on GitHub.

Questions and feedback​

If you have any questions or feedback, let us know in our user forum.