Element <variable>

Purpose: Bind a reusable scalar, entity, source selection, or scripted value in the active scope.

Why: Use it for reusable intermediate data that should not itself become an exported field.

Example

<variable name="active" generator="BooleanGenerator"/>

Decision guide

Business value: Separates reusable calculations and source bindings from the fields that form the exported product.

• Use when

  • Several later fields need the same entity, source row, generated value, or calculation.

• Choose another approach when

  • The value belongs directly in the exported record.

• Prerequisites

  • Declare the variable before expressions that reference it. In a nested generate, later expressions read a binding from the current row as this. and a direct-parent binding as this.parent..

• Alternatives

  • Use key when the value must be part of the output record. (See: <key>)

Complete examples

Bind reusable values before exporting fields

Use variables for intermediate values and expose only the keys that belong in the product.

<setup rngSeed="42">
    <generate name="variable_bindings" count="5" target="LogExporter">
        <variable name="sequence" generator="IncrementGenerator"/>
        <variable name="country" constant="Germany"/>
        <variable name="doubled" script="sequence * 2"/>
        <variable name="tier" values="'standard','premium'" weights="3,1"/>
        <key name="id" script="sequence"/>
        <key name="country" script="country"/>
        <key name="score" script="doubled"/>
        <key name="tier" script="tier"/>
    </generate>
</setup>

Cycle through an ordered entity CSV source

Use cyclic only when a bounded product deliberately needs more rows than the finite source contains.

id|name
1|Ada
2|Grace
3|Linus

<setup defaultSeparator="|">
    <generate name="cycled_people" count="8" target="LogExporter">
        <variable name="person"
                  source="data/people.ent.csv"
                  distribution="ordered"
                  cyclic="true"/>
        <key name="person_id" script="person.id"/>
        <key name="person_name" script="person.name"/>
    </generate>
</setup>

Choose iterator, data, or value storage explicitly

Use iterator for row-wise traversal, data for full-pool calculations, and value for one retained row.

color|priority
red|1
green|2
blue|3

<setup defaultSeparator="|">
    <variable name="color_iterator" source="data/colors.ent.csv" storage="iterator" cyclic="true"/>
    <variable name="all_colors" source="data/colors.ent.csv" storage="data"/>
    <variable name="first_color" source="data/colors.ent.csv" storage="value"/>
    <generate name="storage_examples" count="5" target="LogExporter">
        <key name="cycled_color" script="color_iterator.color"/>
        <key name="available_colors" script="len(all_colors)"/>
        <key name="template_color" script="first_color.get('color')"/>
    </generate>
</setup>

Rules and invalid combinations

A variable requires one value-generation mode.

Attributes: source, entity, script, generator, values, constant, type, pattern, string

Why: A binding without a source, entity, script, generator, value pool, constant, type, pattern, or string template cannot expose a value.

<variable name="environment" constant="test"/>

<variable name="environment"/>

Choose exactly one explicit variable generation mode.

Attributes: source, entity, script, generator, values, constant, pattern, string

Why: Combining source, entity, script, generator, values, constant, pattern, or string would make the binding ambiguous.

<variable name="environment" constant="test"/>

<variable name="environment" constant="test" script="'development'"/>

storage requires a materializable source.

Attributes: storage, source

Why: value, data, and iterator describe how source rows are retained; they do not apply to a constant or generator result.

<variable name="customer" source="data/customers.ent.csv" storage="data"/>

<variable name="customer" constant="test" storage="data"/>

storage cannot be combined with iterationSelector.

Attributes: storage, iterationSelector

Why: Per-iteration queries do not provide the stable source pool required by a storage strategy.

<variable name="customer" source="data/customers.ent.csv" storage="data"/>

<variable name="customer" source="customerDb" storage="data" iterationSelector="SELECT * FROM customers"/>

unique cannot be combined with cyclic.

Attributes: unique, cyclic

Why: Unique sampling consumes a finite pool without replacement, while cyclic selection deliberately repeats it.

<variable name="code" values="'A','B'" unique="true"/>

<variable name="code" source="data/codes.ent.csv" unique="true" cyclic="true"/>

weights requires an inline values pool.

Attributes: weights, values

Why: Each weight biases the corresponding values entry and has no meaning without that pool.

<variable name="tier" values="'standard','premium'" weights="3,1"/>

<variable name="tier" type="string" weights="3,1"/>

defaultValue requires script.

Attributes: defaultValue, script

Why: The fallback is evaluated only when the scripted value is absent or its condition suppresses the variable.

<variable name="nickname" script="None" defaultValue="'unknown'"/>

<variable name="nickname" constant="unknown" defaultValue="'fallback'"/>

Source-selection options require source.

