Notes and best practices

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.

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);

import weaviate from "weaviate-client";

const client = await weaviate.connectToLocal();

console.log(client);

import weaviate from "weaviate-client";

const client = await weaviate.connectToCustom({
  httpHost: "localhost",
  httpPort: 8080,
  grpcHost: "localhost",
  grpcPort: 50051,
  grpcSecure: true,
  httpSecure: true,
  authCredentials: new weaviate.ApiKey("WEAVIATE_INSTANCE_API_KEY"),
  headers: {
    "X-Cohere-Api-Key": process.env.COHERE_API_KEY || "", // Replace with your inference API key
  },
});

console.log(client);

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.

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.

When establishing a connection to the Weaviate server, the client performs a series of checks. These includes checks for the server version, and to make sure that the REST and gRPC ports are available.

You can set skipInitChecks to true to skip these checks.

import weaviate from 'weaviate-client';

const client = await weaviate.connectToLocal({
  skipInitChecks: true,
})

In most cases, you should use the default false setting for skipInitChecks. However, setting skipInitChecks: true may be a useful temporary measure if you have connection issues.

For additional connection configuration, see Timeout values.

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,
});

The cursor API has a new iterator method. To repeat an action over an entire collection, use iterator().

const articles = client.collections.use("Article");

for await (const article of articles.iterator()) {
  // do something with article.
  console.log(article); // we print each object in the collection
}

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.

You can set timeout values, in seconds, for the client. Use the timeout property to configure the timeout values for initialization checks as well as query and insert operations.

import weaviate from 'weaviate-client';

const client = await weaviate.connectToLocal({
  timeout: {
      query: 20,
      insert: 120,
      init: 10,
  }
})