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
}
}
}]
}