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}

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

Find One — {objectName}__findOne

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

Count — {objectName}__count

{
  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:

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

Mutations | 变更

Insert — {objectName}__insert

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

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

Delete — {objectName}__delete

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:

{
  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:

{
  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:

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

Related Records — _related_*

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

{
  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:

# 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 | 完整示例

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

# 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-internals)
• Deleted records (is_deleted: true) are excluded by default