---
title: "Defining Table Relations"
description: "Defining table relations allows you to establish how different tables in your database are connected to one another. By explicitly linking these tables, you can easily query data across related ent..."
last_updated: "2026-07-02T09:37:14.219099+00:00"
canonical_url: "https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/defining-table-relations"
---

Defining table relations allows you to establish how different tables in your database are connected to one another. By explicitly linking these tables, you can easily query data across related entities—for example, retrieving a specific user along with all of their associated posts.

## Understanding Table Relations

In our system, relations are defined using two primary helper functions:

*   **`one`**: Defines a one-to-one relationship. Use this when a record in your source table is associated with a single record in another table (e.g., one user has one profile).
*   **`many`**: Defines a one-to-many relationship. Use this when a record in your source table is associated with multiple records in another table (e.g., one user has many posts).

## Setting Up Relations

You can define these relationships using the `relations` function. This function takes your source table and a configuration block where you define how it relates to other tables.

```typescript
export const usersRelations = relations(users, ({ many, one }) => ({
  posts: many(posts),
  profile: one(profiles),
}));
```

## Key Concepts

| Term | Definition |
| :--- | :--- |
| **Source Table** | The table where you are currently defining the relation. |
| **Referenced Table** | The target table you are linking to. |
| **Relation Name** | An optional identifier used when multiple relations exist between the same two tables. |
| **One-to-One** | A relationship where a single record relates to exactly one other record. |
| **One-to-Many** | A relationship where a single record relates to multiple records in the target table. |

> [!TIP]
> If you have multiple relationships between the same two tables, ensure you provide a unique `relationName` for each to avoid ambiguity during data retrieval.

> [!WARNING]
> While relations make queries simpler, defining complex circular dependencies can sometimes lead to unexpected behavior. Keep your relationship structure as flat and logical as possible.

## Workflow Summary

The following diagram illustrates how the system processes your relation definitions:

```mermaid
graph LR
    A[User defines 'relations'] --> B[System parses schema]
    B --> C[System maps table connections]
    C --> D[User executes query with 'with' config]
    D --> E[System retrieves joined data]
```

## Advanced Configuration

When defining a `one` relationship, you can explicitly map specific columns if the relationship does not follow standard naming conventions. By providing the `fields` (from the source table) and `references` (from the target table), you maintain full control over how data is joined.

> [!NOTE]
> In most cases, the system can automatically infer these links. Only provide explicit column mappings if your database structure requires specific, non-standard key linking.

## Related

- [Declaring Database Schemas](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-database-schemas)
- [Querying and Mutating Data](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/querying-and-mutating-data)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/llms.txt) for all pages in this wiki.