@mastra/pg 1.21.1-alpha.0 → 1.21.1-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @mastra/pg
 
+## 1.21.1-alpha.1
+
+### Patch Changes
+
+- Added HTTP endpoints for caller-driven experiments: `POST /datasets/:datasetId/experiments` now accepts `start: false` to create an experiment without spawning the runner (with an optional target and run-level `scorerIds`), and new routes `POST /datasets/:datasetId/experiments/:experimentId/items/:itemId/run`, `POST /datasets/:datasetId/experiments/:experimentId/results`, and `POST /datasets/:datasetId/experiments/:experimentId/finalize` let external orchestrators run one item server-side, submit externally computed per-item results (idempotent upsert on retries), and finalize the run with server-computed counts. ([#21888](https://github.com/mastra-ai/mastra/pull/21888))
+
+- Added `createDatasetExperiment()`, `runExperimentItem()`, `submitExperimentResult()`, and `finalizeExperiment()` methods so a caller-owned orchestrator (for example Temporal) can drive an experiment loop while Mastra either executes each item server-side or ingests externally computed results. ([#21888](https://github.com/mastra-ai/mastra/pull/21888))
+
+- Added `upsertExperimentResult()` to the experiments storage domain plus an `attempt` column on experiment results and a nullable target with an optional `scorerIds` column on experiments, enabling retry-safe result writes for caller-driven experiments (retried submissions with the same `(experimentId, itemId, attempt)` key converge on a single row). `saveScore()` now accepts an optional caller-supplied `id` and upserts on it, so retried experiment submissions replace their previous score rows (latest wins) instead of accumulating duplicates. ([#21888](https://github.com/mastra-ai/mastra/pull/21888))
+
+- Added caller-driven experiments so an external orchestrator (for example Temporal workers) can own the experiment loop while Mastra stays the system of record. ([#21888](https://github.com/mastra-ai/mastra/pull/21888))
+
+  Create an experiment with `dataset.createExperiment()` (idempotent when you pass your own id). With a target, Mastra runs each item for you: call `dataset.runExperimentItem()` per item and Mastra executes the registered agent or workflow, resolves scorers (experiment `scorers`, falling back to item `scorerIds`, then dataset `scorerIds`), and upserts the result. Without a target, run everything yourself and report per-item results with `dataset.submitExperimentResult()` (upsert semantics on `(experimentId, itemId, attempt)` so retried workers converge on a single row). Either way, close the run with `dataset.finalizeExperiment()` and Mastra computes per-item succeeded/failed/skipped counts from the persisted rows. Results go into the same storage as native runs, so Studio views, comparisons, and review summaries work unchanged.
+
+  ```typescript
+  // Caller drives the loop, Mastra runs each item
+  const { experimentId } = await dataset.createExperiment({
+    id: workflowRunId,
+    targetType: 'agent',
+    targetId: 'support-agent',
+    scorers: ['accuracy'],
+  });
+
+  await dataset.runExperimentItem({ experimentId, itemId });
+
+  // Or: caller runs everything, Mastra ingests results
+  const ingest = await dataset.createExperiment({ id: workflowRunId });
+  await dataset.submitExperimentResult({
+    experimentId: ingest.experimentId,
+    itemId,
+    output,
+    scores: [{ scorerId: 'accuracy', score: 0.92 }],
+  });
+
+  const experiment = await dataset.finalizeExperiment({ experimentId });
+  ```
+
+- Fixed versioned dataset item lookups to return the item visible in the requested dataset snapshot. ([#21979](https://github.com/mastra-ai/mastra/pull/21979))
+
+- Updated dependencies [[`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`acc3471`](https://github.com/mastra-ai/mastra/commit/acc3471de5f3fde8027ee4e355af292b2bc1bc30), [`b6a771e`](https://github.com/mastra-ai/mastra/commit/b6a771ef23d203ddb348efca8065eff65def8191), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`26d4016`](https://github.com/mastra-ai/mastra/commit/26d40160ff7f7d8bf95fee2039a52cbc83863533), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`57c5103`](https://github.com/mastra-ai/mastra/commit/57c51035a2a36e3df3c4f32f46bb789a66ed5946)]:
+  - @mastra/core@1.61.0-alpha.3
+
 ## 1.21.1-alpha.0
 
 ### Patch Changes

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.21.1-alpha.0"
+  version: "1.21.1-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/reference-rag-metadata-filters.md

@@ -46,7 +46,7 @@ const results = await store.query({
 
 ### Custom Operators
 
-`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
+`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: { $gt: 2 } } } — MongoDB requires an integer instead: { tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
 
 ## Common rules and restrictions
 
@@ -186,13 +186,21 @@ const results = await store.query({
 
 ### MongoDB
 
-- Full support for MongoDB/Sift query syntax for metadata filters
-- Supports all standard comparison, array, logical, and element operators
-- Supports nested fields and arrays in metadata
-- Filtering can be applied to both `metadata` and the original document content using the `filter` and `documentFilter` options, respectively
-- `filter` applies to the metadata object; `documentFilter` applies to the original document fields
-- No artificial limits on filter size or complexity (subject to MongoDB query limits)
-- Indexing metadata fields is recommended for optimal performance
+- Requires MongoDB Atlas or a deployment with MongoDB Vector Search enabled. The store queries with the `$vectorSearch` aggregation stage.
+- Uses MongoDB query syntax directly for metadata filters, including nested fields and arrays in metadata.
+- Supports the comparison, array, logical, and element operators in the tables above, plus `$regex` and `$size`. `$size` takes an integer, as in `{ tags: { $size: 3 } }`.
+- Use `filter` to match fields in the metadata object and `documentFilter` to match the original document text. You can combine them in a single query.
+- Declare the metadata fields you filter on in `filterFields` when you create the index. Mastra passes filters that use only declared fields and the operators MongoDB Vector Search accepts (`$and`, `$or`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`) directly to `$vectorSearch`:
+
+```typescript
+await store.createIndex({
+  indexName: 'my_index',
+  dimension: 1536,
+  filterFields: ['category', 'price'],
+})
+```
+
+- Filters that reference an undeclared field or use another operator take a fallback path: Mastra pre-filters the collection and passes the matching document IDs to `$vectorSearch`. This works only while the ID set fits within MongoDB's 16 MB BSON document limit. On large collections the query fails once that limit is exceeded, so declare your filter fields for selective queries over large data sets.
 
 ### Couchbase
 

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

@@ -77,9 +77,19 @@ For detailed information about available operators and syntax, see the [Metadata
 
 Basic filtering examples:
 
+**MongoDB**:
+
 ```ts
+import { MongoDBVector } from '@mastra/mongodb'
+
+const mongoVector = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+})
+
 // Simple equality filter
-const results = await pgVector.query({
+const equalityResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -89,7 +99,7 @@ const results = await pgVector.query({
 })
 
 // Numeric comparison
-const results = await pgVector.query({
+const priceResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -99,7 +109,7 @@ const results = await pgVector.query({
 })
 
 // Multiple conditions
-const results = await pgVector.query({
+const compoundResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -111,7 +121,7 @@ const results = await pgVector.query({
 })
 
 // Array operations
-const results = await pgVector.query({
+const tagResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -121,7 +131,64 @@ const results = await pgVector.query({
 })
 
 // Logical operators
-const results = await pgVector.query({
+const categoryResults = await mongoVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    $or: [{ category: 'electronics' }, { category: 'accessories' }],
+    $and: [{ price: { $gt: 50 } }, { price: { $lt: 200 } }],
+  },
+})
+```
+
+**pgVector**:
+
+```ts
+// Simple equality filter
+const equalityResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    source: 'article1.txt',
+  },
+})
+
+// Numeric comparison
+const priceResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    price: { $gt: 100 },
+  },
+})
+
+// Multiple conditions
+const compoundResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    category: 'electronics',
+    price: { $lt: 1000 },
+    inStock: true,
+  },
+})
+
+// Array operations
+const tagResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    tags: { $in: ['sale', 'new'] },
+  },
+})
+
+// Logical operators
+const categoryResults = await pgVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -141,6 +208,47 @@ Common use cases for metadata filtering:
 - Combine multiple conditions for precise querying
 - Filter by document attributes (e.g., language, author)
 
+### Where the filter is applied
+
+Vector stores differ in _when_ they apply a metadata filter, which affects how filtered queries scale.
+
+MongoDB can evaluate the filter inside the vector index itself. This keeps the query on a single round trip to `$vectorSearch`, so it avoids the pre-filter pass that collects matching document IDs and the 16 MB BSON limit that pass is subject to. Declaring the fields you filter on in `filterFields` when you create the index is what enables it:
+
+```ts
+// Declare the metadata fields you want to filter on
+await mongoVector.createIndex({
+  indexName: 'embeddings',
+  dimension: 1536,
+  filterFields: ['source', 'price', 'category', 'inStock', 'tags'],
+})
+
+// createIndex() returns before the index finishes building
+await mongoVector.waitForIndexReady({ indexName: 'embeddings' })
+
+// The filter is applied during the index search
+const results = await mongoVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: { source: 'article1.txt' },
+})
+```
+
+Mastra passes the filter to the index only when every field it references is declared in `filterFields` and every operator is one the index accepts: `$and`, `$or`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, and `$nin`. A filter that uses an undeclared field or any other operator takes a fallback path: Mastra matches the collection first and passes the matching document IDs into the vector search. That fallback holds only while the ID set fits within MongoDB's 16 MB BSON document limit. On large collections the query fails once that limit is exceeded, so declare your filter fields when you expect selective filters over large data sets.
+
+pgVector applies the filter as an ordinary query condition:
+
+```ts
+const results = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: { source: 'article1.txt' },
+})
+```
+
+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.
+
 ### Vector Query Tool
 
 Sometimes you want to give your agent the ability to query a vector database directly. The Vector Query Tool allows your agent to be in charge of retrieval decisions, combining semantic search with optional filtering and reranking based on the agent's understanding of the user's needs.

package/dist/index.cjs

@@ -6338,7 +6338,7 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 				schemaName: getSchemaName$5(this.#schema)
 			});
 			let result;
-			if (args.datasetVersion !== void 0) result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1 AND "datasetVersion" = $2 AND "isDeleted" = false`, [args.id, args.datasetVersion]);
+			if (args.datasetVersion !== void 0) result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1 AND "datasetVersion" <= $2 AND ("validTo" IS NULL OR "validTo" > $2) AND "isDeleted" = false ORDER BY "datasetVersion" DESC LIMIT 1`, [args.id, args.datasetVersion]);
 			else result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1 AND "validTo" IS NULL AND "isDeleted" = false`, [args.id]);
 			return result ? this.transformItemRow(result) : null;
 		} catch (error) {
@@ -6596,7 +6596,8 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 				"experimentSetId",
 				"comparisonId",
 				"variantId",
-				"trialIndex"
+				"trialIndex",
+				"scorerIds"
 			]
 		});
 		await this.#db.alterTable({
@@ -6608,7 +6609,8 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 				"comment",
 				"toolMockReport",
 				"organizationId",
-				"projectId"
+				"projectId",
+				"attempt"
 			]
 		});
 		await this.createDefaultIndexes();
