Relationships

Relationships allow you to fetch related data from multiple tables in a single API call using the with parameter. Instead of making separate requests for each table, you can retrieve complex, interconnected data structures all at once.

Understanding Relationships

Relationships act as bridges between tables. When you have data split across multiple tables, relationships connect them using common field values.

How matching works

When we say fields "match," we mean the values stored in those fields are equal, not that the field names must be identical.

Matching Fields

USERS TABLE              ORDERS TABLE
┌────────────┐          ┌────────────────┐
│ user_id: 1 │ ──────→  │ customer_id: 1 │  ← Values match!
│ name       │          │ order_id       │
└────────────┘          └────────────────┘

Example with same field names:

Same Field Names

 GIVEAWAYS TABLE            FOODS TABLE
┌────────────────────┐     ┌────────────────────┐
│ date: "2025-07-18" │ ──→ │ date: "2025-07-18" │  ← Values match!
│ title              │     │ item               │
└────────────────────┘     └────────────────────┘

What the SDK does:

1. Retrieves the record from your main table
2. Extracts the value from the from field
3. Searches the related table for all records where the to field equals that value
4. Returns everything nested together in a single response

💡Key point

Field names can be the same (date → date) or different (user_id → customer_id). What matters is that the values inside those fields match.

Relationship parameters

Parameter	Type	Required	Description
fields	string[]	Yes	The specific fields to return from the related table.
on	object	Yes	The condition used to link the source table to the related table.
on.from	string	Yes	The field in the source table used for the join condition.
on.to	string	Yes	The field in the related table used for the join condition.
filter	Record<string, any>	No	An optional filter object to apply to the related records.
with	Record<string, IncludeParams>	No	An object specifying additional related tables to include from this relationship.

Manta Studio

TypeScript

const userWithOrders = await manta.fetchOneRecord({
  table: "users", // Source table
  where: { user_id: "user-1" },
  fields: ["user_id", "first_name", "last_name"],
  with: {
    orders: {
      // Related table
      fields: ["order_id", "product_name", "amount"],
      on: {
        from: "user_id", // Field in users table
        to: "customer_id", // Field in orders table
      },
    },
  },
});

PostgreSQL

TypeScript

const userWithOrders = await manta.fetchOneRecord({
  table: "users", // Source table
  where: { user_id: "user-1" },
  fields: ["user_id", "first_name", "last_name"],
  with: {
    orders: {
      // Related table
      fields: ["order_id", "product_name", "amount"],
      on: {
        from: "user_id", // Field in users table
        to: "customer_id", // Field in orders table
      },
    },
  },
});

Nested relationships

You can also fetch relationships within relationships. This example fetches a user, their orders, and the products within those orders.

Manta Studio

TypeScript

const userWithOrdersAndProducts = await manta.fetchOneRecord({
  table: 'users',
  where: { user_id: 'user-1' },
  fields: ['user_id', 'first_name', 'last_name'],
  with: {
    orders: {
      fields: ['order_id', 'product_id', 'amount'],
      on: { from: 'user_id', to: 'customer_id' },
      with: {
        products: {
          fields: ['product_id', 'name', 'price'],
          on: { from: 'product_id', to: 'product_id' }
        }
      }
    }
  }
});

PostgreSQL

TypeScript

const userWithOrdersAndProducts = await manta.fetchOneRecord({
  table: 'users',
  where: { user_id: 'user-1' },
  fields: ['user_id', 'first_name', 'last_name'],
  with: {
    orders: {
      fields: ['order_id', 'product_id', 'amount'],
      on: { from: 'user_id', to: 'customer_id' },
      with: {
        products: {
          fields: ['product_id', 'name', 'price'],
          on: { from: 'product_id', to: 'product_id' }
        }
      }
    }
  }
});