{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true
  }
}

3. Environment variables - The client is configured programmatically, not via env vars, but a common pattern is:

const client = new QdrantClient({
  url: process.env.QDRANT_URL ?? 'http://127.0.0.1:6333',
  apiKey: process.env.QDRANT_API_KEY,
});

4. Import path alias (optional) - If you want short imports, add a path alias in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@qdrant/*": ["./src/qdrant/*"]
    }
  }
}

5. Run Qdrant locally (development):

docker run -p 6333:6333 qdrant/qdrant

Public API

QdrantClient

class QdrantClient {
  constructor(params?: QdrantClientParams): QdrantClient;
  // Collection operations, vector upsert/search, payload management, etc.
  // all available as async methods on this instance.
}

The primary entry point. Instantiate once per process and reuse. Pass url for simple local/cloud connections, or host/port/https for finer-grained control. Set checkCompatibility: false to suppress server version warnings.

QdrantClientParams

type QdrantClientParams = {
  port?: number | null;       // default: 6333
  apiKey?: string;            // enables HTTPS automatically when set
  https?: boolean;
  prefix?: string;
  url?: string;
  host?: string;
  timeout?: number;           // milliseconds, default: 300_000
  headers?: Record<string, number | string | string[] | undefined>;
  maxConnections?: number;
  checkCompatibility?: boolean; // default: true
};

Use this type to annotate factory functions or dependency-injection containers that create clients. When apiKey is present, HTTPS is enabled automatically unless https: false is explicitly set.

QdrantClientUnexpectedResponseError

class QdrantClientUnexpectedResponseError extends Error {
  static forResponse(response: ApiResponse<unknown>): QdrantClientUnexpectedResponseError;
}

Thrown when the server returns any status outside 200/201. Inspect error.message for a formatted status code, reason phrase, and truncated response body. Catch this to handle server-side validation failures or unexpected states.

QdrantClientTimeoutError

class QdrantClientTimeoutError extends Error {}

Thrown when a request exceeds the configured timeout. Catch separately from network errors to implement retry logic with backoff.

QdrantClientResourceExhaustedError

class QdrantClientResourceExhaustedError extends Error {
  retry_after: number; // seconds parsed from Retry-After header
}

Thrown on HTTP 429 responses that include a Retry-After header. Use error.retry_after to schedule a retry without guessing.

Working examples

Scenario - Connect and list collections

Connect to a local Qdrant instance and retrieve all existing collections to verify the connection is healthy.

import { QdrantClient } from './src/qdrant/index.js';

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

async function listCollections() {
  const result = await client.getCollections();
  console.log('Collections:', result.collections);
}

listCollections().catch(console.error);

Scenario - Connect to Qdrant Cloud with API key and timeout

Authenticate against Qdrant Cloud using an API key. The client enables HTTPS automatically. A 10-second timeout prevents hanging requests in serverless environments.

import { QdrantClient, QdrantClientTimeoutError } from './src/qdrant/index.js';

const client = new QdrantClient({
  url: 'https://your-cluster.us-east-0-1.aws.cloud.qdrant.io',
  apiKey: process.env.QDRANT_API_KEY,
  timeout: 10_000,
});

async function fetchCollections() {
  try {
    const result = await client.getCollections();
    return result.collections;
  } catch (err) {
    if (err instanceof QdrantClientTimeoutError) {
      console.error('Request timed out - retry with backoff');
    }
    throw err;
  }
}

Scenario - Handle rate limiting with retry-after

Wrap calls to respect the Retry-After header returned by Qdrant Cloud when quotas are exceeded.

import {
  QdrantClient,
  QdrantClientResourceExhaustedError,
} from './src/qdrant/index.js';

const client = new QdrantClient({
  url: process.env.QDRANT_URL ?? 'http://127.0.0.1:6333',
  apiKey: process.env.QDRANT_API_KEY,
});

async function withRetry<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err instanceof QdrantClientResourceExhaustedError) {
        const waitMs = err.retry_after * 1000;
        console.warn(`Rate limited. Retrying in ${err.retry_after}s`);
        await new Promise((r) => setTimeout(r, waitMs));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Max retries exceeded');
}

const collections = await withRetry(() => client.getCollections());
console.log(collections);

File walkthrough

• index.ts - Re-exports the three public surface areas: QdrantClient, QdrantClientParams, Schemas, and all error classes. Import exclusively from here.
• qdrant-client.ts - Implements QdrantClient. Reads config, constructs the REST URI, instantiates the OpenAPI client, and exposes high-level methods.
• api-client.ts - Creates the underlying Fetcher instance and attaches middleware for timeout (via AbortController) and error classification (429 → QdrantClientResourceExhaustedError, non-2xx → QdrantClientUnexpectedResponseError).
• client-version.ts - Exports PACKAGE_VERSION ('1.17.0') and ClientVersion utilities for parsing and comparing semver strings to gate compatibility warnings.
• errors.ts - Defines the error class hierarchy: CustomError base, then QdrantClientUnexpectedResponseError, QdrantClientConfigError, QdrantClientTimeoutError, QdrantClientResourceExhaustedError.
• dispatcher.ts - Internal; creates the request dispatcher consumed by api-client.ts. Not part of the public API.
• types.ts - Defines RestArgs (headers, timeout, connections) and re-exports Schemas from generated types.
• openapi/generated_schema.ts - Raw paths type map generated from Qdrant's OpenAPI spec. Updated when the spec changes.
• openapi/generated_client_type.ts - ClientApi interface enumerating every typed endpoint method.
• openapi/generated_api_client.ts - createClientApi factory that binds ClientApi methods to the fetch client.

Common pitfalls and fixes

• .js extension errors in Node ESM - The source imports with explicit .js extensions; set "moduleResolution": "bundler" or "node16" in tsconfig.json or TypeScript will fail to resolve them.
• fetch not defined (Node < 18) - The client relies on the global fetch; upgrade to Node.js >= 18 or polyfill with node-fetch assigned to globalThis.fetch.
• HTTPS not enabling - If you pass host + port instead of url, HTTPS is only auto-enabled when apiKey is set; pass https: true explicitly if needed without an API key.
• QdrantClientConfigError on construction - Thrown when conflicting connection params are supplied (e.g., both url and host). Read the message; it indicates the exact conflict.
• retry_after is seconds, not milliseconds - QdrantClientResourceExhaustedError.retry_after is already parsed as a number in seconds; multiply by 1000 for setTimeout.
• Generated files out of sync - If you upgrade Qdrant server to a new major version, regenerate openapi/generated_schema.ts and generated_api_client.ts from the updated OpenAPI spec to avoid type mismatches.

Vibe-coding prompt template

I have a copy of the Qdrant JS REST client source at `src/qdrant/` in my project.
The public API is documented in `USAGE.md` next to this source directory.
The upstream package is `@qdrant/monorepo@0.0.0` (js-client-rest).

Please integrate this client into my project step by step:

1. Read `USAGE.md` to understand the exported symbols and file layout.
2. Install the single required dependency: `@qdrant/openapi-typescript-fetch`.
3. Update my `tsconfig.json` so `.js` extension imports resolve (moduleResolution: bundler or node16).
4. Create a `src/services/qdrantService.ts` that:
   - Instantiates `QdrantClient` using environment variables `QDRANT_URL` and `QDRANT_API_KEY`.
   - Exports helper functions for listing collections, upserting vectors, and searching.
   - Wraps calls in try/catch blocks that handle `QdrantClientTimeoutError` and
     `QdrantClientResourceExhaustedError` (with retry logic using `retry_after`).
5. Show me where to add the env vars and how to call the service from an Express route.
Only use symbols and imports visible in `USAGE.md`. Do not invent methods.

License and credit

The upstream project is licensed under the Apache 2.0 License (see source/LICENSE if present, or refer to the upstream repository). This block is derived from @qdrant/js-client-rest as published in the qdrant-js monorepo.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。

Orama Full-Text Vector and Hybrid Search Engine

Automation, Utilities & Developer Tools

免费