Data Graph YAML Reference

YAML schema reference for defining a Data Graph with the Rudder CLI — entities, events, and relationships.

Available Plans

growth
enterprise

12 minute read

This reference documents the YAML schema for defining a Data Graph with the Rudder CLI. Use it alongside the CLI to author, version-control, and sync data graph definitions as code.

File structure

A data graph YAML file has the following top-level structure:

version: "rudder/v1"
kind: "data-graph"
metadata:
  name: "ecommerce-data-graph"
spec:
  id: "ecommerce-data-graph"
  account_id: "<warehouse-account-id>"
  models:
    - ...

Top-level fields

Field	Type	Description
`version` Required	String	Schema version. Use `rudder/v1`.
`kind` Required	String	Resource kind. Must be `data-graph`.
`metadata.name` Required	String	Human-readable name for the data graph
`spec.id` Required	String	Unique ID for the data graph. Used as its stable identifier across syncs.
`spec.account_id` Required	String	The ID of the warehouse account the data graph reads from.
`spec.models` Required	List	List of entity and event models that make up the data graph. See Models for more information.

Models

The spec.models list contains all the entities and events the data graph exposes to the Audience Builder. Each model points at a warehouse table and optionally declares relationships to other models.

Model fields

Field	Type	Description
`id` Required	String	Unique ID for the model within this data graph. Used as the target of relationships (see Relationships).
`display_name` Required	String	Name shown in the Audience Builder UI (for example, `Customers`, `Sales`).
`type` Required	String	Either `entity` (dimension-style table) or `event` (timestamped fact table).
`table` Required	String	Fully qualified warehouse table name, for example, `ECOMMERCE_DB.E_MART.DIM_CUSTOMERS`.
`description`	String	Human-readable description of the model. Shown as a tooltip in the builder.
`primary_id` Required	String	Column that uniquely identifies a row in the table. Required for entities, Optional for events.
`timestamp` Required	String	Column holding the event timestamp. Required when `type: event`. Used for time-window filtering in the Audience Builder. Optional for entities.
`relationships` Optional	List	List of relationships this model has to other models. See Relationships for more information.
`columns` Optional	List	Per-column overrides that give warehouse columns a marketer-friendly alias (`display_name`) and an optional `description` (both surfaced in the Audience Builder), and a PII flag (`pii_mask`) that masks the column’s values in the Data Graph preview. See Column metadata for more information.

Entity vs. event

Entity: A dimension-like table representing a business object (Customers, Products, Stores). Use type: entity and set primary_id.
Event: A fact-like table where each row represents something that happened at a point in time (Sales, Customer Interactions, Loyalty Points). Use type: event and set timestamp. Events can be filtered with a time window in the Audience Builder.

Relationships

Relationships connect two models so marketers can filter one model using conditions on related records (for example, “customers with 3 or more orders”). Relationships are declared on the source model under its relationships list.

Relationship fields

Field	Type	Description
`id` Required	String	Unique ID for the relationship within the source model.
`display_name` Required	String	Name shown in the Audience Builder UI (for example, `Has Sales`, `Belongs To Account`).
`cardinality` Required	String	One of `one-to-many`, `many-to-one`, or `one-to-one`. See Current limitations.
`target` Required	String	Reference to the target model in the form `#data-graph-model:<model-id>`.
`source_join_key` Required	String	Column on the source model used in the join.
`target_join_key` Required	String	Column on the target model used in the join.

Target reference format

Relationship targets use the #data-graph-model:<model-id> reference format, where <model-id> is the id of another model in the same data graph. For example:

target: "#data-graph-model:sales"

Column metadata

By default, the Audience Builder shows the raw warehouse column names (for example, EMAIL_ADDRESS or CREATED_TS). Use the optional columns block on a model to give specific columns a marketer-friendly alias (display_name) and an optional description — both surface when building audiences and expressions, making the underlying warehouse columns easier to read and choose. You can also flag a column as PII with pii_mask: true to mask its sample values in the Data Graph preview.

