agentdb 1.0.0

package/dist/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,iDAAqD;AAA5C,mHAAA,kBAAkB,OAAA"}

package/dist/query/index.mjs

@@ -0,0 +1,4 @@
+/**
+ * Query module - Fluent API for building complex vector queries
+ */
+export { VectorQueryBuilder } from './query-builder.mjs';

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

@@ -0,0 +1,323 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=query-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../src/query/query-builder.ts"],"names":[],"mappings":"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"}