Skip to main content

JS/TS client v3

TypeScript client version

The TypeScript client is version v3.2.3. 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.

Jump straight to code?

If you want to dive straight into demo applications and code examples that use the client, please take a look at the example code section of this page.

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": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
  },
  "include": ["src/index.ts"] // this compiles only src/.index.ts, to compile all .ts files, use ["*.ts"]
}

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​

It is recommended to take a look at our Typescript quick start to get started with using the client. We have a more in-depth course; TS_101: Working with text data in Weaviate on our academy that uses the client. In addition, here are some resources to help you get started using the client.

Recipes​

The recipes repository (a W.I.P) on GitHub has sample code for common use cases.

Demo applications​

There are demo applications written in TypeScript and JavaScript here:

  • QuoteFinder: A hybrid, and vector search application to search through famous quotes built with React (Next.js), OpenAI and Weaviate.
  • Nuxt Vector Search: A vector search and RAG application to search through Wikipedia pages with Vue (Nuxt.js), OpenAI and Weaviate.
  • Next Vector Search: A vector search and RAG application to search through Wikipedia pages with React (Next.js), OpenAI and Weaviate.
  • Next Multimodal Search: A multimodal search application to search through images with React (Next.js), Google Vertex AI and Weaviate.
  • Nuxt Multimodal Search: A multimodal search application to search through images with Vue (Nuxt.js), Google Vertex AI and Weaviate.
  • FlickPicker: A multimodal search application with retrieval augmented generation (RAG) functionality to search through images with Vue (Nuxt.js), Google Vertex AI and Weaviate.
  • Nuxt eCommerce RAG: An eCommerce site with vector search and RAG to search through outdoor product listing and help you plan hikes built with Vue (Nuxt.js), OpenAI and Weaviate.

Client releases​

Go to the GitHub releases page to see the history of the TypeScript client library releases.

Click here for a table of Weaviate and corresponding client versions

This table lists the Weaviate core versions and corresponding client library versions.

Weaviate
(GitHub)		First
release date		Python
(GitHub)		TypeScript/
JavaScript
(GitHub)		Go
(GitHub)		Java
(GitHub)
1.27.x2024-10-164.9.x3.2.x4.16.x4.9.x
1.26.x2024-07-224.7.x3.1.x4.15.x4.8.x
1.25.x2024-05-104.6.x2.1.x4.13.x4.6.x
1.24.x2024-02-274.5.x2.0.x4.10.x4.4.x
1.23.x2023-12-183.26.x1.5.x4.10.x4.4.x
1.22.x2023-10-273.25.x1.5.x4.10.x4.3.x
1.21.x2023-08-173.22.x1.4.x4.9.x4.2.x
1.20.x2023-07-063.22.x1.1.x4.7.x4.2.x
1.19.x2023-05-043.17.x1.1.x14.7.x4.0.x
1.18.x2023-03-073.13.x2.14.x4.6.x3.6.x
1.17.x2022-12-203.9.x2.14.x4.5.x3.5.x
1.16.x2022-10-313.8.x2.13.x4.4.x3.4.x
1.15.x2022-09-073.6.x2.12.x4.3.x3.3.x
1.14.x2022-07-073.6.x2.11.x4.2.x3.2.x
1.13.x2022-05-033.4.x2.9.x4.0.x2.4.x
1.12.x2022-04-053.4.x2.8.x3.0.x2.3.x
1.11.x2022-03-143.2.x2.7.x2.6.x2.3.x
1.10.x2022-01-273.1.x2.5.x2.4.x2.1.x
1.9.x2021-12-103.1.x2.4.x2.4.x2.1.x
1.8.x2021-11-303.1.x2.4.x2.3.x1.1.x
1.7.x2021-09-013.1.x2.4.x2.3.x1.1.x
1.6.x2021-08-112.4.x2.3.x2.2.x1.0.x
1.5.x2021-07-132.2.x2.1.x2.1.x1.0.x
1.4.x2021-06-092.2.x2.1.x2.1.x1.0.x
1.3.x2021-04-232.2.x2.1.x2.1.x1.0.x
1.2.x2021-03-152.2.x2.0.x1.1.x-
1.1.x2021-02-102.1.x---
1.0.x2021-01-142.0.x---

Change logs​

For more detailed information on client updates, check the change logs. The logs are hosted here:

Questions and feedback​

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