Attributes: source, selector, separator, sourceScripted, cyclic

Why: Source parsing and selection options have no meaning without a source read.

<variable name="customer" source="data/customers.ent.csv" selector="id != None"/>

<variable name="customer" constant="x" selector="id != None"/>

Generator and entity options require generator or entity.

Attributes: generator, entity, locale, dataset, rngSeed

Why: Locale, dataset, age, condition, and RNG options configure a component-owned value.

<variable name="person" entity="Person" locale="en"/>

<variable name="person" constant="x" locale="en"/>

storage cannot be combined with sourceScripted.

Attributes: storage, sourceScripted

Why: A scripted source does not expose the stable materialized pool required by storage.

<variable name="customer" source="data/customers.ent.csv" storage="data"/>

<variable name="customer" source="data/customers.ent.csv" storage="data" sourceScripted="true"/>

storage cannot be combined with converter.

Attributes: storage, converter

Why: A materialized list/proxy value has no per-row converter boundary.

<variable name="customer" source="data/customers.ent.csv" storage="data"/>

<variable name="customer" source="data/customers.ent.csv" storage="data" converter="Hash"/>

storage cannot materialize a weighted-entity source.

Attributes: storage, source

Why: Weighted selection consumes source metadata that a stored proxy cannot preserve faithfully.

<variable name="customer" source="data/customers.ent.csv" storage="data"/>

<variable name="customer" source="data/customers.wgt.ent.csv" storage="data" weightColumn="weight"/>

unique requires values or source.

Attributes: unique, values, source

Why: Sampling without replacement needs a finite pool.

<variable name="code" values="'A','B'" unique="true"/>

<variable name="code" type="string" unique="true"/>

unique combines only with distribution='random'.

Attributes: unique, distribution

Why: Ordered or weighted selection conflicts with uniform sampling without replacement.

<variable name="code" values="'A','B'" unique="true" distribution="random"/>

<variable name="code" values="'A','B'" unique="true" distribution="ordered"/>

unique cannot be combined with weights.

Attributes: unique, weights

Why: Unique selection is uniform without replacement; weights describe biased repeated draws.

<variable name="code" values="'A','B'" unique="true"/>

<variable name="code" values="'A','B'" weights="1,2" unique="true"/>

cyclic requires a repetition-compatible distribution.

Attributes: cyclic, distribution

Why: Weighted and stratified full-pool draws do not expose a restart boundary.

<variable name="code" source="data/codes.ent.csv" cyclic="true" distribution="ordered"/>

<variable name="code" source="data/codes.ent.csv" cyclic="true" distribution="weighted" weightColumn="weight"/>

distribution='weighted' requires weightColumn.

Attributes: distribution, weightColumn

Why: The selector needs a numeric source column for sampling probabilities.

<variable name="customer" source="data/customers.ent.csv" weightColumn="weight" distribution="weighted"/>

<variable name="customer" source="data/customers.ent.csv" distribution="weighted"/>

distribution='stratified' requires stratifyBy.

Attributes: distribution, stratifyBy

Why: The selector needs a source column identifying each stratum.

<variable name="customer" source="data/customers.ent.csv" stratifyBy="segment" distribution="stratified"/>

<variable name="customer" source="data/customers.ent.csv" distribution="stratified"/>

Inline values accept only distributions supported by the inline-values surface.

Attributes: values, source, distribution

Why: Full-source policies require row metadata that an inline scalar pool does not provide.

<variable name="code" values="'A','B'" distribution="ordered"/>

<variable name="code" values="'A','B'" distribution="reservoir"/>

A semantic project-file source requires its catalogued distribution.

Attributes: source, distribution

Why: The suffix declares selection semantics that an explicit conflicting distribution cannot override.

<variable name="customer" source="data/customers.wgt.ent.csv" weightColumn="weight" distribution="weighted"/>

<variable name="customer" source="data/customers.wgt.ent.csv" weightColumn="weight" distribution="ordered"/>

I192 — Source Reference Identifier Empty

Explicit source URI for family '{family}' requires a non-empty identifier

Why: A recognized source-family URI was declared without the identifier needed to resolve its source.

Resolution: Add the source identifier after the URI scheme and retry.

Full rule

I193 — Source Reference Consumer Unsupported

Explicit source family '{family}' is not supported by <{consumer}>

Why: The source family is valid, but the consuming DSL element does not implement its read contract.

Resolution: Use a source family supported by this element or move the read to generate/iterate.

Full rule

I194 — Source Reference Client Family Mismatch

Explicit source family '{family}' does not match configured client '{client_id}' of type '{actual_client_type}'

Why: The referenced client exists but does not implement the source family declared by the URI.

Resolution: Use the URI scheme matching the configured client or reference a client of the declared family.

