Skip to main content

Concept Statements

Concept Statements

Concept statements define the semantic building blocks of a Trilogy model. Concepts represent business entities and their attributes.

Syntax

Core forms of concept definitions:

syntax-example
# Declaration: define a new concept with a type
concept_declaration: PURPOSE IDENTIFIER (data_type | validated_type) concept_nullable_modifier? metadata?

# Property: define a concept as a property of another
concept_property_declaration: UNIQUE? "property" (prop_ident | IDENTIFIER) (data_type | validated_type) concept_nullable_modifier? metadata?

# Derivation: define a concept as a calculation
concept_derivation: (PURPOSE | "auto" | "property") (prop_ident | IDENTIFIER) "<-" conditional

Purpose Types

  • key: Unique identifier for an entity
  • property: Attribute of an entity
  • metric: Aggregatable measure
  • const/constant: Fixed value
  • param/parameter: Runtime parameter

Key Declaration

Define a unique identifier:


key customer_id int;
key order_id string;

Property Declaration

Define attributes attached to a key:


key customer_id int;
property customer_id.name string;
property customer_id.email string;
property customer_id.created_at datetime;

Multi-Key Properties

Define properties spanning multiple keys:


key customer_id int;
key product_id int;
property <customer_id, product_id>.purchase_count int;

Grouped Property Declarations

Use properties to declare several attributes of the same key together:

key ticket_id int;
properties ticket_id (
    title string,
    status enum<string>['new', 'active', 'closed'],
    progress int[0..100],
    resolved_on date?,
);

For a composite key, use properties <key_a, key_b> (...). Fields accept the same types and nullability as individual property declarations. See Type Statements for ranges, enums, patterns, and traits.

Parameters

Parameters declare values supplied at runtime, with an optional default:

param minimum_score int[0..100] default 50;

CLI commands accept repeatable --param key=value arguments. A parameter declaration can carry a value constraint just like a key or property.

Nullable Concepts

Mark concepts as nullable with ?:


property customer_id.middle_name string?;

Metric Declaration

Define aggregatable measures:


key order_id int;
metric order_total float;
metric order_quantity int;

Concept Derivation

Define a concept as a calculation:


key order_id int;
property order_id.price float;
property order_id.quantity int;
auto order_id.total <- price * quantity;

Constant Definition

Define fixed values:


const tax_rate <- 0.08;
const company_name <- 'Acme Corp';

Unique Properties

Mark properties as unique:


key customer_id int;
unique property customer_id.email string;

With Metadata

Add metadata for documentation or tooling:


property customer_id.name string metadata(description = 'Customer full name');

Example


# Define customer entity
key customer_id int;
property customer_id.name string;
property customer_id.email string;
property customer_id.signup_date date;
# Define order entity
key order_id int;
property order_id.customer_id int;
property order_id.total float;
property order_id.created_at datetime;
# Derived concept
auto order_id.total_with_tax <- total * 1.08;
# Metric
metric revenue <- sum(order_id.total);