redis-vl 0.1.0-beta.0

package/dist/indexes/search-index.d.ts

@@ -0,0 +1,368 @@
+/**
+ * @module Search Index
+ * Main search index class for managing Redis search indexes.
+ */
+import type { RedisClientType, RedisClusterType } from 'redis';
+import { IndexSchema } from '../schema/schema.js';
+import type { BaseQuery, SearchResult, QueryOptions } from '../query/base.js';
+/**
+ * Options for creating an index.
+ */
+export interface CreateIndexOptions {
+    /**
+     * Whether to overwrite the index if it already exists.
+     * @default false
+     */
+    overwrite?: boolean;
+    /**
+     * Whether to drop all keys associated with the index when overwriting.
+     * Only applies when overwrite is true.
+     * @default false
+     */
+    drop?: boolean;
+}
+/**
+ * Options for deleting an index.
+ */
+export interface DeleteIndexOptions {
+    /**
+     * Whether to drop all keys associated with the index.
+     * @default false
+     */
+    drop?: boolean;
+}
+/**
+ * Options for loading data into an index.
+ */
+export interface LoadOptions {
+    /**
+     * Field name to use as the document ID.
+     * If provided, the value of this field will be used as the key.
+     * If not provided, keys will be auto-generated.
+     */
+    idField?: string;
+    /**
+     * Explicit keys to use for the documents.
+     * Must match the length of the data array.
+     */
+    keys?: string[];
+    /**
+     * Time-to-live in seconds for the documents.
+     * If provided, documents will expire after this duration.
+     */
+    ttl?: number;
+    /**
+     * Number of objects to write in a single Redis pipeline execution.
+     * @default 200
+     */
+    batchSize?: number;
+    /**
+     * Preprocessing function to transform documents before loading.
+     * The function receives a document and returns a Promise of the transformed document.
+     *
+     * @example
+     * ```typescript
+     * // Simple transformation
+     * await index.load(data, {
+     *   preprocess: async (doc) => ({ ...doc, timestamp: Date.now() })
+     * });
+     *
+     * // generating embeddings
+     * await index.load(data, {
+     *   preprocess: async (doc) => ({
+     *     ...doc,
+     *     embedding: await vectorizer.embed(doc.text)
+     *   })
+     * });
+     * ```
+     */
+    preprocess?: (doc: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    /**
+     * Whether to validate documents against schema before loading.
+     * @default false
+     */
+    validateOnLoad?: boolean;
+}
+/**
+ * SearchIndex class for managing Redis vector search indices.
+ *
+ * This class provides methods to create, manage, and query Redis search indices.
+ * Users create their own Redis client and pass it to the constructor.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'redis';
+ * import { SearchIndex, IndexSchema, StorageType } from 'redis-vl';
+ *
+ * const client = createClient();
+ * await client.connect();
+ *
+ * const schema = new IndexSchema({
+ *   index: { name: 'my-index', prefix: 'doc', storageType: StorageType.HASH }
+ * });
+ * schema.addField({ name: 'title', type: 'text' });
+ *
+ * const searchIndex = new SearchIndex(schema, client);
+ * await searchIndex.create();
+ * ```
+ */
+export declare class SearchIndex {
+    /**
+     * The index schema defining the structure and fields.
+     */
+    readonly schema: IndexSchema;
+    /**
+     * The Redis client instance.
+     */
+    private readonly client;
+    /**
+     * Internal storage handler for data operations.
+     */
+    private readonly storage;
+    /**
+     * Whether to validate documents against schema when loading.
+     * Can be overridden per load() call.
+     */
+    private readonly validateOnLoad;
+    /**
+     * Create a new SearchIndex instance.
+     *
+     * @param schema - The index schema
+     * @param client - Redis client instance (created by user)
+     * @param validateOnLoad - Whether to validate documents on load (default: false)
+     * @throws {Error} If schema is not a valid IndexSchema instance
+     * @throws {Error} If client is not provided
+     */
+    constructor(schema: IndexSchema, client: RedisClientType | RedisClusterType, validateOnLoad?: boolean);
+    /**
+     * Load an existing index from Redis by name.
+     *
+     * This method fetches the index metadata using FT.INFO and reconstructs
+     * the IndexSchema from the stored information.
+     *
+     * @param name - Name of the existing index in Redis
+     * @param client - Redis client instance
+     * @param validateOnLoad - Whether to validate documents on load (default: false)
+     * @returns SearchIndex instance with reconstructed schema
+     * @throws {RedisVLError} If index doesn't exist or cannot be loaded
+     *
+     * @example
+     * ```typescript
+     * // Load an existing index
+     * const index = await SearchIndex.fromExisting('my-index', client);
+     *
+     * // Use the loaded index
+     * const docs = await index.fetchMany(['key1', 'key2']);
+     * ```
+     */
+    static fromExisting(name: string, client: RedisClientType | RedisClusterType, validateOnLoad?: boolean): Promise<SearchIndex>;
+    /**
+     * Get the index name from the schema.
+     */
+    get name(): string;
+    /**
+     * Convert schema fields to Redis field schema format.
+     * Each field class knows how to convert itself via the toRedisField() method.
+     * @private
+     */
+    private convertFieldsToRedisSchema;
+    private getVectorScoreAlias;
+    private getVectorDistanceNormalizer;
+    /**
+     * Create the index in Redis.
+     *
+     * @param options - Creation options
+     * @throws {Error} If no fields are defined for the index
+     * @returns The result from Redis FT.CREATE command
+     */
+    create(options?: CreateIndexOptions): Promise<"OK" | undefined>;
+    /**
+     * Check if the index exists in Redis.
+     *
+     * @returns True if the index exists, false otherwise
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Delete the index from Redis.
+     *
+     * @param options - Deletion options
+     * @returns The result from Redis FT.DROPINDEX command
+     */
+    delete(options?: DeleteIndexOptions): Promise<"OK">;
+    /**
+     * Get information about the index.
+     *
+     * @returns Index information from Redis
+     */
+    info(): Promise<{
+        index_name: string;
+        index_options: string[];
+        index_definition: {
+            [x: string]: string;
+        };
+        attributes: {
+            [x: string]: string;
+        }[];
+        num_docs: number;
+        max_doc_id: number;
+        num_terms: number;
+        num_records: number;
+        inverted_sz_mb: number;
+        vector_index_sz_mb: number;
+        total_inverted_index_blocks: number;
+        offset_vectors_sz_mb: number;
+        doc_table_size_mb: number;
+        sortable_values_size_mb: number;
+        key_table_size_mb: number;
+        tag_overhead_sz_mb: number;
+        text_overhead_sz_mb: number;
+        total_index_memory_sz_mb: number;
+        geoshapes_sz_mb: number;
+        records_per_doc_avg: number;
+        bytes_per_record_avg: number;
+        offsets_per_term_avg: number;
+        offset_bits_per_record_avg: number;
+        hash_indexing_failures: number;
+        total_indexing_time: number;
+        indexing: number;
+        percent_indexed: number;
+        number_of_uses: number;
+        cleaning: number;
+        gc_stats: {
+            bytes_collected: number;
+            total_ms_run: number;
+            total_cycles: number;
+            average_cycle_time_ms: number;
+            last_run_time_ms: number;
+            gc_numeric_trees_missed: number;
+            gc_blocks_denied: number;
+        };
+        cursor_stats: {
+            global_idle: number;
+            global_total: number;
+            index_capacity: number;
+            index_total: number;
+        };
+        stopwords_list?: string[] | null[] | undefined;
+    }>;
+    /**
+     * Load documents into the index.
+     *
+     * This method handles:
+     * - Auto-generating keys using ULID if no idField or keys provided
+     * - Extracting IDs from documents using idField
+     * - Using explicit keys if provided
+     * - Preprocessing documents before storage
+     * - Setting TTL on documents
+     * - Supporting both HASH and JSON storage types
+     * - Batching operations using Redis pipelining for performance
+     * - Optional schema validation
+     *
+     * @param data - Array of documents to load
+     * @param options - Load options
+     * @returns Array of keys that were loaded
+     * @throws {Error} If keys length doesn't match data length
+     * @throws {Error} If idField is not found in a document
+     * @throws {SchemaValidationError} If validation fails when validateOnLoad is enabled
+     * @throws {RedisVLError} If there's an error loading data to Redis
+     *
+     * @example
+     * ```typescript
+     * // Auto-generate keys
+     * const keys = await index.load([
+     *   { title: 'Doc 1', score: 100 },
+     *   { title: 'Doc 2', score: 200 }
+     * ]);
+     *
+     * // Use idField
+     * const keys = await index.load(
+     *   [{ id: 'user1', name: 'John' }],
+     *   { idField: 'id' }
+     * );
+     *
+     * // Use explicit keys
+     * const keys = await index.load(
+     *   [{ name: 'John' }],
+     *   { keys: ['user:1'] }
+     * );
+     *
+     * // With preprocessing, TTL, and validation
+     * const keys = await index.load(
+     *   [{ name: 'John' }],
+     *   {
+     *     ttl: 3600,
+     *     batchSize: 100,
+     *     validateOnLoad: true,
+     *     preprocess: (doc) => ({ ...doc, timestamp: Date.now() })
+     *   }
+     * );
+     * ```
+     */
+    load(data: Record<string, unknown>[], options?: LoadOptions): Promise<string[]>;
+    /**
+     * Fetch a single document by key.
+     *
+     * @param key - The document key (without prefix)
+     * @returns The document or null if not found
+     *
+     * @example
+     * ```typescript
+     * const doc = await index.fetch('123');
+     */
+    fetch(key: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Fetch multiple documents by keys.
+     * Uses pipelining for efficient batch retrieval.
+     *
+     * @param keys - Array of document keys (without prefix)
+     * @param batchSize - Number of commands per pipeline batch (default: 200)
+     * @returns Array of documents (null for missing keys)
+     *
+     * @example
+     * ```typescript
+     * const docs = await index.fetchMany(['123', '456', '789']);
+     */
+    fetchMany(keys: string[], batchSize?: number): Promise<(Record<string, unknown> | null)[]>;
+    /**
+     * Execute a search query against the index
+     *
+     * @param query - Query object (VectorQuery, FilterQuery, etc.)
+     * @param options - Optional query execution options
+     * @returns Search results with documents and scores
+     *
+     * @example
+     * ```typescript
+     * import { VectorQuery } from 'redis-vl';
+     *
+     * // Vector similarity search
+     * const query = new VectorQuery({
+     *   vector: embedding,
+     *   vectorField: 'embedding',
+     *   topK: 10,
+     *   returnFields: ['title', 'content']
+     * });
+     *
+     * const results = await index.search(query);
+     * console.log(`Found ${results.total} results`);
+     *
+     * results.documents.forEach((doc) => {
+     *   console.log(`${doc.value.title} (score: ${doc.score})`);
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Vector search with metadata filtering
+     * const query = new VectorQuery({
+     *   vector: embedding,
+     *   vectorField: 'embedding',
+     *   filter: '@category:{electronics}',
+     *   topK: 5
+     * });
+     *
+     * const results = await index.search(query);
+     * ```
+     */
+    search<T = Record<string, unknown>>(query: BaseQuery, options?: QueryOptions): Promise<SearchResult<T>>;
+}
+//# sourceMappingURL=search-index.d.ts.map

package/dist/indexes/search-index.d.ts.map

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