{"id":15928,"library":"weaviate-ts-client","title":"Weaviate TypeScript Client","description":"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.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/weaviate/typescript-client","tags":["javascript","weaviate","typescript"],"install":[{"cmd":"npm install weaviate-ts-client","lang":"bash","label":"npm"},{"cmd":"yarn add weaviate-ts-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add weaviate-ts-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for instantiating the Weaviate client. Requires `new WeaviateClient(...)`.","wrong":"const WeaviateClient = require('weaviate-ts-client');","symbol":"WeaviateClient","correct":"import { WeaviateClient } from 'weaviate-ts-client';"},{"note":"A namespace for common Weaviate-related types, particularly useful for specifying generic parameters for multi-vector search since v3.8.0.","symbol":"WeaviateGenerics","correct":"import { WeaviateGenerics } from 'weaviate-ts-client';"},{"note":"Represents the structure of a single data object in a Weaviate collection. Useful for strict typing of data payloads.","symbol":"DataItem","correct":"import { DataItem } from 'weaviate-ts-client';"}],"quickstart":{"code":"import { WeaviateClient } from 'weaviate-ts-client';\n\nasync function run() {\n  // Ensure your Weaviate instance is running, e.g., using Docker Compose.\n  // Environment variables can be set for configuration:\n  // WEAVIATE_SCHEME=http\n  // WEAVIATE_HOST=localhost:8080\n  // WEAVIATE_API_KEY=YOUR_API_KEY (if using auth, e.g., for Weaviate Cloud)\n\n  const client = new WeaviateClient({\n    scheme: process.env.WEAVIATE_SCHEME ?? 'http',\n    host: process.env.WEAVIATE_HOST ?? 'localhost:8080',\n    // Uncomment and provide your API key if your Weaviate instance requires authentication\n    // apiKey: process.env.WEAVIATE_API_KEY ?? '',\n    connectionTimeoutMs: 10000,\n  });\n\n  try {\n    const collectionName = 'MyTestCollection';\n\n    // 1. Check if collection exists and create if not\n    const myCollection = client.collections.get(collectionName);\n    const collectionExists = await myCollection.exists();\n\n    if (!collectionExists) {\n      await client.collections.create({\n        name: collectionName,\n        properties: [\n          { name: 'title', dataType: 'text' },\n          { name: 'year', dataType: 'int' },\n        ],\n        vectorizers: [\n          {\n            name: 'title_vectorizer', // Unique name for the vectorizer configuration\n            vectorizerConfig: {\n              vectorizerClassName: 'text2vec-openai', // Requires 'text2vec-openai' module to be enabled in Weaviate\n              model: 'text-embedding-ada-002',\n              vectorizePropertyName: true, // Vectorize the 'title' property\n            },\n          },\n        ],\n      });\n      console.log(`Collection '${collectionName}' created successfully.`);\n    } else {\n      console.log(`Collection '${collectionName}' already exists.`);\n    }\n\n    // 2. Add data items to the collection\n    const dataManager = client.collections.data;\n    const item1 = await dataManager.insert({\n      collection: collectionName,\n      data: {\n        title: 'The Hitchhikers Guide to the Galaxy',\n        year: 1979,\n      },\n    });\n    console.log('Added data item 1 (UUID):', item1.uuid);\n\n    const item2 = await dataManager.insert({\n      collection: collectionName,\n      data: {\n        title: 'The Restaurant at the End of the Universe',\n        year: 1980,\n      },\n    });\n    console.log('Added data item 2 (UUID):', item2.uuid);\n\n    // 3. Perform a BM25 search on the collection\n    const queryResult = await client.collections.query.bm25(collectionName, {\n      query: 'guide galaxy',\n      properties: ['title'],\n    });\n    console.log('BM25 Search results (title containing \"guide galaxy\"):', queryResult.objects.map(o => o.properties?.title));\n\n  } catch (error) {\n    console.error('An error occurred:', error instanceof Error ? error.message : String(error));\n  }\n}\n\nrun();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version `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.","severity":"breaking","affected_versions":"3.7.0"},{"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>`.","message":"With 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.","severity":"breaking","affected_versions":">=3.8.0"},{"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+`.","message":"Version `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.","severity":"deprecated","affected_versions":"3.7.0"},{"fix":"Always instantiate the client using `new WeaviateClient({ ...config })` after a named import: `import { WeaviateClient } from 'weaviate-ts-client';`.","message":"Weaviate 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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: WeaviateClient is not a constructor"},{"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.","cause":"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.","error":"Error: connect ECONNREFUSED <host>:<port>"},{"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.","cause":"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.","error":"Error: status code 500: ... invalid vectorizer configuration"},{"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.","cause":"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.","error":"Property 'someProperty' does not exist on type 'WeaviateGenerics.Property<...>'"}],"ecosystem":"npm"}