Skip to main content
Version: 2.0

Naming and References

Every asset in a Teckel pipeline — inputs, transformations, and outputs — is identified by a name called an AssetRef. This page explains the naming rules, how references connect the pipeline together, and how to refer to columns unambiguously.

AssetRef Rules​

An AssetRef is the name field on any input or transformation entry. It must follow these rules:

  1. Starts with a letter (A-Z or a-z).
  2. Contains only ASCII letters, digits, underscores (_), and hyphens (-).
  3. Between 1 and 128 characters long.
  4. Case-sensitive — Orders and orders are different assets.
  5. Leading and trailing whitespace is stripped before validation.

Valid Names​

input:
- name: orders # lowercase, simple
- name: raw_events # underscores are fine
- name: staging-data # hyphens are fine
- name: Table1 # can start with uppercase
- name: myDataSource2025 # mixed case with digits

Invalid Names​

input:
- name: 1table # starts with a digit
# ERROR [E-NAME-002]: must start with a letter

- name: my table # contains a space
# ERROR [E-NAME-002]: only letters, digits, _, and - are allowed

- name: my.table # contains a dot
# ERROR [E-NAME-002]: dots are not allowed in asset names

- name: "" # empty string
# ERROR [E-NAME-002]: name must be at least 1 character

Note: Dots are reserved for qualified column references (see below). They cannot appear in asset names.

How References Work​

References are what connect the pipeline DAG together. There are two kinds of references:

Transformation References (the from field)​

Most transformations have a from field that names the upstream asset they consume:

input:
- name: users
format: csv
path: "data/users.csv"

transformation:
- name: activeUsers
where:
from: users # references the input above
filter: "active = true"

- name: sortedUsers
orderBy:
from: activeUsers # references the transformation above
columns:
- name

The from value must match the name of an existing input or transformation. It cannot reference an output.

Output References (the name field)​

Outputs work differently. An output's name field is not creating a new asset — it is referencing an existing one:

output:
- name: activeUsers # references the transformation above
format: parquet
path: "data/output/active"
mode: overwrite

This means the output writes whatever dataset the activeUsers transformation produced.

Warning: Outputs are terminal nodes (sinks). You cannot reference an output from a transformation. If you try, you will get an undefined asset error.

Join References​

Joins reference multiple assets — a left side and one or more right targets:

transformation:
- name: enriched
join:
left: orders # references one asset
right:
- name: customers # references another asset
type: inner
on:
- "orders.customer_id = customers.id"

Namespace Rules​

All asset names share a single, flat namespace within a document. This means:

  • An input and a transformation cannot have the same name.
  • An output can reuse the name of an input or transformation (because it is a reference, not a new name).
  • Split transformations produce two named assets (pass and fail), and both names must be unique in the namespace.

Valid namespace usage​

input:
- name: orders

transformation:
- name: filteredOrders # different from "orders" — OK

output:
- name: filteredOrders # references the transformation — OK
- name: orders # references the input — also OK

Invalid namespace usage​

input:
- name: data

transformation:
- name: data # CONFLICT with input name
# ERROR [E-NAME-001]: duplicate AssetRef "data"

Qualified Column References​

When you need to refer to a column in a specific asset, use dot notation:

asset_name.column_name

For example:

on:
- "orders.customer_id = customers.id"

This tells the runtime that customer_id comes from the orders asset and id comes from the customers asset.

When Qualification Is Required​

  • Join conditions — Always use qualified references. Unqualified column names in a join condition will produce error E-JOIN-001 if the name is ambiguous.

When Qualification Is Optional​

  • Select, where, group, and other single-source transformations — Since there is only one upstream asset, column names are unambiguous. You can write just amount instead of sales.amount. However, qualified references are always accepted.

Column Name Rules​

Column identifiers (the part after the dot) follow similar rules to asset names:

  • Must start with a letter.
  • May contain letters, digits, and underscores (but not hyphens).
# Valid column references
- "name" # unqualified
- "orders.total_amount" # qualified
- "employees.dept_id" # qualified

# Invalid column references
- "orders.1col" # column starts with digit
- "orders.my-col" # hyphens not allowed in column names

Note: Hyphens are allowed in asset names but not in column identifiers. The grammar for column names is slightly stricter than for asset names.

Quick Reference​

RuleAsset NamesColumn Names
Starts with letterYesYes
Letters allowedA-Z, a-zA-Z, a-z
Digits allowedYesYes
UnderscoresYesYes
HyphensYesNo
DotsNoNo (used as separator)
Case-sensitiveYesYes
Max length128Not specified