SchemaRelationships

Relationships

Relationships define how entity types connect to each other in your data schema. They enable cross-entity queries in Segment, power the ERD visualization, and provide the structural foundation for identity resolution and journey orchestration.

What Is a Relationship?

A relationship is a named, typed connection between two entity types. It specifies:

  • Which entity types are connected (e.g., User and Account)
  • The cardinality of the connection (one-to-one, one-to-many, many-to-many)
  • The join keys used to link records from each entity type
  • The direction of the relationship (which entity “owns” the connection)

Relationship Types

One-to-One

Each record in entity A is linked to exactly one record in entity B, and vice versa.

Example: A User has one Profile.

User (1) ────── (1) Profile
  user_id            user_id

One-to-Many

Each record in entity A can be linked to multiple records in entity B, but each record in B links to exactly one record in A.

Example: An Account has many Users.

Account (1) ────── (N) User
  account_id           account_id

This is the most common relationship type. Other examples:

  • A User has many Orders
  • An Account has many Subscriptions
  • A Category has many Products

Many-to-Many

Records in entity A can be linked to multiple records in entity B, and vice versa.

Example: Users can purchase many Products, and Products can be purchased by many Users.

User (N) ────── (M) Product

Many-to-many relationships are typically resolved through an intermediate model (a junction table):

-- Junction model: User-Product Purchases
SELECT DISTINCT user_id, product_id
FROM order_items oi
JOIN orders o ON oi.order_id = o.order_id

Creating a Relationship

Using the UI

  1. Navigate to Schema in the left sidebar
  2. Click Add Relationship (or use the context menu on an entity type)
  3. Select the source entity type (the “from” side)
  4. Select the target entity type (the “to” side)
  5. Choose the relationship type (one-to-one, one-to-many, many-to-many)
  6. Configure the join keys:
    • Select the attribute from the source entity that links to the target
    • Select the matching attribute from the target entity
  7. Give the relationship a name (e.g., “User belongs to Account”)
  8. Click Save

Using the API

curl -X POST https://your-workspace.signalsmith.dev/api/v1/relationships \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User belongs to Account",
    "source_entity_type_id": "et_user123",
    "target_entity_type_id": "et_account456",
    "type": "many_to_one",
    "source_key": "account_id",
    "target_key": "id"
  }'

Configuring Join Keys

Join keys define how records from two entity types are matched. The source key is an attribute on the source entity, and the target key is an attribute on the target entity. Records are linked when their join key values match.

Simple Join Key

The most common case — a foreign key on one entity references the primary key of another:

User                        Account
├── id (PK)                 ├── id (PK)
├── email                   ├── name
├── account_id ───────────▶ ├── domain
└── name                    └── industry
  • Source entity: User
  • Source key: account_id
  • Target entity: Account
  • Target key: id

Shared Key

Sometimes two entities share the same key without a formal foreign key:

User                        UserProfile
├── user_id (PK) ──────── ├── user_id (PK)
├── email                  ├── bio
└── name                   └── avatar_url
  • Source key: user_id
  • Target key: user_id

Relationship Direction

Relationships in SignalSmith have a direction, which affects how they’re queried in Segment:

  • Forward: “User belongs to Account” — from User to Account
  • Reverse: “Account has Users” — from Account to User (automatically created)

When you create a relationship, SignalSmith automatically creates the reverse relationship so you can traverse the graph in both directions.

How Relationships Are Used

Segment Audiences

Relationships enable cross-entity audience criteria. For example:

  • “Find Users whose Account has more than 100 employees” — Traverses the User-to-Account relationship
  • “Find Accounts with at least one User who made a purchase in the last 30 days” — Traverses Account-to-User and User-to-Order relationships
  • “Find Users who purchased a Product in the ‘Enterprise’ category” — Traverses User-to-Order and Order-to-Product relationships

Identity Resolution

Relationships help identity resolution understand the structure of your data. For example, knowing that Users belong to Accounts prevents merging users from different accounts that happen to share a phone number.

ERD Visualization

All relationships appear as connecting lines in the ERD visualization, showing the full structure of your data model at a glance.

Journey Orchestration

Journeys use relationships to enrich personalization context. For example, a journey triggered by a User event can pull Account attributes (like company name) through the User-to-Account relationship.

Example Schemas

E-Commerce

E-commerce entity relationships

Relationships:

  1. User has many Orders (one-to-many, join: User.id = Order.user_id)
  2. Order has many LineItems (one-to-many, join: Order.id = LineItem.order_id)
  3. LineItem refers to Product (many-to-one, join: LineItem.product_id = Product.id)

SaaS B2B

User ───belongs to──▸ Account ───has──▸ Subscription

UserAccountSubscription
id (PK)id (PK)id (PK)
emailnameaccount_id
account_iddomainplan
roleindustrystatus
mrr

Relationships:

  1. User belongs to Account (many-to-one, join: User.account_id = Account.id)
  2. Account has Subscriptions (one-to-many, join: Account.id = Subscription.account_id)

Managing Relationships

Editing a Relationship

To modify an existing relationship:

  1. Navigate to Schema in the sidebar
  2. Click on the relationship line in the ERD (or find it in the relationships list)
  3. Update the name, type, or join keys
  4. Click Save

Changing join keys may affect audiences and identity resolution rules that depend on the relationship.

Deleting a Relationship

  1. Navigate to Schema in the sidebar
  2. Select the relationship to delete
  3. Click Delete and confirm

SignalSmith warns if the relationship is used in audience definitions, identity resolution rules, or journey triggers.

Best Practices

  • Name relationships clearly — Use descriptive names like “User belongs to Account” rather than “User-Account”
  • Use correct cardinality — Misclassifying a one-to-many as many-to-many can lead to incorrect audience counts
  • Ensure join keys are indexed — For performance, make sure the columns used as join keys are indexed in your warehouse
  • Avoid circular relationships — While technically possible, circular relationships (A -> B -> C -> A) can cause confusion in audience queries
  • Start with core relationships — Define the most important relationships first (User-Account, User-Order) and add others incrementally

Next Steps

Entity TypesERD Visualization