agentdb 1.0.0

package/dist/cli/query/query-builder.d.ts

@@ -0,0 +1,322 @@
+/**
+ * VectorQueryBuilder - Fluent API for building complex vector search queries
+ * Provides type-safe filtering, sorting, and pagination with SQL injection protection
+ */
+import { SearchResult, SimilarityMetric } from '../types';
+import { SQLiteVectorDB } from '../core/vector-db';
+/**
+ * Supported comparison operators
+ */
+export type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'IN';
+/**
+ * Sort direction
+ */
+export type SortDirection = 'asc' | 'desc';
+/**
+ * VectorQueryBuilder - Fluent API for complex vector queries
+ *
+ * @template T - Type of metadata object
+ *
+ * @example
+ * ```typescript
+ * const results = await db.query()
+ *   .similarTo(queryVector)
+ *   .where('metadata.category', '=', 'tech')
+ *   .whereBetween('metadata.year', 2020, 2024)
+ *   .orderBySimilarity('asc')
+ *   .limit(10)
+ *   .execute();
+ * ```
+ */
+export declare class VectorQueryBuilder<T = any> {
+    private db;
+    private queryVector?;
+    private queryId?;
+    private k;
+    private filters;
+    private orders;
+    private limitValue?;
+    private offsetValue;
+    private metric;
+    private threshold;
+    private rawSQL?;
+    private rawParams?;
+    constructor(db: SQLiteVectorDB);
+    /**
+     * Search for vectors similar to the given vector
+     *
+     * @param vector - Query vector
+     * @param k - Number of results to retrieve (default: 10)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo([0.1, 0.2, 0.3], 5)
+     * ```
+     */
+    similarTo(vector: number[], k?: number): this;
+    /**
+     * Search for vectors similar to a vector already in the database
+     *
+     * @param id - ID of the reference vector
+     * @param k - Number of results to retrieve (default: 10)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarToId('vector-123', 5)
+     * ```
+     */
+    similarToId(id: string, k?: number): this;
+    /**
+     * Add a filter condition
+     *
+     * @param field - Field name (use 'metadata.field' for metadata)
+     * @param op - Comparison operator
+     * @param value - Value to compare against
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .where('metadata.category', '=', 'tech')
+     *   .where('metadata.year', '>', 2020)
+     * ```
+     */
+    where(field: string, op: Operator, value: any): this;
+    /**
+     * Filter where field is IN a set of values
+     *
+     * @param field - Field name
+     * @param values - Array of values
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .whereIn('metadata.tags', ['typescript', 'javascript'])
+     * ```
+     */
+    whereIn(field: string, values: any[]): this;
+    /**
+     * Filter where field is between min and max (inclusive)
+     *
+     * @param field - Field name
+     * @param min - Minimum value
+     * @param max - Maximum value
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .whereBetween('metadata.year', 2020, 2024)
+     * ```
+     */
+    whereBetween(field: string, min: any, max: any): this;
+    /**
+     * Filter metadata field (alias for where with 'metadata.' prefix)
+     *
+     * @param path - Metadata field path
+     * @param op - Comparison operator
+     * @param value - Value to compare against
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .whereMetadata('author.verified', '=', true)
+     * ```
+     */
+    whereMetadata(path: string, op: Operator, value: any): this;
+    /**
+     * Set similarity metric
+     *
+     * @param metric - Similarity metric ('cosine', 'euclidean', 'dot')
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo(vector).useSimilarityMetric('euclidean')
+     * ```
+     */
+    useSimilarityMetric(metric: SimilarityMetric): this;
+    /**
+     * Set minimum similarity threshold
+     *
+     * @param threshold - Minimum score threshold
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo(vector).withThreshold(0.7)
+     * ```
+     */
+    withThreshold(threshold: number): this;
+    /**
+     * Order results by a field
+     *
+     * @param field - Field name
+     * @param direction - Sort direction ('asc' or 'desc')
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .orderBy('metadata.timestamp', 'desc')
+     * ```
+     */
+    orderBy(field: string, direction?: SortDirection): this;
+    /**
+     * Order results by similarity score
+     *
+     * @param direction - Sort direction ('asc' or 'desc', default: 'desc')
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .orderBySimilarity('asc') // Least similar first
+     * ```
+     */
+    orderBySimilarity(direction?: SortDirection): this;
+    /**
+     * Limit number of results
+     *
+     * @param n - Maximum number of results
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo(vector).limit(10)
+     * ```
+     */
+    limit(n: number): this;
+    /**
+     * Skip first n results
+     *
+     * @param n - Number of results to skip
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo(vector).offset(20).limit(10) // Get results 21-30
+     * ```
+     */
+    offset(n: number): this;
+    /**
+     * Alias for offset
+     */
+    skip(n: number): this;
+    /**
+     * Alias for limit
+     */
+    take(n: number): this;
+    /**
+     * Execute raw SQL query (advanced usage)
+     *
+     * @param sql - Raw SQL query
+     * @param params - Query parameters
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .raw('SELECT * FROM vectors WHERE metadata->>"$.category" = ?', ['tech'])
+     *   .execute()
+     * ```
+     */
+    raw(sql: string, params?: any[]): this;
+    /**
+     * Type-safe metadata wrapper
+     *
+     * @returns QueryBuilder with typed metadata
+     *
+     * @example
+     * ```typescript
+     * interface BlogPost {
+     *   title: string;
+     *   author: string;
+     * }
+     *
+     * const posts = await db.query()
+     *   .withMetadata<BlogPost>()
+     *   .similarTo(vector)
+     *   .execute();
+     *
+     * // posts[0].metadata.title is typed as string
+     * ```
+     */
+    withMetadata<M>(): VectorQueryBuilder<M>;
+    /**
+     * Execute the query and return all results
+     *
+     * @returns Promise resolving to array of search results
+     *
+     * @example
+     * ```typescript
+     * const results = await db.query()
+     *   .similarTo(vector)
+     *   .where('metadata.category', '=', 'tech')
+     *   .limit(10)
+     *   .execute();
+     * ```
+     */
+    execute(): Promise<SearchResult<T>[]>;
+    /**
+     * Execute query and return first result
+     *
+     * @returns Promise resolving to first result or null
+     *
+     * @example
+     * ```typescript
+     * const best = await db.query()
+     *   .similarTo(vector)
+     *   .first();
+     * ```
+     */
+    first(): Promise<SearchResult<T> | null>;
+    /**
+     * Count results without retrieving them
+     *
+     * @returns Promise resolving to count
+     *
+     * @example
+     * ```typescript
+     * const count = await db.query()
+     *   .similarTo(vector)
+     *   .where('metadata.category', '=', 'tech')
+     *   .count();
+     * ```
+     */
+    count(): Promise<number>;
+    /**
+     * Apply filters to results
+     */
+    private applyFilters;
+    /**
+     * Get nested object value by path
+     */
+    private getNestedValue;
+    /**
+     * Check if value matches condition
+     */
+    private matchesCondition;
+    /**
+     * Apply sorting to results
+     */
+    private applySorting;
+    /**
+     * Apply pagination to results
+     */
+    private applyPagination;
+    /**
+     * Execute raw SQL query (advanced)
+     */
+    private executeRaw;
+}