Skip to main content

Data vs object components

DataStar has two kinds of template. Before you create one, you need to know which you're after.

The difference in one line​

  • A data component template describes how to extract and deploy rows in a table: configuration, reference data, lookup values.
  • An object component template describes how to extract and deploy database objects: tables, views, stored procedures, functions, triggers.

What each one generates​

A re-runnable script that reconciles the source rows with the target table using a MERGE (or equivalent) statement, wrapped in a transaction with a metadata header and a change-summary output. Environment-agnostic and re-runnable; identity keys are resolved at deploy time via alternative keys and lookups, so you never ship transient IDs between environments.

How to choose​

You're working with…Pick
Rows in a configuration, reference, or lookup tableData component
A table structure (columns, constraints, indexes)Object component (type Table)
A view, stored procedure, function, or triggerObject component
A hand-written script that runs once (DDL migration, data fix)Neither; use a static script

Most workspaces use both: object components for the schema, data components for the rows, and a handful of static scripts for one-off fixes.

Template files​

Both kinds are XML files. They differ by the root element:

data-component.xml
<DataComponent Name="..." Category="..." DeleteEnabled="true">
<Table Id="1" Name="...">
...
</Table>
</DataComponent>
object-component.xml
<ObjectComponent Name="..." Category="..." Schema="...">
<SchemaObject Name="..." Type="View"/>
</ObjectComponent>

Each has its own XSD, so a text editor with schema support will autocomplete the right elements for you. DataStar's built-in template editor uses these XSDs directly: open a template from Workspace ▸ Data Templates / Object Templates, then press Ctrl+Space in any attribute value (or just type " after an attribute name) for a list of allowed values.

Starting a new template​

You can either author the XML directly in your favourite editor, or seed one from DataStar:

  • Workspace ▸ New Data Template opens a fresh editor tab pre-filled with a usable <DataComponent> scaffold.
  • Workspace ▸ New Object Template does the same for <ObjectComponent>.

Either menu item names the new file tentatively (DataComponent1.xml, ObjectComponent1.xml); use Save As to commit it to your workspace's templates/ folder under whatever name you want.

Requiring a version of DataStar​

A template that relies on something new, such as a lookup's When, can name the oldest version of DataStar it works with. It goes on the root element of a data or object template, as Major.Minor or Major.Minor.Patch:

<DataComponent Name="..." Category="..." MinDataStarVersion="3.1.7">

A version older than that does not use the template:

  • Menus. The template and its category show the note (needs 3.1.7) in the Data Templates, Object Templates and component menus. Its tooltip gives the reason.
  • Template Summary. Its badge reads NEEDS 3.1.7 where a usable template reads VALID.
  • A notification. 1 template(s) need a newer version of DataStar: <name>.
  • The component tab. A bar stays up saying why, with Open Template, so you can still open and read the template: Template 'views.xml' needs DataStar 3.1.7 or later, and this is version 3.1.6. It cannot be used until DataStar is upgraded. Its components are not listed, and cannot be extracted.
  • Deployments. A deployment holding an item of that category is refused, naming the item and the reason, and so is an MCP manage_deployment build. Without its template the item would run with the wrong weight and no reversal.
  • DataStar.Tools. It stops with the same message when it reads the template. See Templates that need a newer DataStar.

Only the version numbers count, so a pre-release counts as its version: 3.2.0-alpha.5 satisfies 3.2.0. A value in any other form, such as 3 or v3.2.0, marks the template invalid.

Setting the attribute does not change the scripts the template generates, so it does not make documents read as changed.

It protects from 3.1.7 on

Versions before 3.1.7 do not know the attribute. Older DataStar ignores it and uses the template anyway, without whatever it needed. Older DataStar.Tools checks a template against its own schema, so expect it to reject the template as invalid rather than name the version. So when you first use it, upgrade the people on the workspace and your pipelines before the template is committed.

Where to next​