Documentation

Relationship Navigation

Explore connected data by following foreign key relationships between tables.

Overview

Simpl automatically detects foreign key relationships in your database and makes it easy to navigate between related records.

Relationship indicator on a record

Understanding Relationships

Foreign Keys

A foreign key is a column that references another table's primary key. For example:

  • orders.user_id → users.id
  • comments.post_id → posts.id
  • line_items.order_id → orders.id

Simpl detects these relationships during schema introspection and displays them visually.

Relationship Types

TypeDescriptionExample
OutgoingThis table references anotherOrder → User
IncomingOther tables reference this oneUser ← Orders

Outgoing Relationships

Visual Indicators

Foreign key columns appear with a violet pill in list and detail views:

Violet relationship pill

Following a Relationship

Click a foreign key field to navigate to the referenced record:

  1. See the violet relationship pill
  2. Click the pill or field
  3. Navigate to the referenced record's detail view

Clicking a foreign key to navigate

Incoming Relationships

Related Records Section

In the detail view, you'll see records from other tables that reference the current record:

Incoming relationships section

This section shows:

  • Table name - Which table has related records
  • Record count - How many related records exist
  • Preview - First few related records

Exploring Related Data

Click on a related table to:

  1. Navigate to that table
  2. With a pre-applied filter
  3. Showing only records related to the original

For example, viewing a User's related Orders:

/dashboard/c/{id}/orders?filters=user_id:eq:{userId}

Relationship Display

In List View

Foreign key fields appear as pills with:

  • Violet accent color
  • Referenced table name
  • Link arrow indicator

In Detail View

Foreign key fields show:

  • The referenced record's primary display field
  • Clickable link to the referenced record
  • Clear indication of the relationship direction

Incoming Relationships Panel

The detail view includes a panel showing:

  • All tables that reference this record
  • Count of related records per table
  • Quick links to view related data

Working with Relationships

Exploring Data Graphs

Navigate through your data by following relationships:

  1. Start at any record
  2. Click outgoing relationships to go "forward"
  3. Click incoming relationships to see "backward" references
  4. Build understanding of how data connects

Finding Related Records

Use relationships to answer questions like:

  • "Which orders belong to this user?"
  • "What comments are on this post?"
  • "Which products are in this category?"

Relationship Counts

The incoming relationships section shows counts:

  • "24 orders" - This user has 24 orders
  • "156 comments" - This post has 156 comments

Schema Requirements

Defining Relationships

For relationships to appear in Simpl, they must be defined in your database:

-- Foreign key definition
ALTER TABLE orders
ADD CONSTRAINT fk_user
FOREIGN KEY (user_id)
REFERENCES users(id);

No Foreign Key?

If columns reference other tables without a formal foreign key constraint, Simpl won't detect the relationship automatically. Consider:

  • Adding the foreign key constraint
  • Using naming conventions Simpl might recognize

Performance

Relationship Counts

Count queries for incoming relationships are optimized:

  • Uses PostgreSQL estimates when available
  • Falls back to COUNT(*) for accuracy
  • Caches within the session

Large Datasets

For tables with many related records:

  • Counts may be estimates
  • Preview shows only first few records
  • Click through for full listing

Best Practices

Use Proper Foreign Keys

Define foreign key constraints in your database to:

  • Enable relationship detection
  • Ensure data integrity
  • Improve query performance

Navigate Thoughtfully

When exploring relationships:

  • Use browser back/forward for navigation
  • Bookmark important records
  • Combine with filters for specific subsets

Understand Your Schema

Before diving into relationships:

  • Review your database schema
  • Identify key relationships
  • Understand the data model

Common Patterns

One-to-Many

User → Orders (one user, many orders)

  • From User: See list of their orders
  • From Order: See the owning user

Many-to-Many

Users ↔ Roles (via user_roles table)

  • Navigate through the join table
  • See role assignments per user
  • See users per role

Self-Referential

Categories with parent_id

  • Navigate to parent category
  • See child categories

Current Limitations

  • Named constraints only - Unnamed constraints may not be detected
  • Public schema - Relationships in other schemas need explicit handling
  • No composite keys - Multi-column foreign keys have limited support

Next Steps