@wiscale/velesdb-sdk 1.4.1 → 1.5.1

package/README.md

@@ -62,7 +62,7 @@ await db.init();
 
 // Same API as WASM backend
 await db.createCollection('products', { dimension: 1536 });
-await db.insert('products', { id: 'p1', vector: [...] });
+await db.insert('products', { id: 1, vector: [...] });
 const results = await db.search('products', query, { k: 10 });
 ```
 
@@ -120,6 +120,10 @@ await db.insert('docs', {
   vector: [0.1, 0.2, ...],  // or Float32Array
   payload: { key: 'value' } // optional metadata
 });
+
+// REST backend note:
+// IDs must be numeric and within JS safe integer range (0..Number.MAX_SAFE_INTEGER).
+// Non-numeric strings are rejected.
 ```
 
 ### `db.insertBatch(collection, documents)`
@@ -189,6 +193,12 @@ const results = await db.query(
   "SELECT * FROM docs WHERE VECTOR NEAR $v AND content MATCH 'rust' LIMIT 10",
   { v: queryVector }
 );
+
+// Aggregation query (returns { result, stats })
+const agg = await db.query(
+  'documents',
+  "SELECT COUNT(*) AS total FROM documents"
+);
 ```
 
 ### `db.multiQuerySearch(collection, vectors, options)` (v1.1.0+) ⭐ NEW
@@ -224,7 +234,7 @@ const results = await db.multiQuerySearch('docs', vectors, {
 });
 ```
 
-> **Note:** Multi-query fusion is only available with the REST backend.
+> **Note:** WASM supports `rrf`, `average`, `maximum`. `weighted` is REST-only.
 
 ### `db.isEmpty(collection)` (v0.8.11+)
 

package/dist/index.d.mts

@@ -8,6 +8,8 @@ type DistanceMetric = 'cosine' | 'euclidean' | 'dot' | 'hamming' | 'jaccard';
 type StorageMode = 'full' | 'sq8' | 'binary';
 /** Backend type for VelesDB connection */
 type BackendType = 'wasm' | 'rest';