The columns block is sparse — list only the columns you want to override. Columns you don’t list keep their raw warehouse names.

models:
  - id: "customers"
    display_name: "Customers"
    type: "entity"
    table: "ECOMMERCE_DB.E_MART.DIM_CUSTOMERS"
    primary_id: "CUSTOMER_KEY"
    columns:
      - name: "EMAIL_ADDRESS"                         # Warehouse column name (must match the table).
        display_name: "Email"                         # Friendly name shown in the Audience Builder.
        description: "Primary contact email"
        pii_mask: true                                # Mask this column's values in the preview.
      - name: "CUSTOMER_KEY"
        display_name: "Customer ID"                   # Alias only — no description.
      - name: "LOYALTY_NOTES"
        description: "Free-form loyalty notes"        # Description only — no alias.
      - name: "SSN"
        pii_mask: true                                # PII only — no alias or description.

Column fields

Field	Type	Description
`name` Required	String	Warehouse column name — must match a column in the model’s `table`.
`display_name` Conditional	String	Friendly name shown in the Audience Builder instead of the raw column name. Required unless `description` or `pii_mask` is set. Maximum 255 characters — should be case-insensitive and unique within the model.
`description` Conditional	String	Human-readable note shown alongside the column in the Audience Builder. Required unless `display_name` or `pii_mask` is set. Maximum 255 characters.
`pii_mask` Optional	Boolean	When `true`, marks the column as PII so its values are masked (`*`) in the Data Graph preview. Defaults to `false`. Marking a column as PII is an enterprise-only** capability — the server rejects `pii_mask: true` on other plans.

Note that:

Each columns entry must set at least one of display_name, description, or pii_mask.
To clear one field while keeping the others, omit it from the entry.
To remove all metadata for a column, drop its entry — the next apply clears it, since the columns block is the source of truth.
In the Data Graph preview, pii_mask columns render as ***. Users with the PII rETL Data Access permission (and enterprise admins) can reveal the clear text.

Complete example

The following example defines a small e-commerce data graph with two entities (Customers, Accounts), one event (Sales), and the relationships between them:

version: "rudder/v1"
kind: "data-graph"
metadata:
  name: "ecommerce-data-graph"
spec:
  id: "ecommerce-data-graph"
  account_id: "<warehouse-account-id>" # RudderStack generates this ID when you connect a warehouse to your RudderStack workspace.
  models:
    # --- Customers (entity) ---
    - id: "customers"
      display_name: "Customers"
      type: "entity"
      table: "ECOMMERCE_DB.E_MART.DIM_CUSTOMERS"
      description: "Customers with demographics and loyalty info"
      primary_id: "CUSTOMER_KEY"
      columns:
        - name: "EMAIL_ADDRESS"
          display_name: "Email"
          description: "Primary contact email"
          pii_mask: true
        - name: "LOYALTY_TIER"
          display_name: "Loyalty Tier"
      relationships:
        - id: "customer-has-sales"
          display_name: "Has Sales"
          cardinality: "one-to-many"
          target: "#data-graph-model:sales"
          source_join_key: "CUSTOMER_KEY"
          target_join_key: "CUSTOMER_KEY"
        - id: "customer-belongs-to-account"
          display_name: "Belongs To Account"
          cardinality: "many-to-one"
          target: "#data-graph-model:accounts"
          source_join_key: "ACCOUNT_KEY"
          target_join_key: "ACCOUNT_KEY"

    # --- Accounts (entity) ---
    - id: "accounts"
      display_name: "Accounts"
      type: "entity"
      table: "ECOMMERCE_DB.E_MART.DIM_ACCOUNTS"
      description: "Customer account records for individual, household, and corporate grouping"
      primary_id: "ACCOUNT_KEY"

    # --- Sales (event) ---
    - id: "sales"
      display_name: "Sales"
      type: "event"
      table: "ECOMMERCE_DB.E_MART.FACT_SALES"
      description: "Sales transactions with amounts, status, and store/channel links"
      timestamp: "CREATED_AT"