@@ -6718,9 +6720,13 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 				columns: ["experimentId"]
 			},
 			{
-				name: "idx_experiment_results_exp_item",
+				name: "idx_experiment_results_exp_item_attempt",
 				table: _mastra_core_storage.TABLE_EXPERIMENT_RESULTS,
-				columns: ["experimentId", "itemId"],
+				columns: [
+					"experimentId",
+					"itemId",
+					"attempt"
+				],
 				unique: true
 			},
 			{
@@ -6737,6 +6743,11 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 	}
 	async createDefaultIndexes() {
 		if (this.#skipDefaultIndexes) return;
+		try {
+			await this.#db.dropIndex("idx_experiment_results_exp_item");
+		} catch (error) {
+			this.logger?.warn?.("Failed to drop legacy index idx_experiment_results_exp_item:", error);
+		}
 		for (const indexDef of this.getDefaultIndexDefinitions()) try {
 			await this.#db.createIndex(indexDef);
 		} catch (error) {
@@ -6768,8 +6779,9 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 			agentVersion: row.agentVersion ?? null,
 			organizationId: row.organizationId ?? null,
 			projectId: row.projectId ?? null,
-			targetType: row.targetType,
-			targetId: row.targetId,
+			targetType: row.targetType ?? null,
+			targetId: row.targetId ?? null,
+			scorerIds: row.scorerIds ? (0, _mastra_core_storage.safelyParseJSON)(row.scorerIds) : null,
 			status: row.status,
 			totalItems: row.totalItems,
 			succeededCount: row.succeededCount,
@@ -6796,6 +6808,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 			startedAt: (0, _mastra_core_storage.ensureDate)(row.startedAtZ || row.startedAt),
 			completedAt: (0, _mastra_core_storage.ensureDate)(row.completedAtZ || row.completedAt),
 			retryCount: row.retryCount,
+			attempt: row.attempt != null ? row.attempt : 0,
 			traceId: row.traceId ?? null,
 			status: row.status ?? null,
 			tags: row.tags ? (0, _mastra_core_storage.safelyParseJSON)(row.tags) : null,
@@ -6827,8 +6840,9 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 					agentVersion: input.agentVersion ?? null,
 					organizationId: input.organizationId ?? null,
 					projectId: input.projectId ?? null,
-					targetType: input.targetType,
-					targetId: input.targetId,
+					targetType: input.targetType ?? null,
+					targetId: input.targetId ?? null,
+					scorerIds: input.scorerIds ?? null,
 					status: "pending",
 					totalItems: input.totalItems,
 					succeededCount: 0,
@@ -6856,8 +6870,9 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 				agentVersion: input.agentVersion ?? null,
 				organizationId: input.organizationId ?? null,
 				projectId: input.projectId ?? null,
-				targetType: input.targetType,
-				targetId: input.targetId,
+				targetType: input.targetType ?? null,
+				targetId: input.targetId ?? null,
+				scorerIds: input.scorerIds ?? null,
 				status: "pending",
 				totalItems: input.totalItems,
 				succeededCount: 0,
@@ -7101,6 +7116,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 					startedAt: input.startedAt.toISOString(),
 					completedAt: input.completedAt.toISOString(),
 					retryCount: input.retryCount,
+					attempt: input.attempt ?? 0,
 					traceId: input.traceId ?? null,
 					status: input.status ?? null,
 					tags: input.tags ?? null,
@@ -7122,6 +7138,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 				startedAt: input.startedAt,
 				completedAt: input.completedAt,
 				retryCount: input.retryCount,
+				attempt: input.attempt ?? 0,
 				traceId: input.traceId ?? null,
 				status: input.status ?? null,
 				tags: input.tags ?? null,
@@ -7136,6 +7153,81 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 			}, error);
 		}
 	}
