@mastra/pg 0.3.4 → 0.4.0-alpha.1

package/src/vector/index.ts

@@ -1,3 +1,4 @@
+import { parseSqlIdentifier } from '@mastra/core/utils';
 import { MastraVector } from '@mastra/core/vector';
 import type {
   IndexStats,
@@ -5,9 +6,10 @@ import type {
   QueryVectorParams,
   CreateIndexParams,
   UpsertVectorParams,
-  ParamsToArgs,
-  QueryVectorArgs,
-  CreateIndexArgs,
+  DescribeIndexParams,
+  DeleteIndexParams,
+  DeleteVectorParams,
+  UpdateVectorParams,
 } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
 import { Mutex } from 'async-mutex';
@@ -42,23 +44,17 @@ interface PgQueryVectorParams extends QueryVectorParams {
   probes?: number;
 }
 
-type PgQueryVectorArgs = [...QueryVectorArgs, number?, number?, number?];
-
 interface PgCreateIndexParams extends CreateIndexParams {
   indexConfig?: IndexConfig;
   buildIndex?: boolean;
 }
 
-type PgCreateIndexArgs = [...CreateIndexArgs, IndexConfig?, boolean?];
-
 interface PgDefineIndexParams {
   indexName: string;
   metric: 'cosine' | 'euclidean' | 'dotproduct';
   indexConfig: IndexConfig;
 }
 
-type PgDefineIndexArgs = [string, 'cosine' | 'euclidean' | 'dotproduct', IndexConfig];
-
 export class PgVector extends MastraVector {
   private pool: pg.Pool;
   private describeIndexCache: Map<string, PGIndexStats> = new Map();
@@ -70,48 +66,15 @@ export class PgVector extends MastraVector {
   private vectorExtensionInstalled: boolean | undefined = undefined;
   private schemaSetupComplete: boolean | undefined = undefined;
 
-  /**
-   * @deprecated Passing connectionString as a string is deprecated.
-   * Use the object parameter instead. This signature will be removed on May 20th, 2025.
-   */
-  constructor(connectionString: string);
-  constructor(config: {
+  constructor({
+    connectionString,
+    schemaName,
+    pgPoolOptions,
+  }: {
     connectionString: string;
     schemaName?: string;
     pgPoolOptions?: Omit<pg.PoolConfig, 'connectionString'>;
-  });
-  constructor(
-    config:
-      | string
-      | {
-          connectionString: string;
-          schemaName?: string;
-          pgPoolOptions?: Omit<pg.PoolConfig, 'connectionString'>;
-        },
-  ) {
-    let connectionString: string;
-    let pgPoolOptions: Omit<pg.PoolConfig, 'connectionString'> | undefined;
-    let schemaName: string | undefined;
-
-    if (typeof config === 'string') {
-      // DEPRECATION WARNING
-      console.warn(
-        `DEPRECATION WARNING: Passing connectionString as a string to PgVector constructor is deprecated.
-
-        Please use an object parameter instead:
-        new PgVector({ connectionString })
-
-        The string signature will be removed on May 20th, 2025.`,
-      );
-      connectionString = config;
-      schemaName = undefined;
-      pgPoolOptions = undefined;
-    } else {
-      connectionString = config.connectionString;
-      schemaName = config.schemaName;
-      pgPoolOptions = config.pgPoolOptions;
-    }
-
+  }) {
     if (!connectionString || connectionString.trim() === '') {
       throw new Error(
         'PgVector: connectionString must be provided and cannot be empty. Passing an empty string may cause fallback to local Postgres defaults.',
@@ -143,7 +106,7 @@ export class PgVector extends MastraVector {
       // warm the created indexes cache so we don't need to check if indexes exist every time
       const existingIndexes = await this.listIndexes();
       void existingIndexes.map(async indexName => {
-        const info = await this.getIndexInfo(indexName);
+        const info = await this.getIndexInfo({ indexName });
         const key = await this.getIndexCacheKey({
           indexName,
           metric: info.metric,
@@ -161,7 +124,9 @@ export class PgVector extends MastraVector {
   }
 
   private getTableName(indexName: string) {
-    return this.schema ? `${this.schema}.${indexName}` : indexName;
+    const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
+    const parsedSchemaName = this.schema ? parseSqlIdentifier(this.schema, 'schema name') : undefined;
+    return parsedSchemaName ? `${parsedSchemaName}.${parsedIndexName}` : parsedIndexName;
   }
 
   transformFilter(filter?: VectorFilter) {
@@ -169,29 +134,38 @@ export class PgVector extends MastraVector {
     return translator.translate(filter);
   }
 
-  async getIndexInfo(indexName: string): Promise<PGIndexStats> {
+  async getIndexInfo({ indexName }: DescribeIndexParams): Promise<PGIndexStats> {
     if (!this.describeIndexCache.has(indexName)) {
-      this.describeIndexCache.set(indexName, await this.describeIndex(indexName));
+      this.describeIndexCache.set(indexName, await this.describeIndex({ indexName }));
     }
     return this.describeIndexCache.get(indexName)!;
   }
 
-  async query(...args: ParamsToArgs<PgQueryVectorParams> | PgQueryVectorArgs): Promise<QueryResult[]> {
-    const params = this.normalizeArgs<PgQueryVectorParams, PgQueryVectorArgs>('query', args, [
-      'minScore',
-      'ef',
-      'probes',
-    ]);
-    const { indexName, queryVector, topK = 10, filter, includeVector = false, minScore = 0, ef, probes } = params;
+  async query({
+    indexName,
+    queryVector,
+    topK = 10,
+    filter,
+    includeVector = false,
+    minScore = 0,
+    ef,
+    probes,
+  }: PgQueryVectorParams): Promise<QueryResult[]> {
+    if (!Number.isInteger(topK) || topK <= 0) {
+      throw new Error('topK must be a positive integer');
+    }
+    if (!Array.isArray(queryVector) || !queryVector.every(x => typeof x === 'number' && Number.isFinite(x))) {
+      throw new Error('queryVector must be an array of finite numbers');
+    }
 
     const client = await this.pool.connect();
     try {
       const vectorStr = `[${queryVector.join(',')}]`;
       const translatedFilter = this.transformFilter(filter);
-      const { sql: filterQuery, values: filterValues } = buildFilterQuery(translatedFilter, minScore);
+      const { sql: filterQuery, values: filterValues } = buildFilterQuery(translatedFilter, minScore, topK);
 
       // Get index type and configuration
-      const indexInfo = await this.getIndexInfo(indexName);
+      const indexInfo = await this.getIndexInfo({ indexName });
 
       // Set HNSW search parameter if applicable
       if (indexInfo.type === 'hnsw') {
@@ -221,7 +195,7 @@ export class PgVector extends MastraVector {
         FROM vector_scores
         WHERE score > $1
         ORDER BY score DESC
-        LIMIT ${topK}`;
+        LIMIT $2`;
       const result = await client.query(query, filterValues);
 
       return result.rows.map(({ id, score, metadata, embedding }) => ({
@@ -235,10 +209,7 @@ export class PgVector extends MastraVector {
     }
   }
 
-  async upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]> {
-    const params = this.normalizeArgs<UpsertVectorParams>('upsert', args);
-
-    const { indexName, vectors, metadata, ids } = params;
+  async upsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
     const tableName = this.getTableName(indexName);
 
     // Start a transaction
@@ -270,7 +241,7 @@ export class PgVector extends MastraVector {
         if (match) {
           const [, expected, actual] = match;
           throw new Error(
-            `Vector dimension mismatch: Index "${params.indexName}" expects ${expected} dimensions but got ${actual} dimensions. ` +
+            `Vector dimension mismatch: Index "${indexName}" expects ${expected} dimensions but got ${actual} dimensions. ` +
               `Either use a matching embedding model or delete and recreate the index with the new dimension.`,
           );
         }
@@ -282,8 +253,13 @@ export class PgVector extends MastraVector {
   }
 
   private hasher = xxhash();
-  private async getIndexCacheKey(params: CreateIndexParams & { type: IndexType | undefined }) {
-    const input = params.indexName + params.dimension + params.metric + (params.type || 'ivfflat'); // ivfflat is default
+  private async getIndexCacheKey({
+    indexName,
+    dimension,
+    metric,
+    type,
+  }: CreateIndexParams & { type: IndexType | undefined }) {
+    const input = indexName + dimension + metric + (type || 'ivfflat'); // ivfflat is default
     return (await this.hasher).h32(input);
   }
   private cachedIndexExists(indexName: string, newKey: number) {
@@ -341,13 +317,13 @@ export class PgVector extends MastraVector {
     await this.setupSchemaPromise;
   }
 
-  async createIndex(...args: ParamsToArgs<PgCreateIndexParams> | PgCreateIndexArgs): Promise<void> {
-    const params = this.normalizeArgs<PgCreateIndexParams, PgCreateIndexArgs>('createIndex', args, [
-      'indexConfig',
-      'buildIndex',
-    ]);
-
-    const { indexName, dimension, metric = 'cosine', indexConfig = {}, buildIndex = true } = params;
+  async createIndex({
+    indexName,
+    dimension,
+    metric = 'cosine',
+    indexConfig = {},
+    buildIndex = true,
+  }: PgCreateIndexParams): Promise<void> {
     const tableName = this.getTableName(indexName);
 
     // Validate inputs
@@ -402,27 +378,7 @@ export class PgVector extends MastraVector {
     });
   }
 
-  /**
-   * @deprecated This function is deprecated. Use buildIndex instead
-   * This function will be removed on May 20th, 2025
-   */
-  async defineIndex(
-    indexName: string,
-    metric: 'cosine' | 'euclidean' | 'dotproduct' = 'cosine',
-    indexConfig: IndexConfig,
-  ): Promise<void> {
-    console.warn('defineIndex is deprecated. Use buildIndex instead. This function will be removed on May 20th, 2025');
-    return this.buildIndex({ indexName, metric, indexConfig });
-  }
-
-  async buildIndex(...args: ParamsToArgs<PgDefineIndexParams> | PgDefineIndexArgs): Promise<void> {
-    const params = this.normalizeArgs<PgDefineIndexParams, PgDefineIndexArgs>('buildIndex', args, [
-      'metric',
-      'indexConfig',
-    ]);
-
-    const { indexName, metric = 'cosine', indexConfig } = params;
-
+  async buildIndex({ indexName, metric = 'cosine', indexConfig }: PgDefineIndexParams): Promise<void> {
     const client = await this.pool.connect();
     try {
       await this.setupIndex({ indexName, metric, indexConfig }, client);
@@ -552,7 +508,13 @@ export class PgVector extends MastraVector {
     }
   }
 
-  async describeIndex(indexName: string): Promise<PGIndexStats> {
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param {string} indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex({ indexName }: DescribeIndexParams): Promise<PGIndexStats> {
     const client = await this.pool.connect();
     try {
       const tableName = this.getTableName(indexName);
@@ -648,7 +610,7 @@ export class PgVector extends MastraVector {
     }
   }
 
-  async deleteIndex(indexName: string): Promise<void> {
+  async deleteIndex({ indexName }: DeleteIndexParams): Promise<void> {
     const client = await this.pool.connect();
     try {
       const tableName = this.getTableName(indexName);
@@ -663,7 +625,7 @@ export class PgVector extends MastraVector {
     }
   }
 
-  async truncateIndex(indexName: string) {
+  async truncateIndex({ indexName }: DeleteIndexParams): Promise<void> {
     const client = await this.pool.connect();
     try {
       const tableName = this.getTableName(indexName);
@@ -680,31 +642,6 @@ export class PgVector extends MastraVector {
     await this.pool.end();
   }
 
-  /**
-   * @deprecated Use {@link updateVector} instead. This method will be removed on May 20th, 2025.
-   *
-   * Updates a vector by its ID with the provided vector and/or metadata.
-   * @param indexName - The name of the index containing the vector.
-   * @param id - The ID of the vector to update.
-   * @param update - An object containing the vector and/or metadata to update.
-   * @param update.vector - An optional array of numbers representing the new vector.
-   * @param update.metadata - An optional record containing the new metadata.
-   * @returns A promise that resolves when the update is complete.
-   * @throws Will throw an error if no updates are provided or if the update operation fails.
-   */
-  async updateIndexById(
-    indexName: string,
-    id: string,
-    update: { vector?: number[]; metadata?: Record<string, any> },
-  ): Promise<void> {
-    this.logger.warn(
-      `Deprecation Warning: updateIndexById() is deprecated. 
-      Please use updateVector() instead. 
-      updateIndexById() will be removed on May 20th, 2025.`,
-    );
-    await this.updateVector(indexName, id, update);
-  }
-
   /**
    * Updates a vector by its ID with the provided vector and/or metadata.
    * @param indexName - The name of the index containing the vector.
@@ -715,14 +652,7 @@ export class PgVector extends MastraVector {
    * @returns A promise that resolves when the update is complete.
    * @throws Will throw an error if no updates are provided or if the update operation fails.
    */
-  async updateVector(
-    indexName: string,
-    id: string,
-    update: {
-      vector?: number[];
-      metadata?: Record<string, any>;
-    },
-  ): Promise<void> {
+  async updateVector({ indexName, id, update }: UpdateVectorParams): Promise<void> {
     if (!update.vector && !update.metadata) {
       throw new Error('No updates provided');
     }
@@ -766,24 +696,6 @@ export class PgVector extends MastraVector {
     }
   }
 
-  /**
-   * @deprecated Use {@link deleteVector} instead. This method will be removed on May 20th, 2025.
-   *
-   * Deletes a vector by its ID.
-   * @param indexName - The name of the index containing the vector.
-   * @param id - The ID of the vector to delete.
-   * @returns A promise that resolves when the deletion is complete.
-   * @throws Will throw an error if the deletion operation fails.
-   */
-  async deleteIndexById(indexName: string, id: string): Promise<void> {
-    this.logger.warn(
-      `Deprecation Warning: deleteIndexById() is deprecated. 
-      Please use deleteVector() instead. 
-      deleteIndexById() will be removed on May 20th, 2025.`,
-    );
-    await this.deleteVector(indexName, id);
-  }
-
   /**
    * Deletes a vector by its ID.
    * @param indexName - The name of the index containing the vector.
@@ -791,7 +703,7 @@ export class PgVector extends MastraVector {
    * @returns A promise that resolves when the deletion is complete.
    * @throws Will throw an error if the deletion operation fails.
    */
-  async deleteVector(indexName: string, id: string): Promise<void> {
+  async deleteVector({ indexName, id }: DeleteVectorParams): Promise<void> {
     const client = await this.pool.connect();
     try {
       const tableName = this.getTableName(indexName);

package/src/vector/sql-builder.ts

@@ -1,3 +1,4 @@
+import { parseFieldKey } from '@mastra/core/utils';
 import type {
   BasicOperator,
   NumericOperator,
@@ -8,14 +9,15 @@ import type {
   VectorFilter,
 } from '@mastra/core/vector/filter';
 
-export type OperatorType =
+type OperatorType =
   | BasicOperator
   | NumericOperator
   | ArrayOperator
   | ElementOperator
   | LogicalOperator
   | '$contains'
-  | Exclude<RegexOperator, '$options'>;
+  | Exclude<RegexOperator, '$options'>
+  | '$size';
 
 type FilterOperator = {
   sql: string;
@@ -25,22 +27,27 @@ type FilterOperator = {
 
 type OperatorFn = (key: string, paramIndex: number, value?: any) => FilterOperator;
 
-// Helper functions to create operators
 const createBasicOperator = (symbol: string) => {
-  return (key: string, paramIndex: number) => ({
-    sql: `CASE 
-      WHEN $${paramIndex}::text IS NULL THEN metadata#>>'{${handleKey(key)}}' IS ${symbol === '=' ? '' : 'NOT'} NULL
-      ELSE metadata#>>'{${handleKey(key)}}' ${symbol} $${paramIndex}::text
-    END`,
-    needsValue: true,
-  });
+  return (key: string, paramIndex: number) => {
+    const jsonPathKey = parseJsonPathKey(key);
+    return {
+      sql: `CASE 
+        WHEN $${paramIndex}::text IS NULL THEN metadata#>>'{${jsonPathKey}}' IS ${symbol === '=' ? '' : 'NOT'} NULL
+        ELSE metadata#>>'{${jsonPathKey}}' ${symbol} $${paramIndex}::text
+      END`,
+      needsValue: true,
+    };
+  };
 };
 
 const createNumericOperator = (symbol: string) => {
-  return (key: string, paramIndex: number) => ({
-    sql: `(metadata#>>'{${handleKey(key)}}')::numeric ${symbol} $${paramIndex}`,
-    needsValue: true,
-  });
+  return (key: string, paramIndex: number) => {
+    const jsonPathKey = parseJsonPathKey(key);
+    return {
+      sql: `(metadata#>>'{${jsonPathKey}}')::numeric ${symbol} $${paramIndex}`,
+      needsValue: true,
+    };
+  };
 };
 
 function buildElemMatchConditions(value: any, paramIndex: number): { sql: string; values: any[] } {
@@ -73,7 +80,7 @@ function buildElemMatchConditions(value: any, paramIndex: number): { sql: string
       paramValue = val;
     }
 
-    const operatorFn = FILTER_OPERATORS[paramOperator as keyof typeof FILTER_OPERATORS];
+    const operatorFn = FILTER_OPERATORS[paramOperator as OperatorType];
     if (!operatorFn) {
       throw new Error(`Invalid operator: ${paramOperator}`);
     }
@@ -93,7 +100,7 @@ function buildElemMatchConditions(value: any, paramIndex: number): { sql: string
 }
 
 // Define all filter operators
-export const FILTER_OPERATORS: Record<string, OperatorFn> = {
+const FILTER_OPERATORS: Record<OperatorType, OperatorFn> = {
   $eq: createBasicOperator('='),
   $ne: createBasicOperator('!='),
   $gt: createNumericOperator('>'),
@@ -102,46 +109,56 @@ export const FILTER_OPERATORS: Record<string, OperatorFn> = {
   $lte: createNumericOperator('<='),
 
   // Array Operators
-  $in: (key, paramIndex) => ({
-    sql: `(
-      CASE
-        WHEN jsonb_typeof(metadata->'${handleKey(key)}') = 'array' THEN
-          EXISTS (
-            SELECT 1 FROM jsonb_array_elements_text(metadata->'${handleKey(key)}') as elem
-            WHERE elem = ANY($${paramIndex}::text[])
-          )
-        ELSE metadata#>>'{${handleKey(key)}}' = ANY($${paramIndex}::text[])
-      END
-    )`,
-    needsValue: true,
-  }),
-  $nin: (key, paramIndex) => ({
-    sql: `(
-      CASE
-        WHEN jsonb_typeof(metadata->'${handleKey(key)}') = 'array' THEN
-          NOT EXISTS (
-            SELECT 1 FROM jsonb_array_elements_text(metadata->'${handleKey(key)}') as elem
-            WHERE elem = ANY($${paramIndex}::text[])
-          )
-        ELSE metadata#>>'{${handleKey(key)}}' != ALL($${paramIndex}::text[])
-      END
-    )`,
-    needsValue: true,
-  }),
-  $all: (key, paramIndex) => ({
-    sql: `CASE WHEN array_length($${paramIndex}::text[], 1) IS NULL THEN false 
-          ELSE (metadata#>'{${handleKey(key)}}')::jsonb ?& $${paramIndex}::text[] END`,
-    needsValue: true,
-  }),
+  $in: (key, paramIndex) => {
+    const jsonPathKey = parseJsonPathKey(key);
+    return {
+      sql: `(
+        CASE
+          WHEN jsonb_typeof(metadata->'${jsonPathKey}') = 'array' THEN
+            EXISTS (
+              SELECT 1 FROM jsonb_array_elements_text(metadata->'${jsonPathKey}') as elem
+              WHERE elem = ANY($${paramIndex}::text[])
+            )
+          ELSE metadata#>>'{${jsonPathKey}}' = ANY($${paramIndex}::text[])
+        END
+      )`,
+      needsValue: true,
+    };
+  },
+  $nin: (key, paramIndex) => {
+    const jsonPathKey = parseJsonPathKey(key);
+    return {
+      sql: `(
+        CASE
+          WHEN jsonb_typeof(metadata->'${jsonPathKey}') = 'array' THEN
+            NOT EXISTS (
+              SELECT 1 FROM jsonb_array_elements_text(metadata->'${jsonPathKey}') as elem
+              WHERE elem = ANY($${paramIndex}::text[])
+            )
+          ELSE metadata#>>'{${jsonPathKey}}' != ALL($${paramIndex}::text[])
+        END
+      )`,
+      needsValue: true,
+    };
+  },
+  $all: (key, paramIndex) => {
+    const jsonPathKey = parseJsonPathKey(key);
+    return {
+      sql: `CASE WHEN array_length($${paramIndex}::text[], 1) IS NULL THEN false 
+            ELSE (metadata#>'{${jsonPathKey}}')::jsonb ?& $${paramIndex}::text[] END`,
+      needsValue: true,
+    };
+  },
   $elemMatch: (key: string, paramIndex: number, value: any): FilterOperator => {
     const { sql, values } = buildElemMatchConditions(value, paramIndex);
+    const jsonPathKey = parseJsonPathKey(key);
     return {
       sql: `(
         CASE
-          WHEN jsonb_typeof(metadata->'${handleKey(key)}') = 'array' THEN
+          WHEN jsonb_typeof(metadata->'${jsonPathKey}') = 'array' THEN
             EXISTS (
               SELECT 1 
-              FROM jsonb_array_elements(metadata->'${handleKey(key)}') as elem
+              FROM jsonb_array_elements(metadata->'${jsonPathKey}') as elem
               WHERE ${sql}
             )
           ELSE FALSE
@@ -152,10 +169,13 @@ export const FILTER_OPERATORS: Record<string, OperatorFn> = {
     };
   },
   // Element Operators
-  $exists: key => ({
-    sql: `metadata ? '${key}'`,
-    needsValue: false,
-  }),
+  $exists: key => {
+    const jsonPathKey = parseJsonPathKey(key);
+    return {
+      sql: `metadata ? '${jsonPathKey}'`,
+      needsValue: false,
+    };
+  },
 
   // Logical Operators
   $and: key => ({ sql: `(${key})`, needsValue: false }),
@@ -164,24 +184,29 @@ export const FILTER_OPERATORS: Record<string, OperatorFn> = {
   $nor: key => ({ sql: `NOT (${key})`, needsValue: false }),
 
   // Regex Operators
-  $regex: (key, paramIndex) => ({
-    sql: `metadata#>>'{${handleKey(key)}}' ~ $${paramIndex}`,
-    needsValue: true,
-  }),
+  $regex: (key, paramIndex) => {
+    const jsonPathKey = parseJsonPathKey(key);
+    return {
+      sql: `metadata#>>'{${jsonPathKey}}' ~ $${paramIndex}`,
+      needsValue: true,
+    };
+  },
 
   $contains: (key, paramIndex, value: any) => {
+    const jsonPathKey = parseJsonPathKey(key);
     let sql;
     if (Array.isArray(value)) {
-      sql = `(metadata->'${handleKey(key)}') ?& $${paramIndex}`;
+      sql = `(metadata->'${jsonPathKey}') ?& $${paramIndex}`;
     } else if (typeof value === 'string') {
-      sql = `metadata->>'${handleKey(key)}' ILIKE '%' || $${paramIndex} || '%'`;
+      sql = `metadata->>'${jsonPathKey}' ILIKE '%' || $${paramIndex} || '%' ESCAPE '\\'`;
     } else {
-      sql = `metadata->>'${handleKey(key)}' = $${paramIndex}`;
+      sql = `metadata->>'${jsonPathKey}' = $${paramIndex}`;
     }
     return {
       sql,
       needsValue: true,
-      transformValue: () => (Array.isArray(value) ? value.map(String) : value),
+      transformValue: () =>
+        Array.isArray(value) ? value.map(String) : typeof value === 'string' ? escapeLikePattern(value) : value,
     };
   },
   /**
@@ -196,29 +221,37 @@ export const FILTER_OPERATORS: Record<string, OperatorFn> = {
   //     return JSON.stringify(parts.reduceRight((value, key) => ({ [key]: value }), value));
   //   },
   // }),
-  $size: (key: string, paramIndex: number) => ({
-    sql: `(
+  $size: (key: string, paramIndex: number) => {
+    const jsonPathKey = parseJsonPathKey(key);
+    return {
+      sql: `(
       CASE
-        WHEN jsonb_typeof(metadata#>'{${handleKey(key)}}') = 'array' THEN 
-          jsonb_array_length(metadata#>'{${handleKey(key)}}') = $${paramIndex}
+        WHEN jsonb_typeof(metadata#>'{${jsonPathKey}}') = 'array' THEN 
+          jsonb_array_length(metadata#>'{${jsonPathKey}}') = $${paramIndex}
         ELSE FALSE
       END
     )`,
-    needsValue: true,
-  }),
+      needsValue: true,
+    };
+  },
 };
 
-export interface FilterResult {
+interface FilterResult {
   sql: string;
   values: any[];
 }
 
-export const handleKey = (key: string) => {
-  return key.replace(/\./g, ',');
+const parseJsonPathKey = (key: string) => {
+  const parsedKey = key !== '' ? parseFieldKey(key) : '';
+  return parsedKey.replace(/\./g, ',');
 };
 
-export function buildFilterQuery(filter: VectorFilter, minScore: number): FilterResult {
-  const values = [minScore];
+function escapeLikePattern(str: string): string {
+  return str.replace(/([%_\\])/g, '\\$1');
+}
+
+export function buildFilterQuery(filter: VectorFilter, minScore: number, topK: number): FilterResult {
+  const values = [minScore, topK];
 
   function buildCondition(key: string, value: any, parentPath: string): string {
     // Handle logical operators ($and/$or)
@@ -229,7 +262,7 @@ export function buildFilterQuery(filter: VectorFilter, minScore: number): Filter
     // If condition is not a FilterCondition object, assume it's an equality check
     if (!value || typeof value !== 'object') {
       values.push(value);
-      return `metadata#>>'{${handleKey(key)}}' = $${values.length}`;
+      return `metadata#>>'{${parseJsonPathKey(key)}}' = $${values.length}`;
     }
 
     // Handle operator conditions
@@ -240,11 +273,11 @@ export function buildFilterQuery(filter: VectorFilter, minScore: number): Filter
       const entries = Object.entries(operatorValue as Record<string, unknown>);
       const conditions = entries
         .map(([nestedOp, nestedValue]) => {
-          if (!FILTER_OPERATORS[nestedOp as keyof typeof FILTER_OPERATORS]) {
+          if (!FILTER_OPERATORS[nestedOp as OperatorType]) {
             throw new Error(`Invalid operator in $not condition: ${nestedOp}`);
           }
-          const operatorFn = FILTER_OPERATORS[nestedOp]!;
-          const operatorResult = operatorFn(key, values.length + 1);
+          const operatorFn = FILTER_OPERATORS[nestedOp as OperatorType]!;
+          const operatorResult = operatorFn(key, values.length + 1, nestedValue);
           if (operatorResult.needsValue) {
             values.push(nestedValue as number);
           }
@@ -254,7 +287,7 @@ export function buildFilterQuery(filter: VectorFilter, minScore: number): Filter
 
       return `NOT (${conditions})`;
     }
-    const operatorFn = FILTER_OPERATORS[operator as string]!;
+    const operatorFn = FILTER_OPERATORS[operator as OperatorType]!;
     const operatorResult = operatorFn(key, values.length + 1, operatorValue);
     if (operatorResult.needsValue) {
       const transformedValue = operatorResult.transformValue ? operatorResult.transformValue() : operatorValue;