Build
GraphQL applications
Give your app a GraphQL endpoint over your collections with no resolver code: you write a schema and say which collection answers each query.
GraphQL is a query language for APIs: the app asks for exactly the fields it needs, in one request. On Ulabase a GraphQL app is a schema and a mapping. The schema says which types and queries your app can ask for; the mapping says which collection answers each one.
Use it when your frontend speaks GraphQL, and each screen should get exactly the data it shows: an order with its customer, for example, in one request.
What you get:
-
No resolver code. Save the app under GraphQL and the endpoint is live at
/graphql/<uri>. -
Related data in one request. A field can look up a document in another collection, declared in one line of the mapping.
-
Several apps per service. Each app has its own schema and address.
An app in one document
{
"descriptor": { "name": "Shop", "description": "The shop's read API", "enabled": true, "uri": "shop" },
"schema": "type Query { orders(status: String): [Order] } type Order { _id: String status: String total: Float customer: User } type User { _id: String name: String }",
"mappings": {
"Query": {
"orders": { "db": "020009", "collection": "orders", "find": { "status": { "$arg": "status" } } }
},
"Order": {
"customer": { "db": "020009", "collection": "users", "find": { "_id": { "$fk": "customerId" } } }
}
}
}
-
descriptor: the name, the
urithe endpoint is served at, andenabled, which takes the app offline without deleting it. -
schema: the GraphQL SDL, as a string. Types, queries, and mutations if you want them.
-
mappings: for each type, how each field is resolved. A root field names a
dband acollectionand optionallyfind,sort,limitandskip.$argputs a query argument into the filter, soorders(status: "pending")becomesfind({status: "pending"}).$fktakes a value from the parent document, which is howOrder.customerlooks up the user: a join, declared in one line.
On Free, Starter and Pro the database is the service’s own, named by its id: write the id, here 020009, and if you write another name the service sets it back to its own and says so in the response. On Enterprise, name the database you use.
Create one
Click New app. The Visual editor gives you a field for each part. The JSON editor takes the whole document, for one you paste from git. Both check what you type, and Format tidies the JSON. Save, and the endpoint answers. Changes take effect at once.
Each app in the list has an enable switch, Edit, Delete, and a copy icon for the endpoint address.
Call it from your app
const res = await fetch('https://c0ffee.ulabase.app/graphql/shop', {
method: 'POST',
headers: { 'Authorization': 'Basic ' + btoa('alice:secret'), 'Content-Type': 'application/json' },
body: JSON.stringify({
query: 'query Orders($status: String) { orders(status: $status) { _id total customer { name } } }',
variables: { status: 'pending' }
})
});
const { data } = await res.json();
The user needs a permission on /graphql/shop. Any GraphQL client works: paste the endpoint address into it.
From a script
Apps are documents in the gql-apps collection, /restheart/gql-apps on Enterprise:
| Operation | API |
|---|---|
List |
|
Create |
|
Update |
|
Delete |
|
Query |
|
Do it from the command line
You can keep a GraphQL app in git and apply it with ulabase setup. The app is the JSON document shown above, saved in a file. The step writes it to /gql-apps/<id>:
import { readFileSync } from 'node:fs';
import { defineSetup, step, isApiError } from '@ulabase/cli';
const id = 'shop';
// the app, read from a JSON file in the repository
const app = JSON.parse(readFileSync('graphql/shop.json', 'utf8'));
export default defineSetup('GraphQL', [
step('shop app stored', {
async check({ service }) {
try {
// the app is up to date when its schema and mappings match the file
const stored = await (await service.fetch(`/gql-apps/${id}`)).json();
return stored.schema === app.schema
&& JSON.stringify(stored.mappings) === JSON.stringify(app.mappings);
} catch (e) {
// 404: the app does not exist yet, so the apply creates it
if (isApiError(e) && e.status === 404) return false;
throw e;
}
},
apply: ({ service }) =>
// ?wm=upsert creates the app on the first run and replaces it on later runs
service.fetch(`/gql-apps/${id}?wm=upsert`, { method: 'PUT', body: JSON.stringify(app) }),
}),
]);
The id can use lower-case letters, digits, - and _. The first run creates the app, and later runs replace it with the file.
Related pages
-
Collections and documents: the data the apps resolve against.
-
MCP server: a GraphQL app you publish is one an AI agent can query too.
-
Permissions: who may query which app.