Skip to content
excalibase
relationships
REST APIstable

Relationships

On Excalibase Cloud

A REST read embeds related rows when select names the related table with the columns to take, in either direction of a foreign key:

curl -s "$BASE/$PROJECT_ID/api/v1/live_poll_polls?select=id,question,live_poll_options(position,label)&limit=1" \
  -H "Authorization: Bearer $TOKEN"
{ "data": [{ "id": "ec0b3c06-…", "question": "Which example should we build next?",
  "live_poll_options": [{ "label": "Chat room", "position": 0 }, { "label": "Guestbook", "position": 1 }] }] }

?expand= is not part of a cloud project's REST API (it answers 400 Unknown column 'expand').

In GraphQL, foreign keys become nested fields, with no join to write. A referenced table gets a list field for the rows that point at it:

{
  publicLivePollPolls(limit: 1) {
    id
    question
    publicLivePollOptions(orderBy: { position: ASC }) {
      position
      label
    }
  }
}

Each nested field or embedded table is filtered by the caller's permissions on the table it reaches, the same as a direct read of that table. Include the foreign key column in the selection of a many-to-one GraphQL field; the resolver reads it. The nested list takes where, orderBy, limit and offset like any other list.

curl -s -X POST "$BASE/$PROJECT_ID/graphql" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ publicLivePollPolls(limit: 1) { question publicLivePollOptions { label } } }"}'

Self-hosting

This section is for the standalone excalibase-rest service, which also expands relationships inline with ?expand=. expand is self-hosted only; on a cloud project, embed with select as above.

Foreign keys are detected automatically; ?expand= includes 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
      }
    }
  }]
}