@mastra/spanner 1.2.4-alpha.1 → 1.3.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @mastra/spanner
 
+## 1.3.0-alpha.2
+
+### Minor Changes
+
+- Added atomic caller-defined dataset IDs for idempotent dataset creation across built-in storage adapters. Supplying `id` to `mastra.datasets.create()` now creates the dataset once and resolves compatible retries to the persisted record; incompatible immutable identity fields throw `DATASET_ID_CONFLICT`. ([#19370](https://github.com/mastra-ai/mastra/pull/19370))
+
+- Added caller-defined dataset item identities for safe retries across all dataset storage adapters. ([#19384](https://github.com/mastra-ai/mastra/pull/19384))
+
+  Dataset items can now include an `externalId` when calling `addItem` or `addItems`:
+
+  ```ts
+  await dataset.addItem({
+    externalId: 'source-item-123',
+    input: { prompt: 'Hello' },
+  });
+  ```
+
+  Retrying with the same identity and payload returns the existing item. Reusing an identity with different content returns a typed conflict, including during concurrent writes. Updates and deletes preserve the identity, Spanner retries transactions without changing the outcome, and MySQL batch writes now preserve every supported dataset item field.
+
+### Patch Changes
+
+- Raised the `@mastra/core` peer dependency floor to `>=1.51.0-0` so the dataset item identity helpers used by the storage adapters are available at runtime. ([#19384](https://github.com/mastra-ai/mastra/pull/19384))
+
+- Updated dependencies [[`a99eae8`](https://github.com/mastra-ai/mastra/commit/a99eae8908e500c1b2d12f9d277be616b98617a5), [`fd13f8e`](https://github.com/mastra-ai/mastra/commit/fd13f8e21990f9904c3eedba3a626bb4a929cdb8), [`f703f87`](https://github.com/mastra-ai/mastra/commit/f703f878de072d51fda557f9c50867d8252bef05), [`0ad646f`](https://github.com/mastra-ai/mastra/commit/0ad646f71a530f2454664299e5e01bfd13fa12e5)]:
+  - @mastra/core@1.51.0-alpha.13
+
 ## 1.2.4-alpha.1
 
 ### Patch Changes

package/dist/docs/SKILL.md

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.4-alpha.1",
+  "version": "1.3.0-alpha.2",
   "package": "@mastra/spanner",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -2995,6 +2995,7 @@ function rowToItem(row) {
     id: String(t.id),
     datasetId: String(t.datasetId),
     datasetVersion: Number(t.datasetVersion),
+    externalId: t.externalId ?? null,
     organizationId: t.organizationId ?? null,
     projectId: t.projectId ?? null,
     input: t.input,
@@ -3059,7 +3060,7 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
     await this.db.alterTable({
       tableName: storage.TABLE_DATASET_ITEMS,
       schema: storage.TABLE_SCHEMAS[storage.TABLE_DATASET_ITEMS],
-      ifNotExists: ["organizationId", "projectId"]
+      ifNotExists: ["organizationId", "projectId", "externalId"]
     });
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
@@ -3078,6 +3079,11 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
         table: storage.TABLE_DATASET_ITEMS,
         columns: ["datasetId", "datasetVersion"]
       },
+      {
+        name: "mastra_dataset_items_dataset_externalid_version_idx",
+        table: storage.TABLE_DATASET_ITEMS,
+        columns: ["datasetId", "externalId", "datasetVersion"]
+      },
       {
         // Unique invariant: one snapshot row per (datasetId, version). The DESC
         // ordering also serves listDatasetVersions' newest-first scan.
@@ -3121,7 +3127,8 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
   async createDataset(input) {
     try {
       const now = /* @__PURE__ */ new Date();
-      const id = crypto.randomUUID();
+      const id = input.id ?? crypto.randomUUID();
+      if (input.id !== void 0) this.validateCallerDefinedDatasetId(input.id);
       const record = {
         id,
         name: input.name,
@@ -3167,6 +3174,11 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
       });
       return record;
     } catch (error$1) {
+      if (input.id !== void 0 && storage.hasErrorCode(error$1, /* @__PURE__ */ new Set([6, "ALREADY_EXISTS"]))) {
+        const existing = await this.getDatasetById({ id: input.id });
+        if (existing) return this.resolveExistingDataset(existing, { ...input, id: input.id });
+      }
+      if (error$1 instanceof error.MastraError) throw error$1;
       throw new error.MastraError(
         {
           id: storage.createStorageErrorId("SPANNER", "CREATE_DATASET", "FAILED"),
@@ -3589,6 +3601,7 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
                 id: args.id,
                 datasetId: args.datasetId,
                 datasetVersion: newVersion,
+                externalId: existing.externalId ?? null,
                 organizationId,
                 projectId,
                 validTo: null,
@@ -3611,6 +3624,7 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
               id: args.id,
               datasetId: args.datasetId,
               datasetVersion: newVersion,
+              externalId: existing.externalId ?? null,
               organizationId,
               projectId,
               input: merged.input,
@@ -3670,6 +3684,7 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
                 id: args.id,
                 datasetId: args.datasetId,
                 datasetVersion: newVersion,
+                externalId: existing.externalId ?? null,
                 organizationId,
                 projectId,
                 validTo: null,
@@ -3939,55 +3954,75 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
   async _doBatchInsertItems(input) {
     try {
       if (input.items.length === 0) return [];
-      const now = /* @__PURE__ */ new Date();
-      const prepared = input.items.map((item) => ({ id: crypto.randomUUID(), item }));
       let result = [];
       await this.db.runWithAbortRetry(
         () => this.database.runTransactionAsync(async (tx) => {
           try {
-            const { version: newVersion, organizationId, projectId } = await this.bumpVersion(tx, input.datasetId, now);
-            for (const { id, item } of prepared) {
-              await this.db.insert({
-                tableName: storage.TABLE_DATASET_ITEMS,
-                record: {
-                  id,
+            const [datasetRows] = await tx.run({
+              sql: `SELECT * FROM ${quoteIdent(storage.TABLE_DATASETS, "table name")} WHERE ${quoteIdent("id", "column name")} = @id LIMIT 1`,
+              params: { id: input.datasetId },
+              json: true
+            });
+            const dataset = datasetRows[0];
+            if (!dataset) {
+              throw new error.MastraError({
+                id: storage.createStorageErrorId("SPANNER", "BATCH_INSERT_ITEMS", "DATASET_NOT_FOUND"),
+                domain: error.ErrorDomain.STORAGE,
+                category: error.ErrorCategory.USER,
+                details: { datasetId: input.datasetId }
+              });
+            }
+            const externalIds = [...new Set(input.items.flatMap((item) => item.externalId ? [item.externalId] : []))];
+            let historyRows = [];
+            if (externalIds.length > 0) {
+              const [rows] = await tx.run({
+                sql: `SELECT * FROM ${quoteIdent(storage.TABLE_DATASET_ITEMS, "table name")} WHERE ${quoteIdent("datasetId", "column name")} = @datasetId AND ${quoteIdent("externalId", "column name")} IN UNNEST(@externalIds) ORDER BY ${quoteIdent("datasetVersion", "column name")}`,
+                params: { datasetId: input.datasetId, externalIds },
+                types: { externalIds: { type: "array", child: "string" } },
+                json: true
+              });
+              historyRows = rows.map(rowToItemRow);
+            }
+            const plan = this.planDatasetItemBatch(input.items, historyRows, crypto.randomUUID);
+            const resolved = new Map(
+              [...plan.existingCurrentItems].map(([id, row]) => [id, this.datasetItemFromRow(row)])
+            );
+            if (plan.inserts.length > 0) {
+              const now = /* @__PURE__ */ new Date();
+              const {
+                version: newVersion,
+                organizationId,
+                projectId
+              } = await this.bumpVersion(tx, input.datasetId, now);
+              for (const insert of plan.inserts) {
+                const item = {
+                  id: insert.id,
                   datasetId: input.datasetId,
                   datasetVersion: newVersion,
+                  externalId: insert.item.externalId ?? null,
                   organizationId,
                   projectId,
-                  validTo: null,
-                  isDeleted: false,
-                  input: item.input,
-                  groundTruth: item.groundTruth ?? null,
-                  expectedTrajectory: item.expectedTrajectory ?? null,
-                  toolMocks: item.toolMocks ?? null,
-                  requestContext: item.requestContext ?? null,
-                  metadata: item.metadata ?? null,
-                  source: item.source ?? null,
+                  input: insert.item.input,
+                  groundTruth: insert.item.groundTruth,
+                  expectedTrajectory: insert.item.expectedTrajectory,
+                  toolMocks: insert.item.toolMocks,
+                  requestContext: insert.item.requestContext,
+                  metadata: insert.item.metadata,
+                  source: insert.item.source,
                   createdAt: now,
                   updatedAt: now
-                },
-                transaction: tx
-              });
+                };
+                await this.db.insert({
+                  tableName: storage.TABLE_DATASET_ITEMS,
+                  record: { ...item, validTo: null, isDeleted: false },
+                  transaction: tx
+                });
+                resolved.set(item.id, item);
+              }
+              await this.insertVersionRow(tx, input.datasetId, newVersion, now);
             }
-            await this.insertVersionRow(tx, input.datasetId, newVersion, now);
             await tx.commit();
-            result = prepared.map(({ id, item }) => ({
-              id,
-              datasetId: input.datasetId,
-              datasetVersion: newVersion,
-              organizationId,
-              projectId,
-              input: item.input,
-              groundTruth: item.groundTruth,
-              expectedTrajectory: item.expectedTrajectory,
-              toolMocks: item.toolMocks,
-              requestContext: item.requestContext,
-              metadata: item.metadata,
-              source: item.source,
-              createdAt: now,
-              updatedAt: now
-            }));
+            result = plan.resolvedIds.map((id) => resolved.get(id));
           } catch (err) {
             await tx.rollback().catch((rollbackErr) => {
               throw new AggregateError([err, rollbackErr], "Transaction and rollback both failed");
@@ -4031,6 +4066,7 @@ var DatasetsSpanner = class _DatasetsSpanner extends storage.DatasetsStorage {
                   id: existing.id,
                   datasetId: input.datasetId,
                   datasetVersion: newVersion,
+                  externalId: existing.externalId ?? null,
                   organizationId,
                   projectId,
                   validTo: null,