Update an existing data spec
update_data_specChange an existing data spec's configuration. If no replacement file names are given, this runs synchronously (no upload needed): saves changes and — by default — re-runs AI analysis, returning the final status directly. If a replacement sample/format/target-schema file name IS given, this instead returns presigned upload URL(s); upload the file(s), then call finish_data_spec_update. Only pass the fields you want to change — omitted fields keep their current value.
IMPORTANT — re-analysis is a full regeneration, not a patch. It throws away the spec's existing parser and column mapping and rebuilds BOTH from the spec's stored input set as a whole: the sample file, format file, target-schema file, source tables and additionalPrompt, each read from storage exactly as it was last uploaded. A component you leave out is NOT left untouched in the generated code — it is fed to the AI again alongside the parts you changed. So updating a target schema without re-sending the source sample maps the new target against whatever sample was uploaded when the spec was onboarded, and the result is a complete, plausible-looking, WRONG mapping rather than an error.
Therefore, before changing anything that feeds code generation: call list_data (resource: "specs") to read this spec's stored input set, show the user what each component currently is, and re-send in THIS SAME call every component that is stale or that the user is now describing differently — then pass confirmedCurrentInputs: true. Keeping a stored component is a decision to make deliberately, not a default to fall into by only mentioning the field you were asked about.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| merge | No | Whether new data should merge/upsert into existing rows rather than append. For sourceType "tables" also changes the generated SQL between MERGE and INSERT. | |
| specName | Yes | Name of the existing data spec to update | |
| computeSize | No | Compute size for analysis/processing. Omit to keep the current setting. | |
| description | No | New description for the spec. Omit to keep the current value. | |
| runAnalysis | No | Whether to run analysis and wait for it after saving the changes (default true). Only applies to the synchronous (no-file-change) path. | |
| workspaceId | No | Workspace to act on. Defaults to your only workspace if you have exactly one. | |
| sourceTables | No | sourceType "tables" specs only: replacement list of source tables the generated query reads from. | |
| targetOption | No | Change where transformed data lands. Omit to keep the current setting. | |
| targetTables | No | sourceType "file" specs: new list of existing workspace tables to load into. Required when setting targetOption to "existing-tables". sourceType "tables" specs: the query's single target table name — pass a one-element array to rename the target (its schema is re-resolved per the spec's targetOption). | |
| formatFileName | No | sourceType "file" specs only. File name of a replacement format spec file. The format spec outranks the sample when deriving field boundaries, so re-send it alongside a replacement sample rather than letting a new sample be parsed by an old spec. | |
| loadSampleData | No | Whether re-analysis should also trigger the data-load job (default true). Only used when runAnalysis is true. | |
| sampleFileName | No | sourceType "file" specs only. File name of a replacement sample data file. Send this whenever the source data the user is describing differs in any way from the stored sample — the regenerated parser and mapping are built from this file, so a stale one silently mis-maps the new target. | |
| additionalPrompt | No | Extra natural-language guidance for the AI schema inference/mapping. Replaces the previously stored value when given (omit to keep it as-is), and is reused on every future re-analysis — keep it to instructions that actually change behavior. Don't restate default platform behavior (e.g. that unmapped target columns are null on insert and preserved on merge match) just to document it; a note only true for one case (like new rows) can read as a standing instruction later and confuse updates. | |
| targetSchemaFileName | No | File name of a replacement target schema file. Required when setting targetOption to "target-schema-file". Replacing this re-derives the whole mapping against the stored sample/format files — re-send those here too unless you have confirmed they still represent the source data. | |
| confirmedCurrentInputs | No | Required (true) whenever this update changes something that feeds AI code generation and analysis will run. It asserts that you have read the spec's stored input set (list_data, resource: "specs"), checked each component — sample file, format file, target-schema file, source tables, additionalPrompt — against what the user now wants, and re-sent every stale one in this same call. Set it only once that is actually true: re-analysis rebuilds the entire parser and mapping from that set, so one component left at an older version silently contradicts the ones you changed. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| files | No | Present only when replacement file(s) were given — upload these, then call finish_data_spec_update. | |
| specId | No | ||
| status | No | ||
| message | Yes | ||
| nextStep | No | The finish_data_spec_update call to make once upload(s) are done. Only present alongside files. | |
| progress | No | ||
| specName | No | ||
| timedOut | No | ||
| lastJobId | No | ||
| errorDetails | No | ||
| statusMessage | No | ||
| hasTransformationConfig | No |