Skip to main content

JS/TS client v3

TypeScript client version

The TypeScript client is version v3.0.9. Use the TypeScript v3 client for new projects.

The Weaviate TypeScript client supports TypeScript and JavaScript.

The v3 client 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

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.connectToWeaviateCloud(
'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.connectToWeaviateCloud(
'WEAVIATE_INSTANCE_URL', // Replace WEAVIATE_INSTANCE_URL with your instance URL
{
authCredentials: new weaviate.ApiKey('WEAVIATE_INSTANCE_API_KEY'), // Add your WCD 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.connectToWeaviateCloud(
'WEAVIATE_INSTANCE_URL', // Replace WEAVIATE_INSTANCE_URL with your instance URL
{
authCredentials: new weaviate.ApiKey('WEAVIATE_INSTANCE_API_KEY'), // Add your WCD 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.data.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

For links to the client releases associated with the latest Weaviate core releases, expand this section.

Current core and client releases
Weaviate VersionRelease DatePythonTypeScriptGoJava
1.25.72024-07-044.6.63.0.84.14.04.7.0
1.25.62024-06-284.6.5''''''
1.25.52024-06-24''''''''
1.25.42024-06-134.6.33.0.3''''
1.25.32024-06-11''''''''
1.25.22024-05-31''2.2.0''''
1.25.12024-05-174.6.02.1.14.13.14.6.0
1.25.02024-05-10''''''''

For links to previous releases, expand this section.

Previous core and client 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.0]4.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''''-

Note: The TypeScript client replaced the JavaScript client on 2023-03-17.

Client change logs

The client change logs for each release are available on GitHub.

Questions and feedback

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