@mastra/pg 1.34.0-alpha.1 → 1.34.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-pg
 description: Documentation for @mastra/pg. Use when working with @mastra/pg APIs, configuration, or implementation.
 metadata:
   package: "@mastra/pg"
-  version: "1.34.0-alpha.1"
+  version: "1.34.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.34.0-alpha.1",
+  "version": "1.34.0",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -435,6 +435,8 @@ When using PostgreSQL as your vector store, you can optimize semantic recall per
 
 PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
 
+Semantic recall always filters by thread or resource. PgVector uses the vector index for these searches only with HNSW on pgvector 0.8.0 or newer. With IVFFlat, each search compares the query against every message in the thread or resource.
+
 ```typescript
 import { Memory } from '@mastra/memory'
 import { PostgresStore, PgVector } from '@mastra/pg'

package/dist/docs/references/reference-rag-retrieval.md

@@ -251,7 +251,11 @@ const results = await pgVector.query({
 })
 ```
 
-Postgres vector indexes (HNSW and IVFFlat) can't restrict that search to rows matching a condition. When a filter is present, pgVector instead compares the query vector against every matching row and returns the closest `topK`. Results are exact, but the work grows with the number of rows the filter matches. Indexing the metadata column speeds up row retrieval. The distance comparisons still happen per row.
+With an HNSW index on pgvector 0.8.0 or newer, PostgreSQL searches the index and skips rows that don't match the filter. When the index search can't fill `topK`, pgVector reruns the query as an exact search.
+
+With IVFFlat, or HNSW on older pgvector versions, pgVector compares the query vector against every matching row. Results are exact, but the work grows with the number of matching rows.
+
+Indexing the metadata fields you filter on speeds up both cases and gives PostgreSQL the row counts it needs to choose between them.
 
 ### Vector Query Tool
 

package/dist/index.cjs

@@ -1103,42 +1103,43 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			const scoreExpr = ops.scoreExpr(distanceExpr);
 			const filterClause = filterQuery.trim().replace(/^WHERE\s+/i, "");
 			const hasFilter = filterClause.length > 0;
-			const useIndexedOrder = indexInfo.type === "hnsw" && !hasFilter && minScore <= 0;
 			const namespaceParam = filterValues.length + 1;
-			const query = useIndexedOrder ? `
+			const queryValues = [...filterValues, namespace];
+			const selectColumns = `vector_id as id, ${scoreExpr} as score, metadata${includeVector ? ", embedding" : ""}`;
+			const whereClause = `WHERE namespace = $${namespaceParam}${filterClause ? ` AND (${filterClause})` : ""}`;
+			const useIndexedOrder = indexInfo.type === "hnsw" && (!hasFilter || this.supportsIterativeScan());
+			let rows;
+			if (useIndexedOrder) {
+				const indexedQuery = `
         WITH vector_scores AS (
-          SELECT
-            vector_id as id,
-            ${scoreExpr} as score,
-            metadata
-            ${includeVector ? ", embedding" : ""}
+          SELECT ${selectColumns}
           FROM ${tableName}
-          WHERE namespace = $${namespaceParam}
+          ${whereClause}
           ORDER BY ${distanceExpr}
           LIMIT $2
         )
-        SELECT *
+        SELECT *, score > $1 AS above_min_score
         FROM vector_scores
-        WHERE score > $1
-        ORDER BY score DESC` : `
+        ORDER BY score DESC`;
+				const candidates = (await client.query(indexedQuery, queryValues)).rows;
+				if (candidates.length >= topK) rows = candidates.filter((row) => row.above_min_score);
+			}
+			if (!rows) {
+				const exactQuery = `
         WITH vector_scores AS (
-          SELECT
-            vector_id as id,
-            ${scoreExpr} as score,
-            metadata
-            ${includeVector ? ", embedding" : ""}
+          SELECT ${selectColumns}
           FROM ${tableName}
-          WHERE namespace = $${namespaceParam}
-          ${filterClause ? `AND (${filterClause})` : ""}
+          ${whereClause}
         )
         SELECT *
         FROM vector_scores
         WHERE score > $1
         ORDER BY score DESC
         LIMIT $2`;
-			const result = await client.query(query, [...filterValues, namespace]);
+				rows = (await client.query(exactQuery, queryValues)).rows;
+			}
 			await client.query("COMMIT");
-			return result.rows.map(({ id, score, metadata, embedding }) => ({
+			return rows.map(({ id, score, metadata, embedding }) => ({
 				id,
 				score,
 				metadata,
@@ -1405,7 +1406,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 					indexConfig,
 					vectorType
 				}, client);
-				if (metadataIndexes?.length) await this.createMetadataIndexes(tableName, indexName, metadataIndexes);
+				if (metadataIndexes?.length) await this.createMetadataIndexes(client, tableName, indexName, metadataIndexes);
 			} catch (error) {
 				this.createdIndexes.delete(indexName);
 				this.namespaceReadyIndexes.delete(indexName);
@@ -1555,13 +1556,13 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			await client.query(indexSQL);
 		});
 	}
-	async createMetadataIndexes(tableName, indexName, metadataFields) {
+	async createMetadataIndexes(client, tableName, indexName, metadataFields) {
 		const hasher = await this.hasher;
 		for (const field of metadataFields) {
 			const fieldHash = hasher.h32(field).toString(16);
 			const metadataIdxName = `"${indexName.slice(0, 55 - fieldHash.length)}_md_${fieldHash}_idx"`;
 			const escapedField = field.replace(/'/g, "''");
-			await this.pool.query(`
+			await client.query(`
         CREATE INDEX CONCURRENTLY IF NOT EXISTS ${metadataIdxName}
         ON ${tableName} ((metadata->>'${escapedField}'))
       `);