Element <execute>

Purpose: Execute trusted Python, SQL, or Bash code from a URI, expression, or inline body.

Why: Use it at an explicit trusted-code boundary for project scripts or client-targeted SQL.

Example

<execute/>

Decision guide

Business value: Provides an explicit trust boundary for setup code or client-targeted SQL that cannot be expressed declaratively.

• Use when

  • Running a reviewed project Python or Bash script, or explicit SQL against a configured client.

• Choose another approach when

  • A built-in DSL element already expresses the behavior or the code is not trusted.

• Prerequisites

  • Choose exactly one code source and provide type or target information where required.

• Alternatives

  • Use generate for declarative record production and transformation. (See: <generate>)
  • Use assert for a declarative hard quality gate. (See: <assert>)

Complete examples

Register and reuse one stateful generator instance

Use a named generator when several fields or tasks must deliberately share one configured generator instance rather than create independent instances.

assert 2 + 2 == 4

<setup>
    <execute uri="script/preflight.scr.py"/>
    <generator name="document_sequence" generator="IncrementGenerator(start=100)"/>
    <generate name="documents" count="3" target="LogExporter">
        <id name="document_id" generator="document_sequence"/>
    </generate>
</setup>

Rules and invalid combinations

I614 — Parser Execute Invalid Source

requires exactly one code source: uri (a script file), inline text, or script (an expression).

Why: has no code source or combines uri, inline text, and script even though they are alternatives.

Resolution: Provide exactly one source: uri= for a file, script= with type=, or an inline element body.

Full rule

I897 — Parser Execute Type Unresolved

: cannot infer execution type from the file extension; set an explicit type=.

Why: The uri has no recognised extension and no explicit type= was given.

Resolution: Set type= (python, sql, or bash), or use a uri with a recognised extension.

Full rule

I823 — Task Execute Client Not Found

Client '{client_id}' not found for task. Check your project environment configuration.

Why: The referenced client could not be found for the task configuration.

Resolution: Ensure the referenced client exists and the identifier/path is correct.

Full rule

I824 — Task Execute Script Not Found

Script file '{script_name}' not found in task workspace. Check your project environment configuration or uploaded script assets.

Why: The referenced script could not be found for the task configuration.

Resolution: Ensure the referenced script exists and the identifier/path is correct.

Full rule

I873 — Task Execute SQL Failed

Failed to execute SQL script '{script_name}' on client '{client_id}': {error_type}{error_code_hint}{error_category_hint}: {error}

Why: SQL execution failed while running the task against the configured client.

Resolution: Review client configuration, SQL statement, and database permissions before retrying.

Full rule

I894 — Task Execute Bash Failed

failed (exit {exit_code}): {detail}

Why: The shell command run by returned a non-zero exit status.

Resolution: Fix the shell command or its environment; inspect the reported stderr/exit code.

Full rule

Content forms

• uri — Load code from the uri attribute; the file extension determines its execution type.
• Required attributes: uri
• script — Evaluate the script attribute to obtain the code to execute.
• Required attributes: script
• inline — Use the element body as the code to execute.
• Required attributes: None

Allowed parents / Allowed children

Allowed parents: else, else-if, if, nestedKey, setup, while

Allowed children:

None

Related concepts and use cases

• Custom Generators and Converters — Shows the trusted-code boundary and loader-provided base classes for project-local generators and converters without exposing internal import paths.
• Use the Scripting API in a Model — Shows all read-only scripting helpers together at their real expression-evaluation boundary.

Attributes

Show all 4 attributes

script

Expression whose evaluated string value IS the code to run. Needs type. Mutually exclusive with uri.

optional; string; Default: null.

target

Client id to execute a SQL script against (e.g. a id).

optional; string; Default: null.

type

Execution type for script= (python, sql or bash). Inferred from the extension for uri=.

optional; string; Default: null; Values: python, sql, bash.

uri

URI of a script file to execute (.py or .sql). Mutually exclusive with script.

optional; string; Default: null.