Steedos GraphQL API | Steedos GraphQL 接口

Overview | 概述

Steedos provides a GraphQL API that is auto-generated from object metadata. Every Steedos object automatically gets GraphQL queries and mutations — no manual schema definition required. The schema updates dynamically when objects or fields change.

Steedos 提供的 GraphQL API 根据对象元数据自动生成。每个 Steedos 对象自动获得 GraphQL 查询和变更操作，无需手动定义 Schema。对象或字段变更时 Schema 自动更新。

Endpoint | 端点

POST /graphql

Authentication:
```
Authorization: Bearer {token}
```
header, or cookie-based session
Content-Type:
```
application/json
```
Apollo Playground: Enabled by default at
```
/graphql
```
(controlled by
```
STEEDOS_GRAPHQL_ENABLE_CONSOLE
```
)

Queries | 查询

For each object (e.g.,

orders

), three queries are auto-generated:

List Records —

{objectName}

graphql

{
  orders(
    filters: [["status", "=", "approved"]]
    fields: ["_id", "name", "amount"]
    top: 20
    skip: 0
    sort: "created desc"
  ) {
    _id
    name
    amount
    status
  }
}

Find One —

{objectName}__findOne

graphql

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    amount
    customer
  }
}

Count —

{objectName}__count

graphql

{
  orders__count(filters: [["status", "=", "draft"]])
}

Query Parameters | 查询参数

Parameter	Type	Required	Default	Description
`filters`	JSON	No	none	OData-style filter array, e.g. `[["name", "contains", "test"]]`
`fields`	JSON	No	all	Array of field names to return
`top`	Int	Yes	10000	Max records to return (max 10,000)
`skip`	Int	Yes	0	Pagination offset
`sort`	String	No	none	Sort expression, e.g. `"created desc"` , `"name asc, amount desc"`

Filter Operators | 筛选运算符

=, !=, >, >=, <, <=
contains, notcontains, startswith
in, notin
between

Example filters:

json

[["status", "=", "active"]]
[["amount", ">", 1000], ["status", "in", ["draft", "submitted"]]]
[["name", "contains", "test"]]

Mutations | 变更

Insert —

{objectName}__insert

graphql

mutation {
  orders__insert(doc: {
    name: "ORD-2026-001",
    customer: "cust_abc123",
    amount: 5000,
    status: "draft"
  }) {
    _id
    name
    amount
  }
}

The

space

field is auto-injected from the authenticated user's session.

Update —

{objectName}__update

graphql

mutation {
  orders__update(
    id: "67abc123def456",
    doc: { status: "approved", approved_at: "2026-04-23T10:00:00Z" }
  ) {
    _id
    name
    status
  }
}

Delete —

{objectName}__delete

graphql

mutation {
  orders__delete(id: "67abc123def456")
}

Respects the object's

enable_trash

setting — soft-delete or hard-delete accordingly.

Special Fields | 特殊字段

Lookup Expansion —

__expand

Expand lookup/master_detail references to get the full related record:

graphql

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    customer              # Returns raw ID: "cust_abc123"
    customer__expand {    # Returns expanded object
      _id
      name
      email
      phone
    }
  }
}

Display Formatting —

_display

Get localized, formatted field values:

graphql

{
  orders__findOne(id: "67abc123def456") {
    _id
    amount                # Raw value: 5000
    status                # Raw value: "approved"
    _display {
      amount              # Formatted: "¥5,000.00"
      status              # Localized label: "已批准"
      created             # Formatted date: "2026-04-23 10:00"
    }
  }
}

Record Permissions —

_permissions

Check what the current user can do with a record:

graphql

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    _permissions {
      allowCreate
      allowEdit
      allowDelete
      field_permissions
    }
  }
}

Related Records —

_related_*

Access related child records, files, tasks, etc.:

graphql

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    _related_order_items_order {  # Detail records via lookup field "order"
      _id
      product
      quantity
      price
    }
    _related_files {
      _id
      name
    }
    _related_tasks {
      _id
      name
      status
    }
    _related_notes {
      _id
      body
    }
  }
}

Related field naming:

_related_{childObjectName}_{lookupFieldName}

Field Type Mapping | 字段类型映射

Steedos Field Type	GraphQL Type
text, textarea, html, url, email	`String`
number, currency, percent	`Float`
boolean	`Boolean`
date, datetime, time	`Date`
select (single)	`String`
select (multiple)	`[String]`
lookup, master_detail	`JSON` (raw) + `__expand` (referenced type)
image, file	`JSON`
formula, summary	Depends on return type
Other	`JSON`

Authentication | 认证

GraphQL requests require authentication via one of:

bash

# Bearer token
curl -X POST /graphql \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ space_users { _id name } }"}'

# Cookie-based session (from browser)
# Cookies: X-Space-Id, X-Auth-Token

Unauthenticated requests return

UnAuthorizedError

DataLoader Batching | DataLoader 批量优化

GraphQL queries automatically use DataLoader to batch and cache database lookups within a single request, preventing N+1 query problems when expanding lookup fields.

Controlled by environment variable:

STEEDOS_GRAPHQL_ENABLE_DATALOADER=true  # default

Complete Example | 完整示例

graphql

# Fetch orders with expanded customer, display values, and permissions
{
  orders(
    filters: [["status", "in", ["submitted", "approved"]], ["amount", ">", 1000]]
    sort: "amount desc"
    top: 10
  ) {
    _id
    name
    amount
    status
    order_date
    customer__expand {
      _id
      name
      phone
    }
    _display {
      amount
      status
      order_date
    }
    _permissions {
      allowEdit
      allowDelete
    }
  }
}

graphql

# Create an order and return the new record
mutation {
  orders__insert(doc: {
    name: "ORD-2026-042",
    customer: "cust_abc123",
    amount: 8500,
    status: "draft",
    order_date: "2026-04-23"
  }) {
    _id
    name
    amount
    customer__expand {
      name
    }
  }
}

Environment Variables | 环境变量

Variable	Default	Description
`STEEDOS_GRAPHQL_ENABLE_CONSOLE`	`true`	Enable Apollo Playground at /graphql
`STEEDOS_GRAPHQL_ENABLE_DATALOADER`	`true`	Enable DataLoader batching

Limitations | 限制

Max 10,000 records per query (
```
top
```
parameter)
Max 10MB request/response body
No subscriptions (real-time updates use WebSocket instead, see steedos-server-websocket)
Deleted records (
```
is_deleted: true
```
) are excluded by default

steedos-graphql-api

NPX Install

Tags

SKILL.md Content

Steedos GraphQL API | Steedos GraphQL 接口

Overview | 概述

Endpoint | 端点

Queries | 查询

List Records —
`{objectName}`

Find One —
`{objectName}__findOne`

Count —
`{objectName}__count`

Query Parameters | 查询参数

Filter Operators | 筛选运算符

Mutations | 变更

Insert —
`{objectName}__insert`

Update —
`{objectName}__update`

Delete —
`{objectName}__delete`

Special Fields | 特殊字段

Lookup Expansion —
`__expand`

Display Formatting —
`_display`

Record Permissions —
`_permissions`

Related Records —
`_related_*`

Field Type Mapping | 字段类型映射

Authentication | 认证

DataLoader Batching | DataLoader 批量优化

Complete Example | 完整示例

Environment Variables | 环境变量

Limitations | 限制