+	async upsertExperimentResult(input) {
+		try {
+			const tableName = getTableName$5({
+				indexName: _mastra_core_storage.TABLE_EXPERIMENT_RESULTS,
+				schemaName: getSchemaName$5(this.#schema)
+			});
+			const attempt = input.attempt ?? 0;
+			const row = await this.#db.client.tx(async (t) => {
+				const existing = await t.oneOrNone(`SELECT "id" FROM ${tableName} WHERE "experimentId" = $1 AND "itemId" = $2 AND COALESCE("attempt", 0) = $3 FOR UPDATE`, [
+					input.experimentId,
+					input.itemId,
+					attempt
+				]);
+				if (!existing) {
+					const id = crypto.randomUUID();
+					return t.one(`INSERT INTO ${tableName} (
+              "id", "experimentId", "itemId", "itemDatasetVersion", "organizationId", "projectId",
+              "input", "output", "groundTruth", "error", "startedAt", "completedAt",
+              "retryCount", "attempt", "traceId", "status", "tags", "toolMockReport", "createdAt"
+            ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19)
+            RETURNING *`, [
+						id,
+						input.experimentId,
+						input.itemId,
+						input.itemDatasetVersion ?? null,
+						input.organizationId ?? null,
+						input.projectId ?? null,
+						JSON.stringify(input.input),
+						input.output != null ? JSON.stringify(input.output) : null,
+						input.groundTruth != null ? JSON.stringify(input.groundTruth) : null,
+						input.error != null ? JSON.stringify(input.error) : null,
+						input.startedAt.toISOString(),
+						input.completedAt.toISOString(),
+						input.retryCount,
+						attempt,
+						input.traceId ?? null,
+						input.status ?? null,
+						input.tags != null ? JSON.stringify(input.tags) : null,
+						input.toolMockReport != null ? JSON.stringify(input.toolMockReport) : null,
+						(/* @__PURE__ */ new Date()).toISOString()
+					]);
+				}
+				return t.one(`UPDATE ${tableName} SET
+            "itemDatasetVersion" = $2, "organizationId" = $3, "projectId" = $4,
+            "input" = $5, "output" = $6, "groundTruth" = $7, "error" = $8,
+            "startedAt" = $9, "completedAt" = $10, "retryCount" = $11, "attempt" = $12,
+            "traceId" = $13, "status" = $14, "tags" = $15, "toolMockReport" = $16
+          WHERE "id" = $1 RETURNING *`, [
+					existing.id,
+					input.itemDatasetVersion ?? null,
+					input.organizationId ?? null,
+					input.projectId ?? null,
+					JSON.stringify(input.input),
+					input.output != null ? JSON.stringify(input.output) : null,
+					input.groundTruth != null ? JSON.stringify(input.groundTruth) : null,
+					input.error != null ? JSON.stringify(input.error) : null,
+					input.startedAt.toISOString(),
+					input.completedAt.toISOString(),
+					input.retryCount,
+					attempt,
+					input.traceId ?? null,
+					input.status ?? null,
+					input.tags != null ? JSON.stringify(input.tags) : null,
+					input.toolMockReport != null ? JSON.stringify(input.toolMockReport) : null
+				]);
+			});
+			return this.transformExperimentResultRow(row);
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("PG", "UPSERT_EXPERIMENT_RESULT", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY
+			}, error);
+		}
+	}
 	async updateExperimentResult(input) {
 		try {
 			const tableName = getTableName$5({
@@ -18940,9 +19032,14 @@ var ScoresPG = class ScoresPG extends _mastra_core_storage.ScoresStorage {
 			}, error);
 		}
 		try {
-			const id = crypto.randomUUID();
+			const suppliedId = parsedScore.id;
+			const id = suppliedId ?? crypto.randomUUID();
 			const now = /* @__PURE__ */ new Date();
-			const { scorer, preprocessStepResult, analyzeStepResult, metadata, input, output, additionalContext, requestContext, entity, ...rest } = parsedScore;
+			const { id: _suppliedId, scorer, preprocessStepResult, analyzeStepResult, metadata, input, output, additionalContext, requestContext, entity, ...rest } = parsedScore;
+			if (suppliedId) await this.#db.client.none(`DELETE FROM ${getTableName$1({
+				indexName: _mastra_core_storage.TABLE_SCORERS,
+				schemaName: getSchemaName$1(this.#schema)
+			})} WHERE id = $1`, [suppliedId]);
 			await this.#db.insert({
 				tableName: _mastra_core_storage.TABLE_SCORERS,
 				record: {