steedos-graphql-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Steedos GraphQL API | Steedos GraphQL 接口

Steedos GraphQL API 接口

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 自动更新。

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
```
)

POST /graphql

认证方式：
```
Authorization: Bearer {token}
```
请求头，或基于Cookie的会话
内容类型：
```
application/json
```
Apollo Playground：默认在
```
/graphql
```
路径启用（由环境变量
```
STEEDOS_GRAPHQL_ENABLE_CONSOLE
```
控制）

Queries | 查询

查询

For each object (e.g.,

orders

), three queries are auto-generated:

每个对象（例如

orders

）会自动生成三种查询操作：

List Records —

{objectName}

列表查询 —

{objectName}

graphql

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

graphql

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

Find One —

{objectName}__findOne

单条查询 —

{objectName}__findOne

graphql

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

graphql

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

Count —

{objectName}__count

数量统计 —

{objectName}__count

graphql

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

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"`

参数	类型	是否必填	默认值	描述
`filters`	JSON	否	无	OData风格的筛选数组，例如 `[["name", "contains", "test"]]`
`fields`	JSON	否	所有字段	需要返回的字段名称数组
`top`	Int	是	10000	返回的最大记录数（上限为10,000）
`skip`	Int	是	0	分页偏移量
`sort`	String	否	无	排序表达式，例如 `"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"]]

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

筛选示例：

json

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

Mutations | 变更

变更操作

Insert —

{objectName}__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.

graphql

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

space

字段会从已认证用户的会话中自动注入。

Update —

{objectName}__update

更新 —

{objectName}__update

graphql

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

graphql

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

Delete —

{objectName}__delete

删除 —

{objectName}__delete

graphql

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

Respects the object's

enable_trash

setting — soft-delete or hard-delete accordingly.

graphql

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

会遵循对象的

enable_trash

设置，执行软删除或硬删除。

Special Fields | 特殊字段

特殊字段

Lookup Expansion —

__expand

关联扩展 —

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

扩展关联/主明细引用，获取完整的关联记录：

graphql

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    customer              # 返回原始ID: "cust_abc123"
    customer__expand {    # 返回扩展后的对象
      _id
      name
      email
      phone
    }
  }
}

Display Formatting —

_display

显示格式化 —

_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"
    }
  }
}

获取本地化的格式化字段值：

graphql

{
  orders__findOne(id: "67abc123def456") {
    _id
    amount                # 原始值: 5000
    status                # 原始值: "approved"
    _display {
      amount              # 格式化后: "¥5,000.00"
      status              # 本地化标签: "已批准"
      created             # 格式化日期: "2026-04-23 10:00"
    }
  }
}

Record Permissions —

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

检查当前用户对记录的操作权限：

graphql

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

Related Records —

_related_*

关联记录 —

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

访问关联的子记录、文件、任务等：

graphql

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    _related_order_items_order {  # 通过关联字段"order"获取明细记录
      _id
      product
      quantity
      price
    }
    _related_files {
      _id
      name
    }
    _related_tasks {
      _id
      name
      status
    }
    _related_notes {
      _id
      body
    }
  }
}

关联字段命名规则：

_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`

Steedos字段类型	GraphQL类型
text, textarea, html, url, email	`String`
number, currency, percent	`Float`
boolean	`Boolean`
date, datetime, time	`Date`
select（单选）	`String`
select（多选）	`[String]`
lookup, master_detail	`JSON` （原始值） + `__expand` （引用类型）
image, file	`JSON`
formula, summary	取决于返回类型
其他	`JSON`

Authentication | 认证

认证

GraphQL requests require authentication via one of:

bash

undefined

GraphQL请求需要通过以下方式之一进行认证：

bash

undefined

Bearer token

Bearer令牌

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

Cookie-based session (from browser)

基于Cookie的会话（浏览器环境）

Cookies: X-Space-Id, X-Auth-Token


Unauthenticated requests return `UnAuthorizedError`.


未认证的请求会返回`UnAuthorizedError`。

DataLoader Batching | DataLoader 批量优化

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

GraphQL查询会自动使用DataLoader在单个请求中批量处理并缓存数据库查询，避免在扩展关联字段时出现N+1查询问题。

由环境变量控制：

STEEDOS_GRAPHQL_ENABLE_DATALOADER=true  # 默认值

Complete Example | 完整示例

完整示例

graphql

undefined

graphql

undefined

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


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

undefined

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

undefined

Environment Variables | 环境变量

环境变量

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

变量	默认值	描述
`STEEDOS_GRAPHQL_ENABLE_CONSOLE`	`true`	启用/graphql路径下的Apollo Playground
`STEEDOS_GRAPHQL_ENABLE_DATALOADER`	`true`	启用DataLoader批量处理

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

每次查询最多返回10,000条记录（
```
top
```
参数）
请求/响应体最大为10MB
不支持订阅（实时更新请使用WebSocket，详见steedos-server-websocket）
默认排除已删除的记录（
```
is_deleted: true
```
）