Weaviate TypeScript Client

2.2.0 · active · verified Tue Apr 21

The `weaviate-ts-client` is the official TypeScript client library for interacting with a Weaviate vector database instance. It provides a type-safe and idiomatic interface for operations like data ingestion, schema management, vector search (including BM25 and hybrid search), and various module functionalities such as generative AI and rerankers. The library is currently on its `v3.12.0` stable release, with frequent minor updates addressing new Weaviate features, bug fixes, and performance improvements. Its release cadence is rapid, reflecting active development and close alignment with the Weaviate database's evolving capabilities, ensuring users can quickly leverage the latest features like object TTL, multi-vector search, and rotational quantization. This client is the recommended way to integrate Weaviate into TypeScript and Node.js applications.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart initializes a Weaviate client, creates a new collection if it doesn't exist, adds two data items, and then performs a BM25 search on the collection.

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

async function run() {
  // Ensure your Weaviate instance is running, e.g., using Docker Compose.
  // Environment variables can be set for configuration:
  // WEAVIATE_SCHEME=http
  // WEAVIATE_HOST=localhost:8080
  // WEAVIATE_API_KEY=YOUR_API_KEY (if using auth, e.g., for Weaviate Cloud)

  const client = new WeaviateClient({
    scheme: process.env.WEAVIATE_SCHEME ?? 'http',
    host: process.env.WEAVIATE_HOST ?? 'localhost:8080',
    // Uncomment and provide your API key if your Weaviate instance requires authentication
    // apiKey: process.env.WEAVIATE_API_KEY ?? '',
    connectionTimeoutMs: 10000,
  });

  try {
    const collectionName = 'MyTestCollection';

    // 1. Check if collection exists and create if not
    const myCollection = client.collections.get(collectionName);
    const collectionExists = await myCollection.exists();

    if (!collectionExists) {
      await client.collections.create({
        name: collectionName,
        properties: [
          { name: 'title', dataType: 'text' },
          { name: 'year', dataType: 'int' },
        ],
        vectorizers: [
          {
            name: 'title_vectorizer', // Unique name for the vectorizer configuration
            vectorizerConfig: {
              vectorizerClassName: 'text2vec-openai', // Requires 'text2vec-openai' module to be enabled in Weaviate
              model: 'text-embedding-ada-002',
              vectorizePropertyName: true, // Vectorize the 'title' property
            },
          },
        ],
      });
      console.log(`Collection '${collectionName}' created successfully.`);
    } else {
      console.log(`Collection '${collectionName}' already exists.`);
    }

    // 2. Add data items to the collection
    const dataManager = client.collections.data;
    const item1 = await dataManager.insert({
      collection: collectionName,
      data: {
        title: 'The Hitchhikers Guide to the Galaxy',
        year: 1979,
      },
    });
    console.log('Added data item 1 (UUID):', item1.uuid);

    const item2 = await dataManager.insert({
      collection: collectionName,
      data: {
        title: 'The Restaurant at the End of the Universe',
        year: 1980,
      },
    });
    console.log('Added data item 2 (UUID):', item2.uuid);

    // 3. Perform a BM25 search on the collection
    const queryResult = await client.collections.query.bm25(collectionName, {
      query: 'guide galaxy',
      properties: ['title'],
    });
    console.log('BM25 Search results (title containing "guide galaxy"):', queryResult.objects.map(o => o.properties?.title));

  } catch (error) {
    console.error('An error occurred:', error instanceof Error ? error.message : String(error));
  }
}

run();

view raw JSON →