Validate the data graph

Validate your data graph YAML before syncing it to your workspace:

rudder-cli validate -l data-graph.yaml

This command returns validation errors and warnings if the YAML is invalid.

Validation rules

Relationship cardinality must be valid for the source and target model types

semantic error

Rule ID: datagraph/data-graph/relationship-cardinality-valid

Examples

Entity-to-entity relationship with any cardinality is valid

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-account
          display_name: User Account
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id

Event-to-entity relationship uses many-to-one cardinality

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at
      relationships:
        - id: purchase-user
          display_name: Purchase User
          cardinality: many-to-one
          target: "#data-graph-model:user"
          source_join_key: user_id
          target_join_key: user_id
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id

Event models cannot connect to other event models

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at
      relationships:
        - id: purchase-click
          display_name: Purchase Click
          cardinality: many-to-one
          target: "#data-graph-model:click"
          source_join_key: session_id
          target_join_key: session_id
    - id: click
      display_name: Click
      type: event
      table: db.schema.clicks
      timestamp: clicked_at

Diagnostics

spec.yaml /models/0/relationships/0/cardinality event models cannot be connected to other event models

Event-to-entity relationship requires many-to-one cardinality

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at
      relationships:
        - id: purchase-user
          display_name: Purchase User
          cardinality: one-to-many
          target: "#data-graph-model:user"
          source_join_key: user_id
          target_join_key: user_id
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id

Diagnostics

spec.yaml /models/0/relationships/0/cardinality relationships from event models must have cardinality 'many-to-one', got "one-to-many"

Entity-to-event relationship requires one-to-many cardinality

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-purchase
          display_name: User Purchase
          cardinality: many-to-one
          target: "#data-graph-model:purchase"
          source_join_key: user_id
          target_join_key: user_id
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at

Diagnostics

spec.yaml /models/0/relationships/0/cardinality relationships from entity models to event models must have cardinality 'one-to-many', got "many-to-one"

Relationship target references must resolve to existing models

semantic error

Rule ID: datagraph/data-graph/relationship-refs-valid

Examples

Relationship target references an existing model in the Data Graph

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-account
          display_name: User Account
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id

Relationship target references a missing model

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-missing
          display_name: User Missing
          cardinality: one-to-one
          target: "#data-graph-model:non-existent"
          source_join_key: ref_id
          target_join_key: ref_id

Diagnostics

spec.yaml /models/0/relationships/0/target target model "data-graph-model:non-existent" does not exist

At most one relationship is allowed per source-target model pair

semantic error

Rule ID: datagraph/data-graph/relationship-unique-pair

Examples

Multiple relationships from one model to different targets are allowed

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-account
          display_name: User Account
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
        - id: user-profile
          display_name: User Profile
          cardinality: one-to-one
          target: "#data-graph-model:profile"
          source_join_key: profile_id
          target_join_key: profile_id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id
    - id: profile
      display_name: Profile
      type: entity
      table: db.schema.profiles
      primary_id: profile_id

A-to-B and B-to-A relationships are distinct and both allowed

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-to-account
          display_name: User to Account
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id
      relationships:
        - id: account-to-user
          display_name: Account to User
          cardinality: one-to-one
          target: "#data-graph-model:user"
          source_join_key: account_id
          target_join_key: account_id

Duplicate source-target model pairs are not allowed

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-account-v1
          display_name: User Account v1
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
        - id: user-account-v2
          display_name: User Account v2
          cardinality: one-to-many
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id

Diagnostics

spec.yaml /models/0/relationships/0 a relationship from model "data-graph-model:user" to model "data-graph-model:account" already exists; at most one relationship is allowed per source-target pair
spec.yaml /models/0/relationships/1 a relationship from model "data-graph-model:user" to model "data-graph-model:account" already exists; at most one relationship is allowed per source-target pair

