1"use strict";(self.webpackChunkmastra_docs=self.webpackChunkmastra_docs||[]).push([["14556"],{3139(e,t,r){r.r(t),r.d(t,{metadata:()=>n,default:()=>p,frontMatter:()=>i,contentTitle:()=>o,toc:()=>c,assets:()=>d});var n=JSON.parse('{"id":"datasets/createExperiment","title":"Reference: dataset.createExperiment() | Datasets","description":"Use dataset.createExperiment() to create a caller-driven experiment without starting a run, then submit results and finalize it from your own orchestrator.","source":"@site/src/content/en/reference/datasets/createExperiment.mdx","sourceDirName":"datasets","slug":"/datasets/createExperiment","permalink":"/reference/datasets/createExperiment","draft":false,"unlisted":false,"editUrl":"https://github.com/mastra-ai/mastra/tree/main/docs/src/content/en/reference/datasets/createExperiment.mdx","tags":[],"version":"current","frontMatter":{"title":"Reference: dataset.createExperiment() | Datasets","description":"Use dataset.createExperiment() to create a caller-driven experiment without starting a run, then submit results and finalize it from your own orchestrator.","packages":["@mastra/core"]},"sidebar":"referenceSidebar","previous":{"title":".create()","permalink":"/reference/datasets/create"},"next":{"title":".delete()","permalink":"/reference/datasets/delete"}}'),a=r(74848),s=r(28453);let i={title:"Reference: dataset.createExperiment() | Datasets",description:"Use dataset.createExperiment() to create a caller-driven experiment without starting a run, then submit results and finalize it from your own orchestrator.",packages:["@mastra/core"]},o="dataset.createExperiment()",d={},c=[{value:"Usage example",id:"usage-example",level:2},{value:"Parameters",id:"parameters",level:2},{value:"Returns",id:"returns",level:2},{value:"Related",id:"related",level:2}];function l(e){let t={a:"a",code:"code",h1:"h1",h2:"h2",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.R)(),...e.components},{PropertiesTable:r}=t;return r||function(e,t){throw Error("Expected "+(t?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("PropertiesTable",!0),(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(t.header,{children:(0,a.jsx)(t.h1,{id:"datasetcreateexperiment",children:"dataset.createExperiment()"})}),"\n",(0,a.jsxs)(t.p,{children:[(0,a.jsx)(t.strong,{children:"Added in:"})," ",(0,a.jsx)(t.code,{children:"@mastra/[email protected]"})]}),"\n",(0,a.jsx)(t.p,{children:"Creates an experiment without starting a run. Your own orchestrator (for example a Temporal workflow) drives the loop in one of two shapes:"}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"With a target:"})," pass ",(0,a.jsx)(t.code,{children:"targetType"})," and ",(0,a.jsx)(t.code,{children:"targetId"}),", then call ",(0,a.jsx)(t.a,{href:"/reference/datasets/runExperimentItem",children:(0,a.jsx)(t.code,{children:"runExperimentItem()"})})," per item. Mastra executes the target and runs the scorers server-side."]}),"\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Without a target:"})," omit both and run everything on your own infrastructure, ingesting each result with ",(0,a.jsx)(t.a,{href:"/reference/datasets/submitExperimentResult",children:(0,a.jsx)(t.code,{children:"submitExperimentResult()"})}),"."]}),"\n"]}),"\n",(0,a.jsxs)(t.p,{children:["Both shapes finish with ",(0,a.jsx)(t.a,{href:"/reference/datasets/finalizeExperiment",children:(0,a.jsx)(t.code,{children:"finalizeExperiment()"})}),"."]}),"\n",(0,a.jsx)(t.p,{children:"The experiment pins the dataset version at creation time, so submissions are validated against a stable set of items even if the dataset changes afterwards."}),"\n",(0,a.jsx)(t.h2,{id:"usage-example",children:"Usage example"}),"\n",(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-typescript",children:"import { Mastra } from '@mastra/core'\n\nconst mastra = new Mastra({/* storage config */})\n\nconst dataset = await mastra.datasets.get({ id: 'dataset-id' })\n\nconst { experimentId, totalItems, datasetVersion } = await dataset.createExperiment({\n id: 'temporal-wf-run-42', // optional: idempotent create on retry\n targetType: 'agent',\n targetId: 'translation-agent',\n scorers: ['accuracy'],\n})\n"})}),"\n",(0,a.jsxs)(t.p,{children:["Passing your own ",(0,a.jsx)(t.code,{children:"id"})," makes creation idempotent, so another call with the same ",(0,a.jsx)(t.code,{children:"id"})," returns the existing experiment and keeps a retried workflow activity safe. The call throws an ",(0,a.jsx)(t.code,{children:"EXPERIMENT_ID_CONFLICT"})," error if the ",(0,a.jsx)(t.code,{children:"id"})," belongs to an experiment on another dataset or one with a different target."]}),"\n",(0,a.jsxs)(t.p,{children:[(0,a.jsx)(t.code,{children:"targetType"})," and ",(0,a.jsx)(t.code,{children:"targetId"})," must be provided together, and the target must exist in the Mastra registry at create time. ",(0,a.jsx)(t.code,{children:"scorers"})," requires a target because Mastra never scores target-less experiments; submit flat scores through ",(0,a.jsx)(t.code,{children:"submitExperimentResult"})," instead."]}),"\n",(0,a.jsx)(t.h2,{id:"parameters",children:"Parameters"}),"\n",(0,a.jsx)(r,{content:[{name:"id",type:"string",isOptional:!0,description:"Caller-supplied experiment ID (for example a
1workflow run ID). Makes creation idempotent on retry."},{name:"targetType",type:"'agent' | 'workflow' | 'scorer'",isOptional:!0,description:"Type of target that `runExperimentItem()` executes. Provide together with `targetId`, or omit both for pure ingestion."},{name:"targetId",type:"string",isOptional:!0,description:"ID of the registered target. Provide together with `targetType`."},{name:"scorers",type:"string[]",isOptional:!0,description:"Run-level scorer IDs resolved server-side by `runExperimentItem()`. Requires a target."},{name:"name",type:"string",isOptional:!0,description:"Human-readable experiment name."},{name:"description",type:"string",isOptional:!0,description:"Experiment description."},{name:"metadata",type:"Record<string, unknown>",isOptional:!0,description:"Arbitrary metadata stored on the experiment."},{name:"provenance",type:"ExperimentProvenance",isOptional:!0,description:"Where the experiment came from (source system, ID, and version)."},{name:"grouping",type:"ExperimentGrouping",isOptional:!0,description:"Grouping fields (`experimentSetId`, `comparisonId`, `variantId`, `trialIndex`) for organizing related runs."},{name:"version",type:"number",isOptional:!0,description:"Dataset version to pin. Defaults to the current dataset version."}]}),"\n",(0,a.jsx)(t.h2,{id:"returns",children:"Returns"}),"\n",(0,a.jsx)(r,{content:[{name:"result",type:"Promise<object>",description:"Immediate response with experiment ID.",properties:[{type:"object",parameters:[{name:"experimentId",type:"string",description:"ID of the created (or existing) experiment."},{name:"status",type:"ExperimentStatus",description:"`'running'` for a new experiment; the stored status when an existing experiment is returned."},{name:"totalItems",type:"number",description:"Number of dataset items visible at the pinned version."},{name:"datasetVersion",type:"number",description:"The pinned dataset version."}]}]}]}),"\n",(0,a.jsx)(t.h2,{id:"related",children:"Related"}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsx)(t.li,{children:(0,a.jsx)(t.a,{href:"/reference/datasets/runExperimentItem",children:"dataset.runExperimentItem()"})}),"\n",(0,a.jsx)(t.li,{children:(0,a.jsx)(t.a,{href:"/reference/datasets/submitExperimentResult",children:"dataset.submitExperimentResult()"})}),"\n",(0,a.jsx)(t.li,{children:(0,a.jsx)(t.a,{href:"/reference/datasets/finalizeExperiment",children:"dataset.finalizeExperiment()"})}),"\n",(0,a.jsx)(t.li,{children:(0,a.jsx)(t.a,{href:"/docs/evals/experiments#caller-driven-experiments",children:"Running experiments"})}),"\n"]})]})}function p(e={}){let{wrapper:t}={...(0,s.R)(),...e.components};return t?(0,a.jsx)(t,{...e,children:(0,a.jsx)(l,{...e})}):l(e)}},28453(e,t,r){r.d(t,{R:()=>i,x:()=>o});var n=r(96540);let a={},s=n.createContext(a);function i(e){let t=n.useContext(s);return n.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:i(e.components),n.createElement(s.Provider,{value:t},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.