Skip to main content

Migrate from v2 to v3

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.

Install​

To install the TypeScript client v3, follow these steps:

  1. Update Node.js

    The v3 client requires Node v18 or higher.

  2. Install the new client package

    npm install weaviate-client

  3. Upgrade Weaviate

    The v3 client requires Weaviate core 1.23.7 or higher. Whenever possible, use the latest versions of Weaviate core and the Weaviate client.

  4. Open a gRPC port

    The default gRPC port is 50051.

    docker-compose.yml

    To map the Weaviate gRPC port in your Docker container to a local port, add this code to your docker-compose.yml file:

        ports:
        - 8080:8080
        - 50051:50051

Instantiate a client​

The weaviate object is the main entry point for all API operations. The v3 client instantiates the weaviate object and creates a connection to your Weaviate instance.

In most cases, you should use one of the connection helper functions to connect to your Weaviate instance:

  • connectToWCD
  • connectToLocal
  • connectToCustom

You can also use a custom configuration to instantiate the client directly:

import weaviate from 'weaviate-client'

const client = await weaviate.connectToLocal()
 
console.log(client)

Changes in v3​

The v3 client introduces a new way to work with your data. Here are some of the important changes:

Work with collections​

The v2 client uses the client object for CRUD and search operations. In the v3 client, the collection object replaces the client object.

After you create a connection, you do not have to specify the collection for each operation. This helps to reduce errors.

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects()

console.log(JSON.stringify(result.objects, null, 2));

The collection object can be re-used throughout the codebase.

Builder Pattern is removed​

The v2 client uses builder patterns to construct queries. Builder patterns can be confusing and can lead to invalid queries.

The v3 client doesn't use the builder pattern. The v3 client uses specific methods and method parameters instead.

let result 
const myCollection = client.collections.get('JeopardyQuestion');

result = await myCollection.query.nearText(['animals in movies'],{
  limit: 2,
  returnProperties: ['question', 'answer'],
  returnMetadata: ['distance']
})

console.log(JSON.stringify(result.objects, null, 2));

Batch Inserts​

The insertMany() method replaces objectBatcher() to make batch insertions easier.

For more information on batch processing, see Batch Inserts.

const questions = client.collections.get("CollectionName")
const dataObject = [...]; // your data

await questions.data.insertMany(dataBatch);

Client Close 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.

Filter data​

The Filter helper class makes it easier to use filters with conditions. The v3 client streamlines how you use Filter so your code is cleaner and more concise.

import weaviate, { Filters } from 'weaviate-client';
const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects({
  returnProperties: ['question', 'answer','round', 'points'],
  filters: Filters.and(
     myCollection.filter.byProperty('round').equal('Double Jeopardy!'),
     myCollection.filter.byProperty('points').lessThan(600)
    ),
  limit: 3,
 })

console.log(JSON.stringify(result, null, 2));

Generate Namespace​

The v3 client adds a new namespace, generate for generative queries. This makes it easier to distinguish between generative queries and vector searches.

const generatePrompt = `Convert this quiz question: {question} and answer: {answer} into a trivia tweet.`;

const myCollection = client.collections.get('JeopardyQuestion');
const result = await myCollection.generate.nearText(['World history'],{
    singlePrompt: generatePrompt,
  },{
    limit: 2,
    returnProperties: ['round'],
})

console.log(JSON.stringify(result.objects, null, 2));

Return object​

The new client has a cleaner return object. It is easier to access important information like object UUIDs, object metadata, and generative query results.

response.objects[0].properties.title  // Get the `title` property of the first object
response.objects[0].uuid  // Get the ID of the first object
response.objects[0].generated  // Get the generated text from a `singlePrompt` request
response.generated  // Get the generated text from a `groupedTask` request
response.metadata?.creationTime // Get the creation time as a native JS Date value

Code comparison​

These samples compare v2 client code and v3 client code.

The comparison samples omit sections of the code that are the same for both clients. The complete v2 and v3 client scripts are here.

Imports​

import weaviate, { WeaviateClient} from 'weaviate-client';
import 'dotenv/config';

Connect to Weaviate Cloud​

  // connect to your Weaviate instance on WCD
  const weaviateURL = process.env.WEAVIATE_URL as string
  const weaviateKey = process.env.WEAVIATE_ADMIN_KEY as string
  const openaiKey = process.env.OPENAI_API_KEY as string
  
  const client: WeaviateClient = await weaviate.connectToWeaviateCloud(weaviateURL, {
    authCredentials: new weaviate.ApiKey(weaviateKey),
    headers: {
      'X-OpenAI-Api-Key': openaiKey,  
    }
  })

Create a collection​

  // create a new collection
  await client.collections.create({
    name: collectionName,
    vectorizers: weaviate.configure.vectorizer.text2VecOpenAI(),
  })

Batch insert​

  // define a collection to interact with 
  const myCollection = client.collections.get(collectionName)

  // bulk insert data to your collection
  await myCollection.data.insertMany(await response.json())

Query your data​

  // run a nearText search; limit 2 results; show distance metrics
  const queryResponse = await myCollection.query.nearText('songs about cowboys',{
    limit: 2,
    returnMetadata: ['distance']
  })

  console.log('Here are songs about cowboys: ', queryResponse.objects)

Delete a collection​

  // delete your collection
  await client.collections.delete(collectionName)

  console.log('Collection Exists:', await client.collections.exists(collectionName))
}

Sample scripts​

These scripts are complete versions of the client comparison code from this section.

import weaviate, { WeaviateClient} from 'weaviate-client';
import 'dotenv/config';
async function main() {
  // define a collection name
  const collectionName = 'RollingStones'
  // connect to your Weaviate instance on WCD
  const weaviateURL = process.env.WEAVIATE_URL as string
  const weaviateKey = process.env.WEAVIATE_ADMIN_KEY as string
  const openaiKey = process.env.OPENAI_API_KEY as string
  
  const client: WeaviateClient = await weaviate.connectToWeaviateCloud(weaviateURL, {
    authCredentials: new weaviate.ApiKey(weaviateKey),
    headers: {
      'X-OpenAI-Api-Key': openaiKey,  
    }
  })
  // create a new collection
  await client.collections.create({
    name: collectionName,
    vectorizers: weaviate.configure.vectorizer.text2VecOpenAI(),
  })
  const response = await fetch('https://raw.githubusercontent.com/weaviate/weaviate-io/tsdocs/content-fixes/_includes/clients/songs.json')
  // define a collection to interact with 
  const myCollection = client.collections.get(collectionName)

  // bulk insert data to your collection
  await myCollection.data.insertMany(await response.json())
  // run a nearText search; limit 2 results; show distance metrics
  const queryResponse = await myCollection.query.nearText('songs about cowboys',{
    limit: 2,
    returnMetadata: ['distance']
  })

  console.log('Here are songs about cowboys: ', queryResponse.objects)
  // delete your collection
  await client.collections.delete(collectionName)

  console.log('Collection Exists:', await client.collections.exists(collectionName))
}
main()

For more code examples, see the following:

How to migrate your code​

To update v2 client code to v3, follow these steps:

  1. Install the v3 client package.
  2. Edit your v2 code to import the v3 client package.
  3. Edit your v2 client instantiation code.
  4. Edit your code to reflect the collection first client orientation.

Continue to update the v2 code until all of the old code is replace with the v3 equivalent.

Client change logs​

The client change logs for each release are available on GitHub.

Questions and feedback​

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