Data Graph spec syntax must be valid

syntactic error

Rule ID: datagraph/data-graph/spec-syntax-valid

Examples

Valid Data Graph spec with entity and event models

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      root: true
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at
      relationships:
        - id: purchase-user
          display_name: Purchase User
          cardinality: many-to-one
          target: "#data-graph-model:user"
          source_join_key: user_id
          target_join_key: user_id

Data Graph missing required account_id

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph

Diagnostics

spec.yaml /account_id 'account_id' is required

Entity model missing required primary_id

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users

Diagnostics

spec.yaml /models/0/primary_id 'primary_id' is required for entity models

Event model missing required timestamp

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases

Diagnostics

spec.yaml /models/0/timestamp 'timestamp' is required for event models

Model table must use catalog.schema.table format

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: schema.users
      primary_id: user_id

Diagnostics

spec.yaml /models/0/table 'table' must be a 3-part reference in the format catalog.schema.table

Model and relationship names must be unique within a Data Graph

semantic error

Rule ID: datagraph/data-graph/unique-names-valid

Examples

Unique model and relationship display names within the Data Graph

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-order
          display_name: User Order
          cardinality: one-to-many
          target: "#data-graph-model:order"
          source_join_key: user_id
          target_join_key: user_id
    - id: order
      display_name: Order
      type: entity
      table: db.schema.orders
      primary_id: order_id

Duplicate model display names within a Data Graph

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
    - id: user-v2
      display_name: User
      type: entity
      table: db.schema.users_v2
      primary_id: user_id

Diagnostics

spec.yaml /models/0/display_name duplicate model display name "User"
spec.yaml /models/1/display_name duplicate model display name "User"

Duplicate relationship display names within a Data Graph

spec.yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-order
          display_name: Links To
          cardinality: one-to-many
          target: "#data-graph-model:order"
          source_join_key: user_id
          target_join_key: user_id
    - id: order
      display_name: Order
      type: entity
      table: db.schema.orders
      primary_id: order_id
      relationships:
        - id: order-product
          display_name: Links To
          cardinality: one-to-many
          target: "#data-graph-model:product"
          source_join_key: order_id
          target_join_key: order_id
    - id: product
      display_name: Product
      type: entity
      table: db.schema.products
      primary_id: product_id

Diagnostics

spec.yaml /models/0/relationships/0/display_name duplicate relationship display name "Links To"
spec.yaml /models/1/relationships/0/display_name duplicate relationship display name "Links To"

Sync to your workspace

Once validation passes, sync the data graph to your workspace:

rudder-cli apply -l data-graph.yaml

Data Graph YAML Reference

File structure

Top-level fields

Models

Model fields

Entity vs. event

Relationships

Relationship fields

Target reference format

Column metadata

Column fields

Complete example

Validate the data graph

Validation rules

Relationship cardinality must be valid for the source and target model types

Examples

Entity-to-entity relationship with any cardinality is valid

Event-to-entity relationship uses many-to-one cardinality

Event models cannot connect to other event models

Event-to-entity relationship requires many-to-one cardinality

Entity-to-event relationship requires one-to-many cardinality

Relationship target references must resolve to existing models

Examples

Relationship target references an existing model in the Data Graph

Relationship target references a missing model

At most one relationship is allowed per source-target model pair

Examples

Multiple relationships from one model to different targets are allowed

A-to-B and B-to-A relationships are distinct and both allowed

Duplicate source-target model pairs are not allowed

Data Graph spec syntax must be valid

Examples

Valid Data Graph spec with entity and event models

Data Graph missing required account_id

Entity model missing required primary_id

Event model missing required timestamp

Model table must use catalog.schema.table format

Model and relationship names must be unique within a Data Graph

Examples

Unique model and relationship display names within the Data Graph

Duplicate model display names within a Data Graph

Duplicate relationship display names within a Data Graph

Sync to your workspace

See also

Questions? We're here to help.