ydb-qdrant 2.1.4 → 2.2.1

package/README.md

@@ -1,7 +1,11 @@
 <img src="https://ydb-qdrant.tech/logo.svg" alt="YDB Qdrant logo" height="56"> 
 
-[![CI](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-ydb-qdrant.yml/badge.svg)](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-ydb-qdrant.yml)
+[![Build](https://img.shields.io/github/actions/workflow/status/astandrik/ydb-qdrant/ci-build.yml?branch=main&label=build)](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-build.yml)
+[![Tests](https://img.shields.io/github/actions/workflow/status/astandrik/ydb-qdrant/ci-tests.yml?branch=main&label=tests)](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-tests.yml)
+[![Integration Tests](https://img.shields.io/github/actions/workflow/status/astandrik/ydb-qdrant/ci-integration.yml?branch=main&label=integration%20tests)](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-integration.yml)
+[![Coverage](https://coveralls.io/repos/github/astandrik/ydb-qdrant/badge.svg?branch=main)](https://coveralls.io/github/astandrik/ydb-qdrant?branch=main)
 [![npm version](https://img.shields.io/npm/v/ydb-qdrant.svg)](https://www.npmjs.com/package/ydb-qdrant)
+[![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Fastandrik%2Fydb--qdrant-blue?logo=docker)](https://github.com/users/astandrik/packages/container/package/ydb-qdrant)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
 # YDB Qdrant-compatible Service
@@ -83,7 +87,11 @@ The package entrypoint exports a programmatic API that mirrors the Qdrant HTTP s
 
   async function main() {
     // defaultTenant is optional; defaults to "default"
-    const client = await createYdbQdrantClient({ defaultTenant: "myapp" });
+    const client = await createYdbQdrantClient({
+      defaultTenant: "myapp",
+      endpoint: "grpcs://lb.etn01g9tcilcon2mrt3h.ydb.mdb.yandexcloud.net:2135",
+      database: "/ru-central1/b1ge4v9r1l3h1q4njclp/etn01g9tcilcon2mrt3h",
+    });
 
     await client.createCollection("documents", {
       vectors: {
@@ -111,7 +119,10 @@ The package entrypoint exports a programmatic API that mirrors the Qdrant HTTP s
 
 - Multi-tenant usage with `forTenant`:
   ```ts
-  const client = await createYdbQdrantClient();
+  const client = await createYdbQdrantClient({
+    endpoint: "grpcs://lb.etn01g9tcilcon2mrt3h.ydb.mdb.yandexcloud.net:2135",
+    database: "/ru-central1/b1ge4v9r1l3h1q4njclp/etn01g9tcilcon2mrt3h",
+  });
   const tenantClient = client.forTenant("tenant-a");
 
   await tenantClient.upsertPoints("sessions", {
@@ -121,6 +132,41 @@ The package entrypoint exports a programmatic API that mirrors the Qdrant HTTP s
 
 The request/response shapes follow the same schemas as the HTTP API (`CreateCollectionReq`, `UpsertPointsReq`, `SearchReq`, `DeletePointsReq`), so code written against the REST API can usually be translated directly to the library calls.
 
+### Example: in-process points search with a shared client
+
+In a typical server application you create a single `ydb-qdrant` client once and reuse it across requests. Then you can perform vector search (points search) directly in your business logic:
+
+```ts
+import {createYdbQdrantClient} from 'ydb-qdrant';
+
+let clientPromise: ReturnType<typeof createYdbQdrantClient> | null = null;
+
+async function getClient() {
+  if (!clientPromise) {
+    clientPromise = createYdbQdrantClient({
+      defaultTenant: 'myapp',
+      endpoint: 'grpcs://lb.etn01g9tcilcon2mrt3h.ydb.mdb.yandexcloud.net:2135',
+      database: '/ru-central1/b1ge4v9r1l3h1q4njclp/etn01g9tcilcon2mrt3h',
+    });
+  }
+  return clientPromise;
+}
+
+export async function searchDocuments(collection: string, queryEmbedding: number[], top: number) {
+  const client = await getClient();
+
+  const result = await client.searchPoints(collection, {
+    vector: queryEmbedding,
+    top,
+    with_payload: true,
+  });
+
+  return result.points ?? [];
+}
+```
+
+This pattern avoids running a separate HTTP service: vector search is executed directly against YDB via the shared `createYdbQdrantClient` instance, while the rest of your code works with plain TypeScript functions.
+
 ## Quick Start
 
 ### Use with IDE agents (Roo Code, Cline)
@@ -182,6 +228,84 @@ Health check:
 curl -s http://localhost:8080/health
 ```
 
+### Docker (self-hosted HTTP server)
+
+Published container: [`ghcr.io/astandrik/ydb-qdrant`](https://github.com/users/astandrik/packages/container/package/ydb-qdrant)
+
+**Option A – pull the published image (recommended)**
+
+```bash
+docker pull ghcr.io/astandrik/ydb-qdrant:latest
+
+docker run -d --name ydb-qdrant \
+  -p 8080:8080 \
+  -e YDB_ENDPOINT=grpcs://ydb.serverless.yandexcloud.net:2135 \
+  -e YDB_DATABASE=/ru-central1/<cloud>/<db> \
+  -e YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=/sa-key.json \
+  -v /abs/path/sa-key.json:/sa-key.json:ro \
+  ghcr.io/astandrik/ydb-qdrant:latest
+```
+
+**Option B – build the image locally**
+
+From the `ydb-qdrant/` directory:
+
+```bash
+docker build -t ydb-qdrant:latest .
+
+docker run -d --name ydb-qdrant \
+  -p 8080:8080 \
+  -e YDB_ENDPOINT=grpcs://ydb.serverless.yandexcloud.net:2135 \
+  -e YDB_DATABASE=/ru-central1/<cloud>/<db> \
+  -e YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=/sa-key.json \
+  -v /abs/path/sa-key.json:/sa-key.json:ro \
+  ydb-qdrant:latest
+```
+
+#### Docker Compose
+
+Example `docker-compose.yml` (can be used instead of raw `docker run`):
+
+```yaml
+services:
+  ydb-qdrant:
+    image: ghcr.io/astandrik/ydb-qdrant:latest
+    ports:
+      - "8080:8080"
+    env_file:
+      - .env
+    environment:
+      YDB_ENDPOINT: ${YDB_ENDPOINT}
+      YDB_DATABASE: ${YDB_DATABASE}
+      YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS: /sa-key.json
+      PORT: ${PORT:-8080}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+    volumes:
+      - ${YDB_SA_KEY_PATH}:/sa-key.json:ro
+```
+
+Example `.env` (per environment):
+
+```bash
+YDB_ENDPOINT=grpcs://ydb.serverless.yandexcloud.net:2135
+YDB_DATABASE=/ru-central1/<cloud>/<db>
+YDB_SA_KEY_PATH=/abs/path/to/ydb-sa.json
+PORT=8080
+LOG_LEVEL=info
+```
+
+- **Updating to a newer image with Compose** (no rebuild):
+  - Pull the latest tag and restart the service:
+    ```bash
+    docker-compose pull ydb-qdrant
+    docker-compose up -d ydb-qdrant
+    ```
+
+- **Environment**: uses the same variables as documented in **Configure credentials** (`YDB_ENDPOINT`, `YDB_DATABASE`, one of the `YDB_*_CREDENTIALS` options, optional `PORT`/`LOG_LEVEL`).
+- **Qdrant URL for tools/clients**: set to `http://localhost:8080` (or `http://<host>:<hostPort>` if you map a different port).
+- **Health check inside container**: `GET http://localhost:8080/health`.
+
+
 ## API Reference
 
 Create collection (PUT /collections/{collection}):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ydb-qdrant",
-  "version": "2.1.4",
+  "version": "2.2.1",
   "main": "dist/package/Api.js",
   "types": "dist/package/Api.d.ts",
   "exports": {
@@ -14,7 +14,9 @@
     "logo.svg"
   ],
   "scripts": {
-    "test": "vitest run",
+    "test": "vitest run --exclude \"test/integration/**\"",
+    "test:coverage": "vitest run --coverage --exclude \"test/integration/**\"",
+    "test:integration": "vitest run test/integration/YdbRealIntegration.test.ts",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "dev": "tsx watch src/index.ts",
@@ -67,6 +69,7 @@
     "@eslint/js": "^9.39.1",
     "@types/express": "^5.0.3",
     "@types/node": "^24.9.1",
+    "@vitest/coverage-v8": "^4.0.12",
     "docsify-cli": "^4.4.4",
     "eslint": "^9.39.1",
     "husky": "^9.1.7",
@@ -76,4 +79,4 @@
     "typescript-eslint": "^8.47.0",
     "vitest": "^4.0.12"
   }
-}
+}