latestOpenAPI 3.0.02026-08-137192110.1 KB

75294f591cc2

Transforms

Update transform

Update an existing transform. All fields are optional. If the transform is published and publish=true, changes to sql_template or materialization will trigger a re-publish to the DWH. Use cron_expression to set the transform's own materialization schedule (published table transforms only), or null to clear it.

patch/transforms/{id}

Path parameters

idstring required

Example:OoORhGXUVjsqFG

The ID of the transform.

Request body

namestring

The new name for the transform.

folder_pathstring

The new folder path. Intermediate folders will be auto-created if they do not exist.

sql_templatestring

The updated SQL template with {{weldTag}} parameter references.

materialization'view' | 'table'

The materialization type.

documentationstring

Documentation for the transform.

cron_expressionstring nullable

Cron expression (UTC) defining the transform's own materialization schedule. Requires a published transform with materialization "table" that is not attached to an Orchestration Workflow. Pass null to clear the schedule, which stops the transform from being rebuilt automatically.

publishboolean

If true and the transform is currently published, changes to sql_template or materialization will trigger an automatic re-publish to the DWH. If false (default), the changes are saved but the DWH is not updated until an explicit publish call.

wait_for_completionboolean

If true, the API will wait for table materialization to complete before returning, up to a configured timeout (default ~45 seconds; may differ per environment). Only relevant when publishing with materialization set to "table". If the materialization does not complete within the timeout, the response will still succeed with materialization_status "running".

Example request

{
  "name": "marketing_attribution_v2",
  "folder_path": "analytics/marketing",
  "sql_template": "SELECT * FROM {{raw.stripe.payments}} WHERE created_at > CURRENT_DATE - 7",
  "materialization": "view",
  "documentation": "Calculates marketing attribution.",
  "cron_expression": "0 6 * * *"
}

Response

idstring required

The ID of the transform.

namestring required

The name of the transform.

folder_pathstring required

The folder path for the transform.

status'draft' | 'published' required

The status of the transform.

materialization'view' | 'table' required

The materialization type.

sql_templatestring required

The SQL template with {{weldTag}} parameter references.

documentationstring

Documentation for the transform.

materialization_status'running' | 'completed' | 'failed' nullable

The status of the table materialization in the data warehouse. Set to "running", "completed", or "failed" for published table transforms, or null for drafts and view-type transforms.

materialization_errorstring

Error message from the data warehouse if table materialization failed.

orchestration_workflow_idstring

The ID of the Orchestration Workflow that this transform is attached to, if any.

cron_expressionstring nullable

Cron expression (UTC) configured as the transform's own materialization schedule, or null if none has been set. It is only acted on while the transform is published, materialized as a "table", and not attached to an Orchestration Workflow. It is still reported in the other cases — a draft, a view, or a transform running as part of a workflow (see orchestration_workflow_id) — so you can see the schedule the transform would fall back to once it is published as a table again or detached from the workflow. Use materialization, status and orchestration_workflow_id to tell whether it is currently in effect.

created_atstring date-time required

The datetime when the transform was created.

updated_atstring date-time required

The datetime when the transform was last updated.

Example response

{
  "id": "OoORhGXUVjsqFG",
  "name": "marketing_attribution",
  "folder_path": "analytics/marketing",
  "status": "published",
  "materialization": "view",
  "sql_template": "SELECT * FROM {{raw.stripe.payments}} WHERE created_at > CURRENT_DATE - 30",
  "parameters": [
    {
      "weld_tag": "raw.stripe.payments",
      "type": "raw_view",
      "dw_item_id": "stripe_schema.payments"
    }
  ],
  "documentation": "Calculates marketing attribution.",
  "materialization_status": "completed",
  "materialization_error": "Column \"foo\" not found in table \"bar\".",
  "orchestration_workflow_id": "3LIw2FdxoByya9",
  "cron_expression": "0 6 * * *",
  "created_at": "2020-01-01T00:00:00.000Z",
  "updated_at": "2020-01-01T00:00:00.000Z"
}