Create a data component template

A data component template tells DataStar how to turn rows in a table into a re-runnable deployment script. This guide walks through the minimum template, then adds the pieces you'll reach for most often.

Before you start

• You've created a workspace and connected it to a database.
• You know which table you want to generate components from.
• You know which column (or columns) uniquely identify a row, the natural key. Identity columns don't count; they change between environments.

The minimum template

Create a new XML file under your workspace's templates/ folder. The file name doesn't matter, but something like countries.xml helps when you come back to it.

<?xml version="1.0" encoding="utf-8"?>
<DataComponent Category="reference-data" Name="country" DeleteEnabled="true">
  <Table Id="1" Name="COUNTRY">
    <Column Name="COUNTRY_CODE" PrimaryKey="true"/>
  </Table>
</DataComponent>

Four things are going on here:

1. <DataComponent>. The root. Category groups the generated scripts in the UI; Name is the component filename.
2. <Table>. The table to extract from. Id="1" is a local identifier used when joining other tables in the same template.
3. <Column>. Only declare columns you want to customise. Everything else is picked up automatically.
4. PrimaryKey="true". Tells DataStar this column is how rows are matched. You need at least one PrimaryKey="true" or AlternativeKey="true" column per table.

That's enough to generate a MERGE script for every country row in the table. Save the file; DataStar picks up the change immediately.

Filtering to specific rows

Most of the time you don't want every row; you want the subset relevant to a specific region or set of codes. Add a <Filters> block:

<Table Id="1" Name="COUNTRY">
  <Column Name="COUNTRY_CODE" PrimaryKey="true"/>
  <Filters>
    <Value Column="COUNTRY_CODE" Value="GB"/>
  </Filters>
</Table>

Now the generated script only covers the row where COUNTRY_CODE = 'GB'. See Generate components in bulk for how to drive this filter from a query so you get one component per country.

Joining a child table

Reference tables often have child tables; COUNTRY_STATE hanging off COUNTRY, for example. Declare both tables and link them:

<Table Id="1" Name="COUNTRY">
  <Column Name="COUNTRY_CODE" PrimaryKey="true"/>
</Table>

<Table Id="2" Name="COUNTRY_STATE">
  <Column Name="COUNTRY_CODE" PrimaryKey="true" SortOrder="1"/>
  <Column Name="STATE_CODE" PrimaryKey="true" SortOrder="2"/>
  <JoinTable ReferenceId="1" Relationship="ManyToOne">
    <JoinColumn Column="COUNTRY_CODE" ReferenceColumn="COUNTRY_CODE"/>
  </JoinTable>
</Table>

ReferenceId="1" points back to the parent table by its Id. SortOrder on multi-column keys controls the column order in the generated MERGE.

Column behaviour cheatsheet

You'll use these attributes on <Column> most often:

Attribute	When to use it
PrimaryKey="true"	Natural key: what identifies the row
AlternativeKey="true"	Business key when the PK is a transient identity; see alternative keys
Transient="true"	Value differs across environments (e.g. an identity column)
InsertExclude="true"	Skip this column in INSERT (e.g. identity columns)
UpdateExclude="true"	Skip this column in UPDATE (e.g. CREATED_DATE)
UpdateTrigger="false"	This column alone doesn't count as a diff (e.g. UPDATED_BY)
Value="N"	Override the extracted value with a constant
<Lookup>...</Lookup>	Resolve a foreign key by business key; see lookups

Root element options

Attributes on <DataComponent> you'll reach for:

Attribute	Effect
DeleteEnabled="false"	Generate INSERT/UPDATE only; don't delete rows missing from source
Schema="..."	Default schema for every table unless overridden on <Table>
Version="2"	SQL Server only. Changes how deletes are generated; see SQL Server: Version 2 templates below.
ExcludeDuplicates="true"	Silently exclude duplicate components instead of flagging them as errors. See handling duplicates.

SQL Server: Version 2 templates

Applies to SQL Server only. On a data component's root element, set Version="2" to change how DataStar generates deletes.

Behaviour	v1 (default)	v2 (Version="2")
Where deletes live	Inside the MERGE via WHEN NOT MATCHED BY SOURCE THEN DELETE	Moved to the end of the script, one DELETE per table, run in reverse table order
Foreign-key handling	Prone to constraint violations when deletes cross tables; typically worked around with constraints-disable.sql / constraints-enable.sql pre- and post-scripts that toggle NOCHECK CONSTRAINT ALL	Reverse-order deletes naturally satisfy FK dependencies, so the disable / enable scripts are usually not needed
Reversal order	Original order by default	Pass --inverse-reversal to DataStar.Tools so reversals also run in reverse table order

For new SQL Server components, v2 is generally the simpler default. For existing v1 workspaces, upgrading may interact with pre-existing constraint-toggle scripts; review those before switching.

The setting is SQL Server only; it has no effect on Oracle templates. Oracle has always generated scripts the way v2 does for SQL Server: the MERGE handles inserts and updates, and deletes run separately at the end of the script in reverse table order. For the same reason, DataStar.Tools runs Oracle reversals in reverse order by default, while on SQL Server you pass --inverse-reversal to opt into that behaviour.

What to do next

• Rows keyed by identity? Add alternative keys so deployments port across environments.
• Rows that reference other rows by ID? Add lookups so those IDs get resolved at deploy time.
• One template, many components? See Generate components in bulk.
• Full schema reference: the DataComponent.xsd shipped with DataStar covers every element and attribute.