Full rule

I195 — Source Reference Identifier Conflict

Explicit source identifier '{identifier}' conflicts with {attribute}='{configured_identifier}'

Why: Two source attributes select different identities for the same explicit source reference.

Resolution: Remove the legacy override or make it equal to the identifier in source.

Full rule

Allowed parents / Allowed children

Allowed parents: ama-generate, else, else-if, generate, if, iterate, nestedKey, setup, while

Allowed children:

None

Related concepts and use cases

• Expression Evaluation and Lifetime — Explains the different evaluation lifetimes of literal values, cached expressions, and dynamic expressions so descriptor authors do not accidentally move runtime state into setup-time attributes.
• Variable Scoping in Nested Generates — Prevents accidental ancestor reads and shadowing, and routes memstore reads through the public Scripting API.
• First DATAMIMIC Model — Builds the smallest model and then composes preparation and generation stages.
• Upgrade your models from DATAMIMIC 3.5 to 4.0 — Helps existing 3.5 users identify affected models, understand the reasons for 4.0 changes, and migrate syntax and expected results without confusing retained compatibility with breakage.
• Migrate Benerator Models to DATAMIMIC — Maps Benerator concepts to the current generated grammar without freezing another support matrix.
• Use the Scripting API in a Model — Shows all read-only scripting helpers together at their real expression-evaluation boundary.
• Scripted Source Templates — Explains typed full-value source expressions, embedded string substitution, and the boundary between sourceScripted templates and field or generate scripts.
• Assemble a complex deterministic model — Provides the requirement-to-model sequence for products, field dependencies, relationships, targets, and acceptance evidence.

Attributes

Show all 39 attributes

ageMax

Maximum age when generating entity data.

optional; integer; Default: null.

ageMin

Minimum age when generating entity data.

optional; integer; Default: null.

condition

Condition for including the variable value.

optional; string; Default: null.

conditionsExclude

Conditions that must be excluded during generation.

optional; string; Default: null.

conditionsInclude

Conditions that must be included during generation.

optional; string; Default: null.

constant

Constant value for variable data.

optional; string; Default: null.

converter

Converter for variable data transformation.

optional; string; Default: null.

cyclic

Enable or disable cyclic generation for variables.

optional; boolean; Default: null.

database

Database client id when source equals 'database'.

optional; string; Default: null.

dataset

Dataset for variable data.

optional; string; Default: null.

defaultValue

Default value for the variable.

optional; string; Default: null.

distribution

Distribution type for data generation.

optional; string; Default: null; Values: ordered, random, weighted, stratified, round_robin, reservoir, cumulated.

entity

Entity type for the variable.

optional; string; Default: null.

generator

Generator for variable data.

optional; string; Default: null.

inDateFormat

Input date format for variable data.

optional; string; Default: null.

iterationSelector

Selector for iteration of variable data.

optional; string; Default: null.

locale

Locale for variable data.

optional; string; Default: null.

name

Name of the variable.

required; string.

outDateFormat

Output date format for variable data.

optional; string; Default: null.

paged

Enable paged DB variable behavior for selectors.

optional; boolean; Default: null.

pattern

Pattern for variable data generation.

optional; string; Default: null.

rngSeed

Deterministic RNG seed for this variable.

optional; integer; Default: null.

script

Script for variable data generation.

optional; string; Default: null.

selector

Selector for variable data generation.

optional; string; Default: null.

separator

Separator for variable data.

optional; string; Default: null.

source

Literal project-file, memstore, database, or Mongo source; expressions remain lazy.

optional; string; Default: null.

sourceClient

Override the client used to load variable data.

optional; string; Default: null.

sourceEntity

Explicit physical entity to read (table/collection/product).

optional; string; Default: null.

sourceScripted

Enable or disable scripted sources.

optional; boolean; Default: null.

storage

Variable storage strategy.

optional; string; Default: null; Values: value, data, iterator.

stratifyBy

Stratum column for distribution='stratified' source selection.

optional; string; Default: null.

string

String for the variable data generation.

optional; string; Default: null.

type

Data type of the variable.

optional; string; Default: null; Values: string, int, integer, float, bool, binary.

unique

Emit each value at most once (distinct picks from values, no replacement).

optional; boolean; Default: null.

values

Comma-separated list of values for the variable.

optional; string; Default: null.

variablePrefix

Prefix before field's name for query select data in selector element

optional; string; Default: null.

variableSuffix

Suffix after field's name for query select data in selector element

optional; string; Default: null.

weightColumn

Weight column for variable data generation; required for a .wgt.ent.csv source.

optional; string; Default: null.

weights

Comma-separated relative weights, one per values entry, for weighted random selection.

optional; string; Default: null.