ydb-qdrant 2.1.4 → 2.2.0

package/README.md

@@ -83,7 +83,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 +115,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 +128,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 +224,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   # or: docker-compose pull ydb-qdrant
+    docker compose up -d ydb-qdrant  # or: 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.0",
   "main": "dist/package/Api.js",
   "types": "dist/package/Api.d.ts",
   "exports": {