Queries & Mutations
All entities support list queries, by-ID queries, and create/update/delete mutations.
List Queries
query
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
query {
customerList(
pagination: { page: 1, per_page: 20 }
filter: {
query: [{
condition: {
field: "status"
operator: equal
value: "active"
}
}]
sortby: [{ field: "created_at", order: desc }]
}
) {
data {
id
name
email
created_at
}
pagination {
current_page
per_page
total
last_page
has_more_pages
}
}
}Pagination
| Input | Type | Default | Description |
|---|---|---|---|
page | Int | 1 | Page number (starts at 1) |
per_page | Int | 20 | Items per page |
| Response | Type | Description |
|---|---|---|
current_page | Int | Current page number |
per_page | Int | Items per page |
total | Int | Total number of items |
last_page | Int | Last page number |
has_more_pages | Boolean | Whether more pages exist |
By-ID Queries
query
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
query {
customerById(id: "abc123") {
data {
id
name
email
company {
data {
id
name
}
}
orders {
data {
id
total
created_at
}
}
}
}
}Relations
Relations are available on all entities. Use the data wrapper to access related records:
query
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
query {
orderList {
data {
id
total
# ManyToOne relation
customer {
data {
id
name
}
}
# OneToMany relation
line_items {
data {
id
product_name
quantity
price
}
}
}
}
}Nested Pagination
OneToMany relations also support pagination. Add a pagination field to limit results.
System Fields
Every entity includes:
| Field | Type | Description |
|---|---|---|
id | ID | Unique identifier (UUID) |
integer_id | Int | Auto-incrementing ID |
created_at | DateTime | Creation timestamp (ISO 8601) |
updated_at | DateTime | Last update timestamp (ISO 8601) |
Create
mutation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
mutation {
createCustomer(
input: {
name: "Acme Corp"
email: "contact@acme.com"
status: "active"
}
) {
data {
id
name
email
status
created_at
}
}
}Creating with Relations
Use _connect to link to existing records:
mutation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
mutation {
createOrder(
input: {
total: 150.00
status: "pending"
customer_connect: [{ id: "customer-123" }]
}
) {
data {
id
total
customer {
data { id name }
}
}
}
}Update
mutation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
mutation {
updateCustomer(
input: {
id: "customer-123"
name: "Acme Corporation"
status: "premium"
}
) {
data {
id
name
status
updated_at
}
}
}Managing Relations
| Suffix | Action |
|---|---|
_connect | Add relations |
_disconnect | Remove relations |
_set | Replace all relations |
mutation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
mutation {
updateOrder(
input: {
id: "order-123"
line_items_connect: [{ id: "item-1" }, { id: "item-2" }]
line_items_disconnect: [{ id: "item-old" }]
}
) {
data {
id
line_items { data { id } }
}
}
}Delete
Pass an array of IDs to delete one or more records:
mutation
1
2
3
4
5
6
7
mutation {
deleteCustomer(ids: ["customer-1", "customer-2"]) {
data {
success
}
}
}Soft Delete
By default, deletions are soft deletes. Records are marked with a deleted_at timestamp but
remain in the database. Contact support to configure hard deletes.
Input Types
| Type | Used For |
|---|---|
Create{Entity}Input | Create mutations |
Update{Entity}Input | Update mutations |
The update input always requires the id field. Other fields are optional.
Error Handling
response
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"errors": [
{
"message": "Validation failed",
"extensions": {
"code": "VALIDATION_ERROR",
"field": "email",
"details": "Email already exists"
}
}
],
"data": null
}| Code | Description |
|---|---|
VALIDATION_ERROR | Input validation failed |
NOT_FOUND | Record not found |
UNAUTHORIZED | Missing or invalid authentication |
FORBIDDEN | Insufficient permissions |