+/** Numeric point ID required by velesdb-server REST API (`u64`). */
+type RestPointId = number;
 /** Configuration options for VelesDB client */
 interface VelesDBConfig {
     /** Backend type: 'wasm' for browser/Node.js, 'rest' for server */
@@ -53,6 +55,8 @@ interface Collection {
     /** Creation timestamp */
     createdAt?: Date;
 }
+/** Sparse vector: mapping from term/dimension index to weight */
+type SparseVector = Record<number, number>;
 /** Vector document to insert */
 interface VectorDocument {
     /** Unique identifier */
@@ -61,6 +65,8 @@ interface VectorDocument {
     vector: number[] | Float32Array;
     /** Optional payload/metadata */
     payload?: Record<string, unknown>;
+    /** Optional sparse vector for hybrid search */
+    sparseVector?: SparseVector;
 }
 /** Search options */
 interface SearchOptions {
@@ -70,6 +76,17 @@ interface SearchOptions {
     filter?: Record<string, unknown>;
     /** Include vectors in results (default: false) */
     includeVectors?: boolean;
+    /** Optional sparse vector for hybrid sparse+dense search */
+    sparseVector?: SparseVector;
+}
+/** PQ (Product Quantization) training options */
+interface PqTrainOptions {
+    /** Number of subquantizers (default: 8) */
+    m?: number;
+    /** Number of centroids per subquantizer (default: 256) */
+    k?: number;
+    /** Enable Optimized Product Quantization (default: false) */
+    opq?: boolean;
 }
 /** Fusion strategy for multi-query search */
 type FusionStrategy$1 = 'rrf' | 'average' | 'maximum' | 'weighted';
@@ -229,6 +246,68 @@ interface QueryResponse {
     /** Execution statistics */
     stats: QueryStats;
 }
+/** Aggregation query response from VelesQL (`GROUP BY`, `COUNT`, `SUM`, etc.). */
+interface AggregationQueryResponse {
+    /** Aggregation result payload as returned by server. */
+    result: Record<string, unknown> | unknown[];
+    /** Execution statistics */
+    stats: QueryStats;
+}
+/** Unified response type for `query()` (rows or aggregation). */
+type QueryApiResponse = QueryResponse | AggregationQueryResponse;
+/** Query explain request/response metadata */
+interface ExplainPlanStep {
+    step: number;
+    operation: string;
+    description: string;
+    estimatedRows: number | null;
+}
+interface ExplainCost {
+    usesIndex: boolean;
+    indexName: string | null;
+    selectivity: number;
+    complexity: string;
+}
+interface ExplainFeatures {
+    hasVectorSearch: boolean;
+    hasFilter: boolean;
+    hasOrderBy: boolean;
+    hasGroupBy: boolean;
+    hasAggregation: boolean;
+    hasJoin: boolean;
+    hasFusion: boolean;
+    limit: number | null;
+    offset: number | null;
+}
+interface ExplainResponse {
+    query: string;
+    queryType: string;
+    collection: string;
+    plan: ExplainPlanStep[];
+    estimatedCost: ExplainCost;
+    features: ExplainFeatures;
+}
+interface CollectionSanityChecks {
+    hasVectors: boolean;
+    searchReady: boolean;
+    dimensionConfigured: boolean;
+}
+interface CollectionSanityDiagnostics {
+    searchRequestsTotal: number;
+    dimensionMismatchTotal: number;
+    emptySearchResultsTotal: number;
+    filterParseErrorsTotal: number;
+}
+interface CollectionSanityResponse {
+    collection: string;
+    dimension: number;
+    metric: string;
+    pointCount: number;
+    isEmpty: boolean;
+    checks: CollectionSanityChecks;
+    diagnostics: CollectionSanityDiagnostics;
+    hints: string[];
+}
 /** Index type for property indexes */
 type IndexType = 'hash' | 'range';
 /** Index information */
@@ -295,7 +374,11 @@ interface IVelesDBBackend {
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
     /** Execute VelesQL multi-model query (EPIC-031 US-011) */
-    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryResponse>;
+    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
+    /** Explain a VelesQL query without executing it */
+    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    /** Run collection sanity checks */
+    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     /** Multi-query fusion search */
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     /** Check if collection is empty */
@@ -320,6 +403,10 @@ interface IVelesDBBackend {
     traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
     /** Get the in-degree and out-degree of a node */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    /** Train Product Quantization on a collection */
+    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
+    /** Stream-insert documents with backpressure support */
+    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
 }
 /** Error types */
 declare class VelesDBError extends Error {
@@ -336,6 +423,10 @@ declare class ValidationError extends VelesDBError {
 declare class NotFoundError extends VelesDBError {
     constructor(resource: string);
 }
+/** Thrown when stream insert receives 429 Too Many Requests (backpressure) */
+declare class BackpressureError extends VelesDBError {
+    constructor(message?: string);
+}
 
 /**
  * VelesDB Client - Unified interface for all backends
@@ -436,6 +527,7 @@ declare class VelesDB {
      */
     insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
     private validateDocument;
+    private validateRestPointId;
     /**
      * Search for similar vectors
      *
@@ -521,7 +613,7 @@ declare class VelesDB {
      * }
      * ```
      */
-    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryResponse>;
+    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     /**
      * Multi-query fusion search combining results from multiple query vectors
      *
@@ -549,7 +641,27 @@ declare class VelesDB {
      * });
      * ```
      */
+    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    /**
+     * Train Product Quantization on a collection
+     *
+     * @param collection - Collection name
+     * @param options - PQ training options (m, k, opq)
+     * @returns Server response message
+     */
+    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
+    /**
+     * Stream-insert documents with backpressure support
+     *
+     * Sends documents sequentially to respect server backpressure.
+     * Throws BackpressureError on 429 responses.
+     *
+     * @param collection - Collection name
+     * @param docs - Documents to insert
+     */
+    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
     /**
      * Check if a collection is empty
      *
@@ -703,6 +815,9 @@ declare class WasmBackend implements IVelesDBBackend {
     init(): Promise<void>;
     isInitialized(): boolean;
     private ensureInitialized;
+    private normalizeIdString;
+    private canonicalPayloadKeyFromResultId;
+    private canonicalPayloadKey;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
     getCollection(name: string): Promise<Collection | null>;
@@ -726,11 +841,14 @@ declare class WasmBackend implements IVelesDBBackend {
         vectorWeight?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    query(_collection: string, _queryString: string, _params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryResponse>;
+    query(_collection: string, _queryString: string, _params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryApiResponse>;
     multiQuerySearch(_collection: string, _vectors: Array<number[] | Float32Array>, _options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    queryExplain(_queryString: string, _params?: Record<string, unknown>): Promise<ExplainResponse>;
+    collectionSanity(_collection: string): Promise<CollectionSanityResponse>;
     isEmpty(collectionName: string): Promise<boolean>;
     flush(collectionName: string): Promise<void>;
     close(): Promise<void>;
+    private sparseVectorToArrays;
     private toNumericId;
     createIndex(_collection: string, _options: CreateIndexOptions): Promise<void>;
     listIndexes(_collection: string): Promise<IndexInfo[]>;
@@ -740,6 +858,8 @@ declare class WasmBackend implements IVelesDBBackend {
     getEdges(_collection: string, _options?: GetEdgesOptions): Promise<GraphEdge[]>;
     traverseGraph(_collection: string, _request: TraverseRequest): Promise<TraverseResponse>;
     getNodeDegree(_collection: string, _nodeId: number): Promise<DegreeResponse>;
+    trainPq(_collection: string, _options?: PqTrainOptions): Promise<string>;
+    streamInsert(_collection: string, _docs: VectorDocument[]): Promise<void>;
 }
 
 /**
@@ -769,6 +889,8 @@ declare class RestBackend implements IVelesDBBackend {
      * Returns bigint for large values, number for safe values.
      */
     private parseNodeId;
+    private parseRestPointId;
+    private isLikelyAggregationQuery;
     private request;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
@@ -776,6 +898,7 @@ declare class RestBackend implements IVelesDBBackend {
     listCollections(): Promise<Collection[]>;
     insert(collection: string, doc: VectorDocument): Promise<void>;
     insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+    private sparseVectorToRestFormat;
     search(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
     searchBatch(collection: string, searches: Array<{
         vector: number[] | Float32Array;
@@ -793,10 +916,14 @@ declare class RestBackend implements IVelesDBBackend {
         vectorWeight?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    query(collection: string, queryString: string, params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryResponse>;
+    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
+    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     isEmpty(collection: string): Promise<boolean>;
     flush(collection: string): Promise<void>;
+    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
+    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
     close(): Promise<void>;
     createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
     listIndexes(collection: string): Promise<IndexInfo[]>;
@@ -998,4 +1125,4 @@ declare class VelesQLBuilder {
  */
 declare function velesql(): VelesQLBuilder;
 
-export { type AddEdgeRequest, type BackendType, type Collection, type CollectionConfig, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type SearchOptions, type SearchResult, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };
+export { type AddEdgeRequest, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchResult, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };

package/dist/index.d.ts

@@ -8,6 +8,8 @@ type DistanceMetric = 'cosine' | 'euclidean' | 'dot' | 'hamming' | 'jaccard';
 type StorageMode = 'full' | 'sq8' | 'binary';
 /** Backend type for VelesDB connection */
 type BackendType = 'wasm' | 'rest';
+/** Numeric point ID required by velesdb-server REST API (`u64`). */
+type RestPointId = number;
 /** Configuration options for VelesDB client */
 interface VelesDBConfig {
     /** Backend type: 'wasm' for browser/Node.js, 'rest' for server */
@@ -53,6 +55,8 @@ interface Collection {
     /** Creation timestamp */
     createdAt?: Date;
 }
+/** Sparse vector: mapping from term/dimension index to weight */
+type SparseVector = Record<number, number>;
 /** Vector document to insert */
 interface VectorDocument {
     /** Unique identifier */
@@ -61,6 +65,8 @@ interface VectorDocument {
     vector: number[] | Float32Array;
     /** Optional payload/metadata */
     payload?: Record<string, unknown>;
+    /** Optional sparse vector for hybrid search */
+    sparseVector?: SparseVector;
 }
 /** Search options */
 interface SearchOptions {
@@ -70,6 +76,17 @@ interface SearchOptions {
     filter?: Record<string, unknown>;
     /** Include vectors in results (default: false) */
     includeVectors?: boolean;
+    /** Optional sparse vector for hybrid sparse+dense search */
+    sparseVector?: SparseVector;
+}
+/** PQ (Product Quantization) training options */
+interface PqTrainOptions {
+    /** Number of subquantizers (default: 8) */
+    m?: number;
+    /** Number of centroids per subquantizer (default: 256) */
+    k?: number;
+    /** Enable Optimized Product Quantization (default: false) */
+    opq?: boolean;
 }
 /** Fusion strategy for multi-query search */
 type FusionStrategy$1 = 'rrf' | 'average' | 'maximum' | 'weighted';
@@ -229,6 +246,68 @@ interface QueryResponse {
     /** Execution statistics */
     stats: QueryStats;
 }
+/** Aggregation query response from VelesQL (`GROUP BY`, `COUNT`, `SUM`, etc.). */
+interface AggregationQueryResponse {
+    /** Aggregation result payload as returned by server. */
+    result: Record<string, unknown> | unknown[];
+    /** Execution statistics */
+    stats: QueryStats;
+}
+/** Unified response type for `query()` (rows or aggregation). */
+type QueryApiResponse = QueryResponse | AggregationQueryResponse;
+/** Query explain request/response metadata */
+interface ExplainPlanStep {
+    step: number;
+    operation: string;
+    description: string;
+    estimatedRows: number | null;
+}
+interface ExplainCost {
+    usesIndex: boolean;
+    indexName: string | null;
+    selectivity: number;
+    complexity: string;
+}
+interface ExplainFeatures {
+    hasVectorSearch: boolean;
+    hasFilter: boolean;
+    hasOrderBy: boolean;
+    hasGroupBy: boolean;
+    hasAggregation: boolean;
+    hasJoin: boolean;
+    hasFusion: boolean;
+    limit: number | null;
+    offset: number | null;
+}
+interface ExplainResponse {
+    query: string;
+    queryType: string;
+    collection: string;
+    plan: ExplainPlanStep[];
+    estimatedCost: ExplainCost;
+    features: ExplainFeatures;
+}
+interface CollectionSanityChecks {
+    hasVectors: boolean;
+    searchReady: boolean;
+    dimensionConfigured: boolean;
+}
+interface CollectionSanityDiagnostics {
+    searchRequestsTotal: number;
+    dimensionMismatchTotal: number;
+    emptySearchResultsTotal: number;
+    filterParseErrorsTotal: number;
+}
+interface CollectionSanityResponse {
+    collection: string;
+    dimension: number;
+    metric: string;
+    pointCount: number;
+    isEmpty: boolean;
+    checks: CollectionSanityChecks;
+    diagnostics: CollectionSanityDiagnostics;
+    hints: string[];
+}
 /** Index type for property indexes */
 type IndexType = 'hash' | 'range';
 /** Index information */
@@ -295,7 +374,11 @@ interface IVelesDBBackend {
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
     /** Execute VelesQL multi-model query (EPIC-031 US-011) */
-    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryResponse>;
+    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
+    /** Explain a VelesQL query without executing it */
+    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    /** Run collection sanity checks */
+    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     /** Multi-query fusion search */
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     /** Check if collection is empty */
@@ -320,6 +403,10 @@ interface IVelesDBBackend {
     traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
     /** Get the in-degree and out-degree of a node */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    /** Train Product Quantization on a collection */
+    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
+    /** Stream-insert documents with backpressure support */
+    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
 }
 /** Error types */
 declare class VelesDBError extends Error {
@@ -336,6 +423,10 @@ declare class ValidationError extends VelesDBError {
 declare class NotFoundError extends VelesDBError {
     constructor(resource: string);
 }
+/** Thrown when stream insert receives 429 Too Many Requests (backpressure) */
+declare class BackpressureError extends VelesDBError {
+    constructor(message?: string);
+}
 
 /**
  * VelesDB Client - Unified interface for all backends
@@ -436,6 +527,7 @@ declare class VelesDB {
      */
     insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
     private validateDocument;
+    private validateRestPointId;
     /**
      * Search for similar vectors
      *
@@ -521,7 +613,7 @@ declare class VelesDB {
      * }
      * ```
      */
-    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryResponse>;
+    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     /**
      * Multi-query fusion search combining results from multiple query vectors
      *
@@ -549,7 +641,27 @@ declare class VelesDB {
      * });
      * ```
      */
+    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    /**
+     * Train Product Quantization on a collection
+     *
+     * @param collection - Collection name
+     * @param options - PQ training options (m, k, opq)
+     * @returns Server response message
+     */
+    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
+    /**
+     * Stream-insert documents with backpressure support
+     *
+     * Sends documents sequentially to respect server backpressure.
+     * Throws BackpressureError on 429 responses.
+     *
+     * @param collection - Collection name
+     * @param docs - Documents to insert
+     */
+    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
     /**
      * Check if a collection is empty
      *
@@ -703,6 +815,9 @@ declare class WasmBackend implements IVelesDBBackend {
     init(): Promise<void>;
     isInitialized(): boolean;
     private ensureInitialized;
+    private normalizeIdString;
+    private canonicalPayloadKeyFromResultId;
+    private canonicalPayloadKey;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
     getCollection(name: string): Promise<Collection | null>;
@@ -726,11 +841,14 @@ declare class WasmBackend implements IVelesDBBackend {
         vectorWeight?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    query(_collection: string, _queryString: string, _params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryResponse>;
+    query(_collection: string, _queryString: string, _params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryApiResponse>;
     multiQuerySearch(_collection: string, _vectors: Array<number[] | Float32Array>, _options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    queryExplain(_queryString: string, _params?: Record<string, unknown>): Promise<ExplainResponse>;
+    collectionSanity(_collection: string): Promise<CollectionSanityResponse>;
     isEmpty(collectionName: string): Promise<boolean>;
     flush(collectionName: string): Promise<void>;
     close(): Promise<void>;
+    private sparseVectorToArrays;
     private toNumericId;
     createIndex(_collection: string, _options: CreateIndexOptions): Promise<void>;
     listIndexes(_collection: string): Promise<IndexInfo[]>;
@@ -740,6 +858,8 @@ declare class WasmBackend implements IVelesDBBackend {
     getEdges(_collection: string, _options?: GetEdgesOptions): Promise<GraphEdge[]>;
     traverseGraph(_collection: string, _request: TraverseRequest): Promise<TraverseResponse>;
     getNodeDegree(_collection: string, _nodeId: number): Promise<DegreeResponse>;
+    trainPq(_collection: string, _options?: PqTrainOptions): Promise<string>;
+    streamInsert(_collection: string, _docs: VectorDocument[]): Promise<void>;
 }
 
 /**
@@ -769,6 +889,8 @@ declare class RestBackend implements IVelesDBBackend {
      * Returns bigint for large values, number for safe values.
      */
     private parseNodeId;
+    private parseRestPointId;
+    private isLikelyAggregationQuery;
     private request;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
@@ -776,6 +898,7 @@ declare class RestBackend implements IVelesDBBackend {
     listCollections(): Promise<Collection[]>;
     insert(collection: string, doc: VectorDocument): Promise<void>;
     insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+    private sparseVectorToRestFormat;
     search(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
     searchBatch(collection: string, searches: Array<{
         vector: number[] | Float32Array;
@@ -793,10 +916,14 @@ declare class RestBackend implements IVelesDBBackend {
         vectorWeight?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    query(collection: string, queryString: string, params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryResponse>;
+    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
+    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     isEmpty(collection: string): Promise<boolean>;
     flush(collection: string): Promise<void>;
+    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
+    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
     close(): Promise<void>;
     createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
     listIndexes(collection: string): Promise<IndexInfo[]>;
@@ -998,4 +1125,4 @@ declare class VelesQLBuilder {
  */
 declare function velesql(): VelesQLBuilder;
 
-export { type AddEdgeRequest, type BackendType, type Collection, type CollectionConfig, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type SearchOptions, type SearchResult, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };
+export { type AddEdgeRequest, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchResult, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };