@rushdb/javascript-sdk 1.19.0 → 2.0.0

package/README.md

@@ -2,156 +2,189 @@
 
 ![RushDB Logo](https://raw.githubusercontent.com/rush-db/rushdb/main/rushdb-logo.svg)
 
-# 🚀 RushDB SDK for JavaScript and TypeScript
+# RushDB — JavaScript & TypeScript SDK
 
-### The Modern Graph Database Client for Web & Node.js
+### The memory layer for AI agents and apps.
+
+Push any JSON. Get graph relationships and vector search — automatically.
+No schema. No pipeline. No glue code.
 
 [![NPM Version](https://img.shields.io/npm/v/%40rushdb%2Fjavascript-sdk)](https://www.npmjs.com/package/@rushdb/javascript-sdk)
-[![NPM License](https://img.shields.io/npm/l/%40rushdb%2Fjavascript-sdk)](#license "Go to license section")
 [![NPM Downloads](https://img.shields.io/npm/dw/%40rushdb%2Fjavascript-sdk)](https://www.npmjs.com/package/@rushdb/javascript-sdk)
-[![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40rushdb%2Fjavascript-sdk)](https://bundlephobia.com/package/@rushdb/javascript-sdk)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/%40rushdb%2Fjavascript-sdk)](https://bundlephobia.com/package/@rushdb/javascript-sdk)
+[![License](https://img.shields.io/npm/l/%40rushdb%2Fjavascript-sdk)](#license)
+[![Made with Node](https://img.shields.io/badge/dynamic/json?label=node&query=%24.engines%5B%22node%22%5D&url=https%3A%2F%2Fraw.githubusercontent.com%2Frush-db%2Frushdb%2Fmain%2Fpackage.json)](https://nodejs.org)
 
-[![Made with Node](https://img.shields.io/badge/dynamic/json?label=node&query=%24.engines%5B%22node%22%5D&url=https%3A%2F%2Fraw.githubusercontent.com%2Frush-db%2Frushdb%2Fmain%2Fpackage.json)](https://nodejs.org "Go to Node.js homepage")
-[![Package - Typescript](https://img.shields.io/github/package-json/dependency-version/rush-db/rushdb/dev/typescript?logo=typescript&logoColor=white)](https://www.npmjs.com/package/typescript "Go to TypeScript on NPM")
+[🌐 Website](https://rushdb.com) • [📖 Documentation](https://docs.rushdb.com) • [☁️ Cloud](https://app.rushdb.com) • [🔍 Examples](https://github.com/rush-db/examples)
 
-[🌐 Website](https://rushdb.com) • [📖 Documentation](https://docs.rushdb.com) • [☁️ Cloud Platform](https://app.rushdb.com) • [🔍 Examples](https://github.com/rush-db/examples)
 </div>
 
-## ✨ Highlights
-
 ---
 
-- **🔌 No Configuration Needed**: Plug-and-play design requires minimal setup to get started
-- **🛡️ Automatic Type Inference**: Enjoy seamless type safety with automatic TypeScript inference
-- **🔄 Isomorphic Architecture**: Fully compatible with both server and browser environments
-- **⚡ Zero Dependencies**: Lightweight (just 6.9KB gzipped) and efficient with no external dependencies
+## Why RushDB
+
+Agents need memory. Apps need connected data. The standard answer involves multiple databases, schema design, and an embedding pipeline before you write a single useful line of business logic.
 
+RushDB skips all of that:
 
-## 📦 Installation
+- **Managed embeddings** — mark a property for indexing once; every write is auto-embedded server-side
+- **Graph auto-structured** — nested JSON becomes a traversable graph; no manual edge creation
+- **Semantic + graph in one query** — filter by relationships, rank by meaning, compute metrics — one call (use select/groupBy)
+- **Zero schema** — push any shape; RushDB infers types and links records
+- **6.9KB gzipped** — zero runtime dependencies
+- **Isomorphic** — Node.js and browser
 
 ---
-```bash
-# NPM
-npm install @rushdb/javascript-sdk
 
-# YARN
-yarn add @rushdb/javascript-sdk
+## Installation
 
-# PNPM
-pnpm add @rushdb/javascript-sdk
+```bash
+npm install @rushdb/javascript-sdk
+# yarn add @rushdb/javascript-sdk
+# pnpm add @rushdb/javascript-sdk
 ```
 
+---
 
-## 🚀 Usage
+## Agent memory in 3 lines
 
----
+Get an API key at [app.rushdb.com](https://app.rushdb.com).
 
-1. **Obtain API Key**: Grab one from the [RushDB Cloud Dashboard](https://app.rushdb.com).
-2. **Build anything**: Easily push, search, and manage relationships within your data.
+```typescript
+import RushDB from '@rushdb/javascript-sdk'
+
+const db = new RushDB('RUSHDB_API_KEY')
+
+// 1. One-time: index a property for semantic search
+await db.ai.indexes.create({ label: 'MEMORY', propertyName: 'output' })
+
+// 2. Store — no embedder needed, server handles it
+await db.records.create({
+  label: 'MEMORY',
+  data: {
+    agent_id: 'agent-42',
+    session_id: 'sess-001',
+    action: 'summarized',
+    topic: 'Q4 results',
+    output: summaryText,
+  },
+})
 
-### Quick Example
-```ts
-import RushDB from '@rushdb/javascript-sdk';
+// 3. Recall by meaning, scoped by graph
+const memories = await db.ai.search({
+  labels: ['MEMORY'],
+  propertyName: 'output',
+  query: 'what did we decide about Q4?',
+  where: { agent_id: 'agent-42' },
+  limit: 10,
+})
+```
 
-// Setup SDK
-const db = new RushDB("RUSHDB_API_KEY");
-// Default URL is "https://api.rushdb.com/api/v1". See SDK Configuration for more options.
+---
 
-// Push any data, and RushDB will automatically flatten it into Records
-// and establish relationships between them accordingly.
-await db.records.createMany({
-  label: "COMPANY",
+## Graph traversal
+
+```typescript
+// Push nested JSON — relationships created automatically
+await db.records.importJson({
+  label: 'COMPANY',
   payload: {
-    name: 'Google LLC',
-    address: '1600 Amphitheatre Parkway, Mountain View, CA 94043, USA',
-    foundedAt: '1998-09-04T00:00:00.000Z',
-    rating: 4.9,
+    name: 'Acme Corp',
     DEPARTMENT: [{
-      name: 'Research & Development',
-      description: 'Innovating and creating advanced technologies for AI, cloud computing, and consumer devices.',
-      PROJECT: [{
-        name: 'Bard AI',
-        description: 'A state-of-the-art generative AI model designed for natural language understanding and creation.',
-        active: true,
-        budget: 1200000000,
-        EMPLOYEE: [{
-          name: 'Jeff Dean',
-          position: 'Head of AI Research',
-          email: 'jeff@google.com',
-          dob: '1968-07-16T00:00:00.000Z',
-          salary: 3000000
-        }]
+      name: 'Engineering',
+      EMPLOYEE: [{
+        name: 'Alice',
+        role: 'Staff Engineer',
       }]
     }]
   }
 })
 
-
-// Find Records by specific criteria
-const matchedEmployees = await db.records.find({
+// Traverse the auto-created graph
+const engineers = await db.records.find({
   labels: ['EMPLOYEE'],
   where: {
-    position: { $contains: 'AI' },
-    PROJECT: {
-      DEPARTMENT: {
-        COMPANY: {
-          rating: { $gte: 4 }
-        }
-      }
-    }
-  }
+    role: { $contains: 'Engineer' },
+    DEPARTMENT: { COMPANY: { name: 'Acme Corp' } },
+  },
 })
 
-const company = await db.records.findUniq({
-  labels: ['COMPANY'],
+// Constrain by relationship type and direction
+const authoredPosts = await db.records.find({
+  labels: ['USER'],
   where: {
-    name: 'Google LLC'
-  }
+    POST: {
+      $relation: { type: 'AUTHORED', direction: 'out' },
+      title: { $contains: 'graph' },
+    },
+  },
+  limit: 10,
 })
 
-// Manage relationships
-await company.attach(matchedEmployees, { type: "WORKING_AT" })
+// Manage relationships explicitly
+const company = await db.records.findUniq({
+  labels: ['COMPANY'],
+  where: { name: 'Acme Corp' },
+})
+await company.attach(engineers, { type: 'EMPLOYS' })
 ```
 
-## ⚙️ SDK Configuration
 ---
-The SDK is designed to be flexible. You can provide configuration options when initializing `RushDB` to customize its behavior, such as the API endpoint or request timeouts.
 
-```typescript
-import RushDB from '@rushdb/javascript-sdk';
+## Unified query API
 
-// Example: Initialize with a custom URL and timeout
-const db = new RushDB('RUSHDB_API_KEY', {
-  url: 'http://your-custom-rushdb-server.com/api/v1', // Default is 'https://api.rushdb.com/api/v1'
-  timeout: 30000 // 30 seconds
-});
+One JSON structure works for records, labels, properties, relationships, aggregations, and vector search:
+
+```typescript
+const result = await db.records.find({
+  labels: ['TRANSACTION'],
+  where: {
+    status: 'posted',
+    amount: { $gte: 100 },
+  },
+  select: {
+    total: { $sum: '$record.amount' },
+  },
+  groupBy: ['$record.category'],
+  // Legacy: The aggregate clause is deprecated and should only be used for vector similarity until select supports it.
+  orderBy: { amount: 'desc' },
+  limit: 50,
+})
 ```
 
-The `RushDB` constructor accepts an optional second argument for configuration. Key options include:
-- `url`: The complete URL to the RushDB API.
-- Alternatively, `host`, `port`, and `protocol` can be specified individually.
-- `timeout`: Request timeout in milliseconds (default: 10000).
-- `httpClient`: For advanced use cases, provide a custom HTTP client implementation.
-- `logger`: Implement a custom logger for debugging or monitoring.
-- `options.allowForceDelete`: Set to `true` to enable deleting all records without specifying criteria (defaults to `false` for safety).
+The same shape works with `db.labels.find()`, `db.properties.find()`, and `db.relationships.find()` — learn once, works everywhere.
 
-For a comprehensive guide on all available configuration options, please refer to the [SDK Configuration Documentation](https://docs.rushdb.com/typescript-sdk/introduction#sdk-configuration-options).
+---
 
-<div align="center">
-<b>You're Awesome!</b>  🚀
-</div>
+## SDK configuration
 
----
+```typescript
+import RushDB from '@rushdb/javascript-sdk'
+
+const db = new RushDB('RUSHDB_API_KEY', {
+  // Override for self-hosted or staging
+  url: 'http://your-rushdb-server.com/api/v1',
+  timeout: 30000,
+})
+```
 
-<div align="center" style="margin-top: 20px">
+Key options:
+- `url` — full API URL (default: `https://api.rushdb.com/api/v1`)
+- `host`, `port`, `protocol` — alternative to `url`
+- `timeout` — request timeout in ms (default: 10000)
+- `httpClient` — custom HTTP client for advanced use
+- `options.allowForceDelete` — allow deleting all records without criteria (default: false)
 
-> 📚 Check the [Complete Documentation](https://docs.rushdb.com/typescript-sdk/introduction) and [Examples Repository](https://github.com/rush-db/examples) to learn more!
+Full config reference: [docs.rushdb.com/typescript-sdk/introduction#sdk-configuration-options](https://docs.rushdb.com/typescript-sdk/introduction#sdk-configuration-options)
 
-</div>
+---
 
+## Documentation
 
-## 🤝 Contributing
+[docs.rushdb.com/typescript-sdk](https://docs.rushdb.com/typescript-sdk/introduction) — full API reference, examples, transactions, CSV import, and more.
 
 ---
-We welcome contributions! See our [CONTRIBUTING.md](CONTRIBUTING.md) guide for details.
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.

package/dist/api/api.d.ts

@@ -4,6 +4,7 @@ import { DBRecordInstance, DBRecordsArrayInstance } from '../sdk/record.js';
 import type { SDKConfig } from '../sdk/types.js';
 import type { FlatObject, InferSchemaTypesWrite, MaybeArray, OrderDirection, Property, PropertyDraft, PropertyValuesData, Schema, SearchQuery, Where } from '../types/index.js';
 import type { ApiResponse } from './types.js';
+import type { CreateEmbeddingIndexParams, EmbeddingIndex, EmbeddingIndexStats, SemanticSearchParams, UpsertEmbeddingVectorsParams, UpsertEmbeddingVectorsResult, VectorEntry } from './types.js';
 import { createFetcher } from '../network/index.js';
 import { Transaction } from '../sdk/transaction.js';
 export declare class RestAPI {
@@ -61,10 +62,11 @@ export declare class RestAPI {
          * @returns Promise resolving to the created DBRecordInstance
          * @throws Error if data is not a flat object and createMany should be used instead
          */
-        create: <S extends Schema = any>({ label, data: rawData, options }: {
+        create: <S extends Schema = any>({ label, data: rawData, options, vectors }: {
             label: string;
             data: InferSchemaTypesWrite<S> | Array<PropertyDraft>;
             options?: Omit<DBRecordCreationOptions, "returnResult" | "capitalizeLabels" | "relationshipType">;
+            vectors?: VectorEntry[];
         }, transaction?: Transaction | string) => Promise<DBRecordInstance<S>>;
         /**
          * Creates multiple flat records in a single operation.
@@ -83,6 +85,11 @@ export declare class RestAPI {
             label: string;
             data: Array<InferSchemaTypesWrite<S>>;
             options?: DBRecordCreationOptions;
+            /**
+             * Per-row inline vectors for external embedding indexes.
+             * `vectors[i]` is applied to `data[i]`. Its length must not exceed `data.length`.
+             */
+            vectors?: VectorEntry[][];
         }, transaction?: Transaction | string) => Promise<DBRecordsArrayInstance<S>>;
         /**
          * Import nested or complex JSON payloads.
@@ -127,6 +134,12 @@ export declare class RestAPI {
                 newline?: string;
             };
             parentId?: string;
+            /**
+             * Per-row inline vectors for external embedding indexes.
+             * `vectors[i]` is applied to CSV row `i` (0-based, after header).
+             * Its length must not exceed the number of data rows — validated server-side.
+             */
+            vectors?: VectorEntry[][];
         }, transaction?: Transaction | string) => Promise<DBRecordsArrayInstance<S>>;
         /**
          * Deletes records matching the search query
@@ -198,11 +211,12 @@ export declare class RestAPI {
          * @returns Promise resolving to updated DBRecordInstance
          * @throws Error if data is not a flat object
          */
-        set: <S extends Schema = any>({ target, label, data: rawData, options }: {
+        set: <S extends Schema = any>({ target, label, data: rawData, options, vectors }: {
             target: DBRecordTarget;
             label: string;
             data: InferSchemaTypesWrite<S> | Array<PropertyDraft>;
             options?: Omit<DBRecordCreationOptions, "returnResult" | "capitalizeLabels" | "relationshipType">;
+            vectors?: VectorEntry[];
         }, transaction?: Transaction | string) => Promise<DBRecordInstance<S, SearchQuery<S>>>;
         /**
          * Updates record data (partial update)
@@ -232,13 +246,14 @@ export declare class RestAPI {
          * @param options.mergeStrategy - 'rewrite' | 'append'
          * @param transaction - Optional transaction for atomic operations
          */
-        upsert: <S extends Schema = any>({ label, data: rawData, options }: {
+        upsert: <S extends Schema = any>({ label, data: rawData, options, vectors }: {
             label?: string;
             data: InferSchemaTypesWrite<S> | Array<PropertyDraft>;
             options?: Omit<DBRecordCreationOptions, "returnResult" | "capitalizeLabels" | "relationshipType"> & {
                 mergeBy?: string[];
                 mergeStrategy?: "rewrite" | "append";
             };
+            vectors?: VectorEntry[];
         }, transaction?: Transaction | string) => Promise<DBRecordInstance<S>>;
     };
     /**
@@ -336,6 +351,7 @@ export declare class RestAPI {
             metadata?: string;
             name: string;
             type: import("../types/value.js").PropertyType;
+            recordsCount?: number;
         } & {
             id: string;
         } & PropertyValuesData>>;
@@ -397,26 +413,105 @@ export declare class RestAPI {
             selfHosted: boolean;
             customDB?: boolean;
             managedDB?: boolean;
-            planType?: import("../sdk/types.js").PlanType;
         } | undefined>>;
     };
     query: {
         /**
-         * Runs a raw Cypher query against the connected Neo4j database.
+         * Executes a raw query against the underlying database engine.
          *
          * NOTE: This endpoint is cloud-only — available only on the RushDB managed
          * service or when your project is connected to a custom database through
          * RushDB Cloud. It will not work for self-hosted or local-only deployments.
          *
-         * @param param0 - Object containing the Cypher query and optional params
-         * @param param0.query - Cypher query string to execute
+         * @param param0 - Object containing the query and optional params
+         * @param param0.query - Query string to execute
          * @param param0.params - Optional parameters to pass to the query
          * @param transaction - Optional transaction id or Transaction instance to run the query in
-         * @returns ApiResponse<any> - Raw result returned by the server (Neo4j driver result wrapped in ApiResponse)
+         * @returns ApiResponse<any> - Raw result returned by the server (wrapped in ApiResponse)
          */
         raw: <T extends unknown = any>({ query, params }: {
             query: string;
             params?: FlatObject;
         }, transaction?: Transaction | string) => Promise<ApiResponse<T>>;
     };
+    /**
+     * API methods for AI-assisted graph exploration.
+     */
+    ai: {
+        /**
+         * Returns the full graph ontology as structured JSON.
+         * Each item contains the label name, record count, properties with value ranges/samples,
+         * and cross-label relationships with direction.
+         * Properties may include a `vectorIndexes` array when one or more embedding indexes
+         * exist for that property — a non-empty array means the property is queryable with
+         * `db.ai.search()`. Each entry exposes: id, sourceType, similarityFunction, dimensions,
+         * status, and modelKey.
+         * Use property `id` fields to pass to db.properties.values() for deeper drill-down.
+         * @param params - Optional filter. `labels` scopes to specific labels only.
+         *                 `force: true` bypasses the 1-hour ontology cache and triggers a full recalculation.
+         * @param transaction - Optional transaction for atomic operations
+         */
+        getOntology: (params?: {
+            labels?: string[];
+            force?: boolean;
+        }, transaction?: Transaction | string) => Promise<ApiResponse<unknown[]>>;
+        /**
+         * Returns the full graph ontology as compact Markdown tables.
+         * Token-efficient — intended for direct LLM consumption.
+         * Includes: labels with counts, properties with types and value ranges/samples,
+         * cross-label relationship map, and a "Semantic Search" column per property that shows
+         * `sourceType similarityFunction dimensionsd [status]` (e.g. `managed cosine 1536d [ready]`)
+         * for indexed properties, or `—` when no embedding index exists.
+         * @param params - Optional filter. `labels` scopes to specific labels only.
+         *                 `force: true` bypasses the 1-hour ontology cache and triggers a full recalculation.
+         * @param transaction - Optional transaction for atomic operations
+         */
+        getOntologyMarkdown: (params?: {
+            labels?: string[];
+            force?: boolean;
+        }, transaction?: Transaction | string) => Promise<ApiResponse<string>>;
+        /**
+         * Embedding Index management methods.
+         */
+        indexes: {
+            /**
+             * Lists all embedding index policies configured for the current project.
+             */
+            find: () => Promise<ApiResponse<EmbeddingIndex[]>>;
+            /**
+             * Creates a new embedding index policy for a string property.
+             * @param params.propertyName - Name of the property to index
+             * @param params.modelKey - Embedding model identifier (e.g. 'text-embedding-3-small')
+             * @param params.dimensions - Vector dimensionality produced by the model
+             */
+            create: (params: CreateEmbeddingIndexParams) => Promise<ApiResponse<EmbeddingIndex>>;
+            /**
+             * Upserts external vectors for a specific embedding index.
+             * @param id - The target embedding index ID
+             * @param params.items - Array of { recordId, vector }
+             */
+            upsertVectors: (id: string, params: UpsertEmbeddingVectorsParams) => Promise<ApiResponse<UpsertEmbeddingVectorsResult>>;
+            /**
+             * Deletes an embedding index policy by ID.
+             * @param id - The ID of the embedding index to delete
+             */
+            delete: (id: string) => Promise<ApiResponse<{
+                deleted: boolean;
+            }>>;
+            /**
+             * Returns Neo4j-level statistics for an embedding index.
+             * @param id - The ID of the embedding index
+             */
+            stats: (id: string) => Promise<ApiResponse<EmbeddingIndexStats>>;
+        };
+        /**
+         * Performs semantic (vector) search over records whose `propertyName` has been indexed.
+         *
+         * RushDB performs exact search: candidates are narrowed via MATCH/WHERE first,
+         * then ranked by similarity. You can pass either query text or queryVector.
+         *
+         * @param params - Search parameters including the query text, property name, and optional filters
+         */
+        search: <S extends Schema = any>(params: SemanticSearchParams) => Promise<DBRecordsArrayInstance<S>>;
+    };
 }

package/dist/api/index.d.ts

@@ -1,2 +1,2 @@
 export { RestAPI } from './api.js';
-export { ApiResponse } from './types.js';
+export { ApiResponse, CreateEmbeddingIndexParams, EmbeddingIndex, EmbeddingIndexStats, SemanticSearchParams, SemanticSearchResult, UpsertEmbeddingVectorItem, UpsertEmbeddingVectorsParams, UpsertEmbeddingVectorsResult } from './types.js';

package/dist/api/types.d.ts

@@ -1,5 +1,107 @@
+import type { DBRecord } from '../sdk/record.js';
+import type { Schema } from '../types/index.js';
 export type ApiResponse<T, E = Record<string, any>> = {
     data: T;
     success: boolean;
     total?: number;
 } & E;
+/** An embedding index policy stored in RushDB. */
+export type EmbeddingIndex = {
+    id: string;
+    projectId: string;
+    /** Neo4j label this index is scoped to (e.g. "Book"). */
+    label: string;
+    propertyName: string;
+    modelKey: string;
+    sourceType: 'managed' | 'external';
+    similarityFunction: 'cosine' | 'euclidean';
+    dimensions: number;
+    vectorPropertyName: string;
+    enabled: boolean;
+    /** 'pending' | 'indexing' | 'awaiting_vectors' | 'ready' | 'error' */
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+};
+/** Parameters for creating a new embedding index. */
+export type CreateEmbeddingIndexParams = {
+    /** Neo4j label to scope this index to (e.g. "Book", "Task"). */
+    label: string;
+    propertyName: string;
+    sourceType?: 'managed' | 'external';
+    /**
+     * Shorthand for `sourceType: 'external'`.
+     * When `true`, the index will be created with `sourceType: 'external'` regardless of the `sourceType` field.
+     */
+    external?: boolean;
+    similarityFunction?: 'cosine' | 'euclidean';
+    dimensions?: number;
+};
+/**
+ * A single vector entry for inline vector upsert.
+ * Provided alongside record data in create/upsert/set calls.
+ */
+export type VectorEntry = {
+    /** Name of the property whose embedding index should be written to. */
+    propertyName: string;
+    /** The embedding vector to store. Its length must match the index dimensions. */
+    vector: number[];
+    /**
+     * Required when two indexes share the same `propertyName` and `dimensions` but differ in
+     * `similarityFunction`. Omit when there is only one matching index.
+     */
+    similarityFunction?: 'cosine' | 'euclidean';
+};
+export type UpsertEmbeddingVectorItem = {
+    recordId: string;
+    vector: number[];
+};
+export type UpsertEmbeddingVectorsParams = {
+    items: UpsertEmbeddingVectorItem[];
+};
+export type UpsertEmbeddingVectorsResult = {
+    updated: number;
+    requested: number;
+};
+/** Neo4j-level stats for an embedding index. */
+export type EmbeddingIndexStats = {
+    totalRecords: number;
+    indexedRecords: number;
+};
+/** Parameters for semantic (vector) search over an embedding index. */
+export type SemanticSearchParams = {
+    /** Name of the indexed property to search against. */
+    propertyName: string;
+    /** Free-text query that will be embedded and compared against indexed vectors. */
+    query?: string;
+    /** External vector query. Use instead of query text for external indexes. */
+    queryVector?: number[];
+    /**
+     * One or more Neo4j labels to scope the search.
+     * The first label is used to resolve which embedding index to use.
+     * Required — always provide at least one label.
+     */
+    labels: string[];
+    sourceType?: 'managed' | 'external';
+    similarityFunction?: 'cosine' | 'euclidean';
+    dimensions?: number;
+    /**
+     * Optional filter applied before cosine scoring.
+     * Candidates are narrowed via MATCH/WHERE and then ranked by similarity.
+     */
+    where?: Record<string, unknown>;
+    /** Number of results to skip for pagination (default 0). */
+    skip?: number;
+    /** Maximum number of results to return (default 20). */
+    limit?: number;
+};
+/**
+ * A record returned by db.ai.search().
+ * Identical to DBRecord but with __score guaranteed present — never optional.
+ * __score is the cosine similarity between the query vector and this record's embedding (0–1,
+ * higher = more similar). It is only injected by the semantic search path; regular
+ * db.records.find() / db.records.search() results are plain DBRecord and never carry __score.
+ */
+export type SemanticSearchResult<S extends Schema = Schema> = DBRecord<S> & {
+    readonly __score: number;
+};

package/dist/common/constants.d.ts

@@ -5,5 +5,4 @@ export declare const PROPERTY_TYPE_DATETIME: "datetime";
 export declare const PROPERTY_TYPE_BOOLEAN: "boolean";
 export declare const PROPERTY_TYPE_NUMBER: "number";
 export declare const PROPERTY_TYPE_NULL: "null";
-export declare const PROPERTY_TYPE_VECTOR: "vector";
-export declare const PROPERTY_TYPES: ("string" | "number" | "boolean" | "datetime" | "null" | "vector")[];
+export declare const PROPERTY_TYPES: ("string" | "number" | "boolean" | "datetime" | "null")[];