@qdrant/js-client-rest

What is @qdrant/js-client-rest?

@qdrant/js-client-rest is a JavaScript client for interacting with the Qdrant vector search engine via REST API. It allows developers to manage collections, upload and search vectors, and perform various operations related to vector databases.

What are @qdrant/js-client-rest's main functionalities?

Manage Collections

This feature allows you to create and manage collections in the Qdrant database. The code sample demonstrates how to create a new collection with a specified vector size and distance metric.

const { QdrantClient } = require('@qdrant/js-client-rest');

const client = new QdrantClient({ url: 'http://localhost:6333' });

async function createCollection() {
  await client.createCollection('my_collection', {
    vectors: {
      size: 128,
      distance: 'Cosine'
    }
  });
}

createCollection();

Upload Vectors

This feature allows you to upload vectors to a specified collection. The code sample shows how to upload vectors with unique IDs to a collection.

const { QdrantClient } = require('@qdrant/js-client-rest');

const client = new QdrantClient({ url: 'http://localhost:6333' });

async function uploadVectors() {
  await client.uploadVectors('my_collection', [
    { id: '1', vector: [0.1, 0.2, 0.3, ...] },
    { id: '2', vector: [0.4, 0.5, 0.6, ...] }
  ]);
}

uploadVectors();

Search Vectors

This feature allows you to perform a search for similar vectors in a collection. The code sample demonstrates how to search for the top 5 vectors similar to a given query vector.

const { QdrantClient } = require('@qdrant/js-client-rest');

const client = new QdrantClient({ url: 'http://localhost:6333' });

async function searchVectors() {
  const results = await client.search('my_collection', {
    vector: [0.1, 0.2, 0.3, ...],
    top: 5
  });
  console.log(results);
}

searchVectors();

Other packages similar to @qdrant/js-client-rest

pinecone-client

Pinecone-client is a JavaScript client for interacting with the Pinecone vector database. Like @qdrant/js-client-rest, it provides functionalities for managing collections and performing vector operations. However, Pinecone is a managed service, which means it handles scaling and infrastructure, whereas Qdrant can be self-hosted.

weaviate-client

Weaviate-client is a JavaScript client for the Weaviate vector search engine. It offers similar functionalities such as managing collections and searching vectors. Weaviate also provides additional features like hybrid search and knowledge graph capabilities, which might not be present in Qdrant.

README

JavaScript Qdrant REST Client

This repository contains the REST client for the Qdrant vector search engine.

Installation

npm install @qdrant/js-client-rest
# or
yarn add @qdrant/js-client-rest
# or
pnpm i @qdrant/js-client-rest

Usage

Run the Qdrant Docker container:

docker run -p 6333:6333 qdrant/qdrant

Instantiate a client

import {QdrantClient} from '@qdrant/js-client-rest';

const client = new QdrantClient({host: '127.0.0.1', port: 6333});
// or
const client = new QdrantClient({url: 'http://127.0.0.1:6333'});

Make requests

Using one of the available facade methods:

try {
    const result = await client.getCollections();
    console.log('List of collections:', result.collections);
} catch (err) {
    console.error('Could not get collections:', err);
}

Or directly using an endpoint from the API:

await client.api('collections').getCollections();

Typed Error Handling

A non-ok fetch response throws a generic ApiError

But an Openapi document can declare a different response type for each status code, or a default error response type.

These can be accessed via a discriminated union on status, as in code snippet below:

const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create();
const addPet = fetcher.path('/pet').method('post').create();

try {
    const collection = await client.getCollection('bom-ada-002');
    // ...
} catch (e) {
    // check which operation threw the exception
    if (e instanceof client.getCollection.Error) {
        // get discriminated union error { status, data }
        const error = e.getActualType();
        // sort case's logic
        if (error.status === 400) {
            error.data.status.error; // only available for a 4xx responses
        } else if (error.status === 500) {
            error.data.status.error; // only available for a 500 response
        } else {
            error.data.result;
            // ...
        }
    }
}

Support

The REST implementation relies on the native fetch API, which is available in Deno and Node.js (starting on v18.0.0 without experimental flag). The Deno implementation supports HTTP/2 whereas Node.js is still lagging on the spec and provide only HTTP 1.1 support (this is due to the fact that under the hood Node.js still relies on undici).

Releases

Major and minor versions align with Qdrant's engine releases, whilst patch are reserved for fixes regarding the current minor release. Check out RELEASE.md for more info on release guidelines.

Contributing

These are the most relevant scripts for development:

• pnpm build: builds and bundles from TypeScript sources
• pnpm pre-check: type-checks sources
• pnpm pre-commit: same as pre-check, but for git hooks (husky)
• pnpm test: run unit tests
• pnpm test:integration: runs integration tests against a locally running Qdrant docker container
• pnpm codegen:openapi-typescript: updates generated TS schema from the latest openapi.json remote