Registry / vector-search / weaviate-ts-client

weaviate-ts-client

JSON →
library2.2.0jsnpmunverified

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.

npm install weaviate-ts-client
INSTALL
IMPORT
SIG · WEAVIATE-TS-CLIENT
W
weaviate-ts-client
vector-searchjavascriptv2.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

WeaviateClient
import { WeaviateClient } from 'weaviate-ts-client';
const WeaviateClient = require('weaviate-ts-client');
The primary class for instantiating the Weaviate client. Requires `new WeaviateClient(...)`.
WeaviateGenerics
import { WeaviateGenerics } from 'weaviate-ts-client';
A namespace for common Weaviate-related types, particularly useful for specifying generic parameters for multi-vector search since v3.8.0.
DataItem
import { DataItem } from 'weaviate-ts-client';
Represents the structure of a single data object in a Weaviate collection. Useful for strict typing of data payloads.

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();
Debug
Known issues
breakingVersion `v3.7.0` accidentally introduced several breaking changes due to a refactor during API deprecation. It was quickly deprecated on NPM. Users are strongly advised to avoid `v3.7.0` and either remain on `v3.6.2` or upgrade directly to `v3.8.0` or later.
fix
Do not use `weaviate-ts-client@3.7.0`. If you are currently on `3.6.2`, upgrade to `3.8.0` or newer. If you are already on `3.7.0`, downgrade to `3.6.2` or upgrade to `3.8.0+` after reviewing the `v3.8.0` migration notes.
affects: 3.7.0
breakingWith the release of `v3.8.0`, several types in the API acquired a generic parameter to accommodate multi-vector search capabilities. This requires users to explicitly specify these generics, particularly when working with collection definitions or query results, to ensure type correctness.
fix
Review the official Weaviate TypeScript client documentation for `v3.8.0` and later. Update type annotations in your codebase to include the necessary generic parameters, often found within the `WeaviateGenerics` namespace, e.g., `WeaviateClient<WeaviateGenerics.Property>`.
affects: >=3.8.0
deprecatedVersion `v3.7.0` was explicitly deprecated on NPM shortly after its release due to critical breaking changes that rendered it unstable. It should not be used in production environments.
fix
Avoid installing or deploying `weaviate-ts-client@3.7.0`. Ensure your project's `package.json` specifies a stable version like `^3.8.0` or later, or `~3.6.2` if backward compatibility is paramount before migrating to `3.8.0+`.
affects: 3.7.0
gotchaWeaviate client initialization uses a class constructor (`new WeaviateClient({...})`) in `v3.x`, moving away from a factory pattern (`weaviate.client({...})`) seen in some older examples or other client libraries. Using the incorrect instantiation method will lead to runtime errors.
fix
Always instantiate the client using `new WeaviateClient({ ...config })` after a named import: `import { WeaviateClient } from 'weaviate-ts-client';`.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: WeaviateClient is not a constructor
Attempting to call WeaviateClient as a function (e.g., `WeaviateClient({...})`) instead of using the `new` keyword, or incorrect CommonJS `require` usage for an ESM-first library.
fix
Ensure you are using `new WeaviateClient({...})` for instantiation and `import { WeaviateClient } from 'weaviate-ts-client';` for ESM contexts. For CommonJS, consider using dynamic import or transpilation.
Error: connect ECONNREFUSED <host>:<port>
The Weaviate instance specified in the client configuration (host, port, scheme) is not running, is inaccessible from the client's network, or the configuration is incorrect.
fix
Verify that your Weaviate instance is running and accessible at the specified `host` and `port`. Check firewall rules and ensure the `scheme` (http/https) matches your Weaviate setup. Double-check environment variables if used for configuration.
Error: status code 500: ... invalid vectorizer configuration
When creating a collection, the specified vectorizer module (e.g., 'text2vec-openai') is either not enabled in your Weaviate instance, or its configuration parameters (like model name, API key) are incorrect.
fix
Ensure the necessary Weaviate modules are enabled in your Weaviate instance's configuration (e.g., in `docker-compose.yml`). Verify that the vectorizer configuration within your client code matches the module's requirements, including any required API keys for external services.
Property 'someProperty' does not exist on type 'WeaviateGenerics.Property<...>'
This typically occurs after upgrading to `v3.8.0` or later due to the introduction of generic parameters for multi-vector support, or generally due to incorrect type inference when querying data.
fix
Explicitly specify the generic type parameters for collection definitions and query results. Review the `WeaviateGenerics` namespace and adapt your types. For query results, ensure you're accessing properties through `result.objects[i].properties` which will have the inferred type.
Upgrade
Version history
2.2.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
58 hits · last 30 days
node
50
Perplexity
1
OpenAI (training)
1
Resources