# 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.

## 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

| Type     | Description                             | Example            |
|----------|-----------------------------------------|--------------------|
| Outgoing | This table references another            | Order → User       |
| Incoming | Other tables reference this one          | User ← Orders      |

## Outgoing Relationships

### Visual Indicators

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

### 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

## Incoming Relationships

### Related Records Section

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

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:
```sql
-- 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

- [Use keyboard shortcuts](/content/docs/features/keyboard-shortcuts/index.html) for faster navigation
- [Export related data](/content/docs/features/export/index.html) together
- [Customize layouts](/content/docs/features/layouts/index.html) to highlight relationships