Relationship Expansion

Foreign keys are automatically detected — use ?expand= to include related rows inline.

Forward (many-to-one)

# Each rental includes its customer
GET /api/v1/rental?expand=customer&limit=5

{
  "data": [{
    "rental_id": 1,
    "customer_id": 130,
    "customer": {
      "customer_id": 130,
      "first_name": "CHARLOTTE",
      "last_name": "HUNTER",
      "email": "charlotte.hunter@sakilacustomer.org"
    },
    "rental_date": "2005-05-24T22:53:30"
  }]
}

Reverse (one-to-many)

# Each customer includes their payments array
GET /api/v1/customer?expand=payment&limit=3

Parameterized expansion

Control what's included in the expansion:

# Only the last 3 rentals, selecting specific columns
GET /api/v1/customer?expand=rental(limit:3,select:rental_id,rental_date,return_date)

Multiple expansions

GET /api/v1/rental?expand=customer,inventory&limit=10

Nested expansion

# rental → inventory → film
GET /api/v1/rental?expand=inventory(expand:film)&limit=5

Response format

All expanded relations are included inline:

{
  "data": [{
    "rental_id": 76,
    "inventory_id": 3021,
    "inventory": {
      "inventory_id": 3021,
      "film_id": 639,
      "film": {
        "film_id": 639,
        "title": "MISSION ZOOLANDER",
        "rental_rate": 4.99
      }
    }
  }]
}