OpenAPI 接口

基础地址为 https://api.chaintable.com。认证配置见身份认证，公共响应格式、错误处理和 CU 消耗见接口调用。

凭证访问范围

Personal Access Token 可访问本页列出的全部 OpenAPI 接口，具体操作仍受用户权限约束。Access Key 用于生产应用和服务的大规模调用，仅支持以下接口，资源访问受所属账户权限约束：

Method	Path	用途
`POST`	/v1/function/invoke	调用 Function
`POST`	/v1/leafage/{chain_id}	调用 Leafage

Personal Access Token 请求须带 X-Account-ID；Access Key 自动使用所属账户，若提供该请求头则必须匹配。 GET 参数放在查询字符串中，POST 参数放在 JSON 请求体中。嵌套字段的“必填”仅在提供所属对象时适用；可选字段不等于可传 null，以类型说明为准。返回字段描述 data，可选关联信息仅在对应条件下返回。示例中的 ID 和结果为示意数据，请替换为自己的资源；凭证从环境变量读取。展开对象或数组可查看子字段；object[] 表示对象数组。

接口列表

space

GET /v1/space — 读取 Space

id 为 Space ID。不存在时 data 为 null。Method: GET
Path: /v1/space参数

字段	类型	必填	说明
`id`	`string`	是	Space ID；1–64 字符

返回字段对象不存在时，data 为 null。

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl --get https://api.chaintable.com/v1/space \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=demo

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo",
    "description": "Example resources",
    "account_id": "0190000000007000800000000000000b",
    "status": "active",
    "visibility": "public",
    "dep_count": 0,
    "content_count": 6,
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "account": {
      "id": "0190000000007000800000000000000b",
      "type": "org",
      "slug": "example-team",
      "display_name": "Example team",
      "avatar_url": null,
      "avatar_thumbnail_url": null
    }
  }
}

GET /v1/space/list — 列出可见 Space

列出可见 Space。Method: GET
Path: /v1/space/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 1000；默认 `100`
`account_id`	`string` / `null`	否	账户 ID；32–32 字符；格式：`^[0-9a-f]{32}$`
`order_by`	`string`	否	排序字段；取值：`"id"`, `"created_at"`, `"updated_at"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	Space 的可见范围
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息
`table_count`	`integer`	Space 中的数据表数量

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl --get https://api.chaintable.com/v1/space/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode start=0 \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "demo",
        "description": "Example resources",
        "account_id": "0190000000007000800000000000000b",
        "status": "active",
        "visibility": "public",
        "dep_count": 0,
        "content_count": 6,
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "account": {
          "id": "0190000000007000800000000000000b",
          "type": "org",
          "slug": "example-team",
          "display_name": "Example team",
          "avatar_url": null,
          "avatar_thumbnail_url": null
        },
        "table_count": 1
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

table

行读取接口将 64 位整数、UINT256 和 DECIMAL 值表示为字符串，避免精度损失。字段类型见数据类型。

GET /v1/table — 读取表定义

id 为完整表 ID。通常保留 is_l1=false；访问派生数据表时可指定 true。Method: GET
Path: /v1/table参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`is_l1`	`boolean`	否	是否读取派生数据表定义；默认 `false`

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`chain_id`	`string` / `null`	平台链标识，如 eth；非区块表为空字符串或 null
`table_type`	`string`	表类型
`description`	`string` / `null`	用途说明
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`columns`	`object[]`	已初始化的字段定义；列表接口不返回
`indexes`	`object[]`	已初始化的索引；列表接口不返回
`view`	`object` / `null`	表展示配置
`start_height`	`integer` / `null`	起始区块高度
`deps`	`integer`	读取该表的依赖数量
`last_write_at_ms`	`integer` / `null`	最后写入时间，Unix 毫秒；没有记录时为 null
`first_write_at`	`number` / `null`	首次写入时间，Unix 秒；时间表返回
`inited`	`boolean`	是否已初始化；表详情及结构操作返回
`table_rows`	`integer`	表的记录数
`table_size`	`integer`	表的数据大小，单位为字节
`replica_num`	`integer`	副本数量
`s3_synced_at`	`number` / `null`	数据同步时间，Unix 秒
`subtables`	`object[]`	该表关联的数据表
`parent`	`object`	所属主表的 ID 和类型
`label`	`string`	说明文字或展示分类
`relations`	`object[]`	相关数据表

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 columns — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string`	名称
`type`	`string`	字段逻辑类型，取值见数据类型参考，见数据类型
`is_system`	`boolean`	是否为系统字段或索引

显示 indexes — 每项的字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`columns`	`string[]`	按索引顺序排列的字段名
`is_primary`	`boolean`	是否为主键索引
`is_system`	`boolean`	是否为系统字段或索引
`is_hidden`	`boolean`	是否隐藏索引

显示 view — 每个值的字段

字段	类型	说明
`sort`	`integer`	列的展示顺序，从 0 开始

显示 subtables — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

显示 parent — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`table_type`	`string`	表类型

显示 relations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

请求示例

curl --get https://api.chaintable.com/v1/table \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=demo.asset_notes

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.asset_notes",
    "space": "demo",
    "name": "asset_notes",
    "chain_id": "",
    "table_type": "normal",
    "description": "Asset notes",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "columns": [
      {
        "id": "id",
        "name": "id",
        "type": "STRING",
        "is_system": true
      },
      {
        "id": "note",
        "name": "note",
        "type": "STRING",
        "is_system": false
      }
    ],
    "indexes": [
      {
        "columns": [
          "id"
        ],
        "is_primary": true,
        "is_system": true
      }
    ],
    "table_rows": 1,
    "table_size": 64,
    "replica_num": 1,
    "inited": true,
    "subtables": [],
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "view": {
      "id": {
        "sort": 0
      },
      "note": {
        "sort": 1
      }
    },
    "deps": 0,
    "last_write_at_ms": 1788220800000
  }
}

POST /v1/table/columns/update — 更新表字段

整体替换字段定义；保留需要的已有字段，不能改变已有字段类型，也不能删除索引引用的字段。Method: POST
Path: /v1/table/columns/update参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`columns`	`object[]`	是	字段定义
`view`	`object` / `null`	否	表展示配置

显示 columns — 每项的字段

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–64 字符
`name`	`string`	是	名称；1–64 字符
`type`	`string`	是	字段逻辑类型，取值见数据类型参考，见数据类型；≥ 1 字符

显示 view — 每个值的字段

字段	类型	必填	说明
`sort`	`integer`	否	列的展示顺序，从 0 开始

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`chain_id`	`string` / `null`	平台链标识，如 eth；非区块表为空字符串或 null
`table_type`	`string`	表类型
`description`	`string` / `null`	用途说明
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`columns`	`object[]`	已初始化的字段定义；列表接口不返回
`indexes`	`object[]`	已初始化的索引；列表接口不返回
`view`	`object` / `null`	表展示配置
`start_height`	`integer` / `null`	起始区块高度
`deps`	`integer`	读取该表的依赖数量
`last_write_at_ms`	`integer` / `null`	最后写入时间，Unix 毫秒；没有记录时为 null
`first_write_at`	`number` / `null`	首次写入时间，Unix 秒；时间表返回
`inited`	`boolean`	是否已初始化；表详情及结构操作返回
`table_rows`	`integer`	表的记录数
`table_size`	`integer`	表的数据大小，单位为字节
`replica_num`	`integer`	副本数量
`s3_synced_at`	`number` / `null`	数据同步时间，Unix 秒
`subtables`	`object[]`	该表关联的数据表
`parent`	`object`	所属主表的 ID 和类型
`label`	`string`	说明文字或展示分类
`relations`	`object[]`	相关数据表

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 columns — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string`	名称
`type`	`string`	字段逻辑类型，取值见数据类型参考，见数据类型
`is_system`	`boolean`	是否为系统字段或索引

显示 indexes — 每项的字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`columns`	`string[]`	按索引顺序排列的字段名
`is_primary`	`boolean`	是否为主键索引
`is_system`	`boolean`	是否为系统字段或索引
`is_hidden`	`boolean`	是否隐藏索引

显示 view — 每个值的字段

字段	类型	说明
`sort`	`integer`	列的展示顺序，从 0 开始

显示 subtables — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

显示 parent — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`table_type`	`string`	表类型

显示 relations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/table/columns/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "demo.asset_notes",
  "columns": [
    {
      "id": "id",
      "name": "id",
      "type": "STRING"
    },
    {
      "id": "note",
      "name": "note",
      "type": "STRING"
    }
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.asset_notes",
    "space": "demo",
    "name": "asset_notes",
    "chain_id": "",
    "table_type": "normal",
    "description": "Asset notes",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "columns": [
      {
        "id": "id",
        "name": "id",
        "type": "STRING",
        "is_system": true
      },
      {
        "id": "note",
        "name": "note",
        "type": "STRING",
        "is_system": false
      }
    ],
    "indexes": [
      {
        "columns": [
          "id"
        ],
        "is_primary": true,
        "is_system": true
      }
    ],
    "table_rows": 1,
    "table_size": 64,
    "replica_num": 1,
    "inited": true,
    "subtables": [],
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "view": {
      "id": {
        "sort": 0
      },
      "note": {
        "sort": 1
      }
    },
    "deps": 0,
    "last_write_at_ms": 1788220800000
  }
}

POST /v1/table/columns/validate — 校验字段名

校验字段名。Method: POST
Path: /v1/table/columns/validate参数

字段	类型	必填	说明
`name`	`string`	是	名称；≥ 1 字符

返回字段

字段	类型	说明
`is_valid`	`boolean`	名称是否有效
`reason`	`string` / `null`	原因；没有原因时为 null

请求示例

curl https://api.chaintable.com/v1/table/columns/validate \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "name": "note"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "is_valid": true,
    "reason": null
  }
}

POST /v1/table/create — 创建数据表

表 ID 由 space.name 组成，总长度不超过 64 个字符。区块表名称需要对应的链后缀，chain_id 使用 eth 等链标识。Method: POST
Path: /v1/table/create参数

字段	类型	必填	说明
`name`	`string`	是	名称；1–255 字符
`table_type`	`string`	是	表类型；取值：`"normal"`, `"block_event"`, `"block_state"`, `"time"`
`chain_id`	`string` / `null`	否	平台链标识，如 eth；区块表必填；默认 `""`
`description`	`string` / `null`	否	用途说明；≤ 255 字符
`space`	`string`	是	Space ID；1–64 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`chain_id`	`string` / `null`	平台链标识，如 eth；非区块表为空字符串或 null
`table_type`	`string`	表类型
`description`	`string` / `null`	用途说明
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

请求示例

curl https://api.chaintable.com/v1/table/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "space": "demo",
  "name": "asset_notes",
  "table_type": "normal",
  "description": "Asset notes"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.asset_notes",
    "space": "demo",
    "name": "asset_notes",
    "chain_id": "",
    "table_type": "normal",
    "description": "Asset notes",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0
  }
}

GET /v1/table/id_types — 列出主键类型

列出主键类型。Method: GET
Path: /v1/table/id_types参数无请求参数。返回字段

字段	类型	说明
`data`	`string[]`	支持的主键类型名称

请求示例

curl https://api.chaintable.com/v1/table/id_types \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID"

返回示例

{
  "code": 0,
  "message": "ok",
  "data": [
    "STRING",
    "ADDRESS",
    "TOKENID",
    "HASH",
    "BLOCKID",
    "CHAINID",
    "TXID"
  ]
}

POST /v1/table/indexes/update — 更新索引

indexes 整体替换，保留需要的已有索引。Method: POST
Path: /v1/table/indexes/update参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`indexes`	`object[]`	是	索引定义

显示 indexes — 每项的字段

字段	类型	必填	说明
`id`	`string` / `null`	否	普通表索引须提供 ID；保留已有索引时沿用原 ID；1–64 字符
`columns`	`string[]`	是	按索引顺序排列的字段名；≥ 1 项
`is_hidden`	`boolean` / `null`	否	只读标记，传入时忽略
`is_system`	`boolean` / `null`	否	只读标记，传入时忽略
`is_primary`	`boolean` / `null`	否	只读标记，传入时忽略

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`chain_id`	`string` / `null`	平台链标识，如 eth；非区块表为空字符串或 null
`table_type`	`string`	表类型
`description`	`string` / `null`	用途说明
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`columns`	`object[]`	已初始化的字段定义；列表接口不返回
`indexes`	`object[]`	已初始化的索引；列表接口不返回
`view`	`object` / `null`	表展示配置
`start_height`	`integer` / `null`	起始区块高度
`deps`	`integer`	读取该表的依赖数量
`last_write_at_ms`	`integer` / `null`	最后写入时间，Unix 毫秒；没有记录时为 null
`first_write_at`	`number` / `null`	首次写入时间，Unix 秒；时间表返回
`inited`	`boolean`	是否已初始化；表详情及结构操作返回
`table_rows`	`integer`	表的记录数
`table_size`	`integer`	表的数据大小，单位为字节
`replica_num`	`integer`	副本数量
`s3_synced_at`	`number` / `null`	数据同步时间，Unix 秒
`subtables`	`object[]`	该表关联的数据表
`parent`	`object`	所属主表的 ID 和类型
`label`	`string`	说明文字或展示分类
`relations`	`object[]`	相关数据表

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 columns — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string`	名称
`type`	`string`	字段逻辑类型，取值见数据类型参考，见数据类型
`is_system`	`boolean`	是否为系统字段或索引

显示 indexes — 每项的字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`columns`	`string[]`	按索引顺序排列的字段名
`is_primary`	`boolean`	是否为主键索引
`is_system`	`boolean`	是否为系统字段或索引
`is_hidden`	`boolean`	是否隐藏索引

显示 view — 每个值的字段

字段	类型	说明
`sort`	`integer`	列的展示顺序，从 0 开始

显示 subtables — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

显示 parent — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`table_type`	`string`	表类型

显示 relations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/table/indexes/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "demo.asset_notes",
  "indexes": [
    {
      "id": "note_index",
      "columns": [
        "note"
      ]
    }
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.asset_notes",
    "space": "demo",
    "name": "asset_notes",
    "chain_id": "",
    "table_type": "normal",
    "description": "Asset notes",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "columns": [
      {
        "id": "id",
        "name": "id",
        "type": "STRING",
        "is_system": true
      },
      {
        "id": "note",
        "name": "note",
        "type": "STRING",
        "is_system": false
      }
    ],
    "indexes": [
      {
        "columns": [
          "id"
        ],
        "is_primary": true,
        "is_system": true
      },
      {
        "id": "note_index",
        "columns": [
          "note"
        ],
        "is_system": false
      }
    ],
    "table_rows": 1,
    "table_size": 64,
    "replica_num": 1,
    "inited": true,
    "subtables": [],
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "view": {
      "id": {
        "sort": 0
      },
      "note": {
        "sort": 1
      }
    },
    "deps": 0,
    "last_write_at_ms": 1788220800000
  }
}

POST /v1/table/init — 初始化表结构

初始化表结构。普通表须包含 id 字段；字段 ID 和名称不能重复。时间表使用固定字段，区块表保留系统字段。Method: POST
Path: /v1/table/init参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`columns`	`object[]`	否	字段定义
`indexes`	`object[]`	否	索引定义
`view`	`object` / `null`	否	表展示配置

显示 columns — 每项的字段

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–64 字符
`name`	`string`	是	名称；1–64 字符
`type`	`string`	是	字段逻辑类型，取值见数据类型参考，见数据类型；≥ 1 字符

显示 indexes — 每项的字段

字段	类型	必填	说明
`id`	`string` / `null`	否	普通表索引须提供 ID；保留已有索引时沿用原 ID；1–64 字符
`columns`	`string[]`	是	按索引顺序排列的字段名；≥ 1 项
`is_hidden`	`boolean` / `null`	否	只读标记，传入时忽略
`is_system`	`boolean` / `null`	否	只读标记，传入时忽略
`is_primary`	`boolean` / `null`	否	只读标记，传入时忽略

显示 view — 每个值的字段

字段	类型	必填	说明
`sort`	`integer`	否	列的展示顺序，从 0 开始

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`chain_id`	`string` / `null`	平台链标识，如 eth；非区块表为空字符串或 null
`table_type`	`string`	表类型
`description`	`string` / `null`	用途说明
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`columns`	`object[]`	已初始化的字段定义；列表接口不返回
`indexes`	`object[]`	已初始化的索引；列表接口不返回
`view`	`object` / `null`	表展示配置
`start_height`	`integer` / `null`	起始区块高度
`deps`	`integer`	读取该表的依赖数量
`last_write_at_ms`	`integer` / `null`	最后写入时间，Unix 毫秒；没有记录时为 null
`first_write_at`	`number` / `null`	首次写入时间，Unix 秒；时间表返回
`inited`	`boolean`	是否已初始化；表详情及结构操作返回
`table_rows`	`integer`	表的记录数
`table_size`	`integer`	表的数据大小，单位为字节
`replica_num`	`integer`	副本数量
`s3_synced_at`	`number` / `null`	数据同步时间，Unix 秒
`subtables`	`object[]`	该表关联的数据表
`parent`	`object`	所属主表的 ID 和类型
`label`	`string`	说明文字或展示分类
`relations`	`object[]`	相关数据表

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 columns — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string`	名称
`type`	`string`	字段逻辑类型，取值见数据类型参考，见数据类型
`is_system`	`boolean`	是否为系统字段或索引

显示 indexes — 每项的字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`columns`	`string[]`	按索引顺序排列的字段名
`is_primary`	`boolean`	是否为主键索引
`is_system`	`boolean`	是否为系统字段或索引
`is_hidden`	`boolean`	是否隐藏索引

显示 view — 每个值的字段

字段	类型	说明
`sort`	`integer`	列的展示顺序，从 0 开始

显示 subtables — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

显示 parent — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`table_type`	`string`	表类型

显示 relations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/table/init \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "demo.asset_notes",
  "columns": [
    {
      "id": "id",
      "name": "id",
      "type": "STRING"
    },
    {
      "id": "note",
      "name": "note",
      "type": "STRING"
    }
  ],
  "indexes": [],
  "view": {
    "id": {
      "sort": 0
    },
    "note": {
      "sort": 1
    }
  }
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.asset_notes",
    "space": "demo",
    "name": "asset_notes",
    "chain_id": "",
    "table_type": "normal",
    "description": "Asset notes",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "columns": [
      {
        "id": "id",
        "name": "id",
        "type": "STRING",
        "is_system": true
      },
      {
        "id": "note",
        "name": "note",
        "type": "STRING",
        "is_system": false
      }
    ],
    "indexes": [
      {
        "columns": [
          "id"
        ],
        "is_primary": true,
        "is_system": true
      }
    ],
    "table_rows": 1,
    "table_size": 64,
    "replica_num": 1,
    "inited": true,
    "subtables": [],
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "view": {
      "id": {
        "sort": 0
      },
      "note": {
        "sort": 1
      }
    },
    "deps": 0,
    "last_write_at_ms": 1788220800000
  }
}

GET /v1/table/instance/list — 列出关联的 Notebook 实例

access 选择读取或写入记录；返回当前调用身份可见的实例。Method: GET
Path: /v1/table/instance/list参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`access`	`string`	是	读取或写入记录；取值：`"read"`, `"write"`
`limit`	`integer`	否	最多返回条数；≥ 1；默认 `100`

返回字段

字段	类型	说明
`instances`	`object[]`	Notebook 执行实例
`count`	`integer`	返回的实例数量

显示 instances — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`last_accessed_at_ms`	`integer` / `null`	最近一次访问时间，Unix 毫秒
`name`	`string` / `null`	名称
`display_status`	`string`	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`, `"starting"`
`launched`	`string`	实例启动方式；取值：`"manual"`, `"schedule"`
`notebook_id`	`string` / `null`	Notebook ID
`schedule_id`	`string` / `null`	调度 ID
`exit_message`	`string` / `null`	退出原因；运行中为 null

请求示例

curl --get https://api.chaintable.com/v1/table/instance/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=demo.asset_notes \
  --data-urlencode access=write \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "instances": [
      {
        "id": "01900000000070008000000000000009",
        "last_accessed_at_ms": 1788220800000,
        "name": "print_message",
        "display_status": "running",
        "launched": "manual",
        "notebook_id": "01900000000070008000000000000002",
        "schedule_id": null,
        "exit_message": null
      }
    ],
    "count": 1
  }
}

GET /v1/table/list — 列出数据表

列出数据表。Method: GET
Path: /v1/table/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 100；默认 `10`
`order_by`	`string`	否	排序字段；取值：`"id"`, `"name"`, `"created_at"`, `"updated_at"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`
`space`	`string` / `null`	否	按 Space 筛选；省略时列出可见 Space 内的资源；1–64 字符
`name`	`string` / `null`	否	名称，按子串筛选
`with_activity`	`boolean`	否	附带使用和写入信息；默认 `false`

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`chain_id`	`string` / `null`	平台链标识，如 eth；非区块表为空字符串或 null
`table_type`	`string`	表类型
`description`	`string` / `null`	用途说明
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`deps`	`integer`	读取该表的依赖数量
`last_write_at_ms`	`integer` / `null`	最后写入时间，Unix 毫秒；没有记录时为 null

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl --get https://api.chaintable.com/v1/table/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode space=demo \
  --data-urlencode limit=10 \
  --data-urlencode with_activity=true

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "demo.asset_notes",
        "space": "demo",
        "name": "asset_notes",
        "chain_id": "",
        "table_type": "normal",
        "description": "Asset notes",
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "space_entity": {
          "id": "demo",
          "description": "Example resources",
          "account_id": "0190000000007000800000000000000b",
          "status": "active",
          "visibility": "public",
          "dep_count": 0,
          "content_count": 6,
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "account": {
            "id": "0190000000007000800000000000000b",
            "type": "org",
            "slug": "example-team",
            "display_name": "Example team",
            "avatar_url": null,
            "avatar_thumbnail_url": null
          }
        },
        "deps": 0,
        "last_write_at_ms": 1788220800000
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

POST /v1/table/row/create — 写入一行

向已初始化的普通表写入一行；主键已存在时更新该行。data 中须包含主键 id，字段值应符合表结构。Method: POST
Path: /v1/table/row/create参数

字段	类型	必填	说明
`table_id`	`string`	是	完整表 ID；1–255 字符
`data`	`object`	是	行字段和值

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/table/row/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "table_id": "demo.asset_notes",
  "data": {
    "id": "usdc",
    "note": "Stablecoin"
  }
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/table/row/delete — 删除一行

仅支持普通表。id 是要删除的行主键。Method: POST
Path: /v1/table/row/delete参数

字段	类型	必填	说明
`table_id`	`string`	是	完整表 ID；1–255 字符
`id`	`string`	是	行主键；≥ 1 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/table/row/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "table_id": "demo.asset_notes",
  "id": "usdc"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/table/row/get — 按主键批量读取行

pks 为主键字符串数组，最多 10,000 项。Method: POST
Path: /v1/table/row/get参数

字段	类型	必填	说明
`table_id`	`string`	是	完整表 ID；1–255 字符
`pks`	`string[]`	是	主键值列表；≤ 10000 项

返回字段

字段	类型	说明
`columns`	`object[]`	结果列定义
`rows`	`object[]`	结果行，每行以字段名为键
`total_count`	`integer` / `null`	row/get 返回匹配条数；row/list 和 row/query 通常为 null
`start`	`integer`	row/list 返回的分页起始位置
`limit`	`integer`	row/list 返回的分页大小
`truncated`	`boolean`	row/query 的结果是否截断
`rows_count`	`integer`	row/query 返回的记录数

显示 columns — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	类型

请求示例

curl https://api.chaintable.com/v1/table/row/get \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "table_id": "demo.asset_notes",
  "pks": [
    "usdc"
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "columns": [
      {
        "id": "id",
        "name": "id",
        "type": "STRING"
      },
      {
        "id": "note",
        "name": "note",
        "type": "STRING"
      }
    ],
    "rows": [
      {
        "id": "usdc",
        "note": "Stablecoin"
      }
    ],
    "total_count": 1
  }
}

GET /v1/table/row/list — 分页读取行

分页读取记录。filter 为 JSON 编码的条件数组，每项包含 field（字段名）、op（eq、neq、gt、lt、gte、lte）和 value（字符串、数字、布尔值或 null）。条件以 AND 组合，null 仅支持 eq 和 neq。Method: GET
Path: /v1/table/row/list参数

字段	类型	必填	说明
`table_id`	`string`	是	完整表 ID；1–255 字符
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；≤ 9223372036854775807；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 10000；默认 `1000`
`filter`	`string` / `null`	否	筛选条件的 JSON 字符串
`order_by`	`string` / `null`	否	排序字段
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`

返回字段

字段	类型	说明
`columns`	`object[]`	结果列定义
`rows`	`object[]`	结果行，每行以字段名为键
`total_count`	`integer` / `null`	row/get 返回匹配条数；row/list 和 row/query 通常为 null
`start`	`integer`	row/list 返回的分页起始位置
`limit`	`integer`	row/list 返回的分页大小
`truncated`	`boolean`	row/query 的结果是否截断
`rows_count`	`integer`	row/query 返回的记录数

显示 columns — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	类型

请求示例

curl --get https://api.chaintable.com/v1/table/row/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode table_id=demo.asset_notes \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "columns": [
      {
        "id": "id",
        "name": "id",
        "type": "STRING"
      },
      {
        "id": "note",
        "name": "note",
        "type": "STRING"
      }
    ],
    "rows": [
      {
        "id": "usdc",
        "note": "Stablecoin"
      }
    ],
    "total_count": null,
    "start": 0,
    "limit": 10
  }
}

POST /v1/table/row/query — 执行单表查询

执行当前表的单条 SELECT * 查询，支持 WHERE、ORDER BY 和 LIMIT。最多返回 10,000 行；聚合和多表查询使用 Query 接口。Method: POST
Path: /v1/table/row/query参数

字段	类型	必填	说明
`table_id`	`string`	是	完整表 ID；1–255 字符
`sql`	`string`	是	单表 SQL 查询；≥ 1 字符

返回字段

字段	类型	说明
`columns`	`object[]`	结果列定义
`rows`	`object[]`	结果行，每行以字段名为键
`total_count`	`integer` / `null`	row/get 返回匹配条数；row/list 和 row/query 通常为 null
`start`	`integer`	row/list 返回的分页起始位置
`limit`	`integer`	row/list 返回的分页大小
`truncated`	`boolean`	row/query 的结果是否截断
`rows_count`	`integer`	row/query 返回的记录数

显示 columns — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	类型

请求示例

curl https://api.chaintable.com/v1/table/row/query \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "table_id": "demo.asset_notes",
  "sql": "SELECT * FROM demo.asset_notes LIMIT 10"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "columns": [
      {
        "name": "id",
        "type": "STRING"
      },
      {
        "name": "note",
        "type": "STRING"
      }
    ],
    "rows": [
      {
        "id": "usdc",
        "note": "Stablecoin"
      }
    ],
    "total_count": null,
    "rows_count": 1,
    "truncated": false
  }
}

POST /v1/table/row/update — 更新一行

仅支持普通表；data.id 若存在，必须与顶层 id 一致。Method: POST
Path: /v1/table/row/update参数

字段	类型	必填	说明
`table_id`	`string`	是	完整表 ID；1–255 字符
`id`	`string`	是	行主键；≥ 1 字符
`data`	`object`	是	行字段和值

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/table/row/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "table_id": "demo.asset_notes",
  "id": "usdc",
  "data": {
    "note": "USD Coin"
  }
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

GET /v1/table/start_height/editable — 检查起始高度是否可修改

检查起始高度是否可修改。Method: GET
Path: /v1/table/start_height/editable参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符

返回字段

字段	类型	说明
`editable`	`boolean`	起始高度是否可修改
`reason`	`string` / `null`	原因；没有原因时为 null

请求示例

curl --get https://api.chaintable.com/v1/table/start_height/editable \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=demo.pool_reserves.eth

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "editable": true,
    "reason": null
  }
}

POST /v1/table/start_height/update — 设置起始高度

仅支持已初始化、尚无处理进度的区块表，且不能超过链的当前高度。可先调用 /v1/table/start_height/editable 检查。Method: POST
Path: /v1/table/start_height/update参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`start_height`	`integer`	是	起始区块高度；≥ 0；≤ 9223372036854775807

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`chain_id`	`string` / `null`	平台链标识，如 eth；非区块表为空字符串或 null
`table_type`	`string`	表类型
`description`	`string` / `null`	用途说明
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`columns`	`object[]`	已初始化的字段定义；列表接口不返回
`indexes`	`object[]`	已初始化的索引；列表接口不返回
`view`	`object` / `null`	表展示配置
`start_height`	`integer` / `null`	起始区块高度
`deps`	`integer`	读取该表的依赖数量
`last_write_at_ms`	`integer` / `null`	最后写入时间，Unix 毫秒；没有记录时为 null
`first_write_at`	`number` / `null`	首次写入时间，Unix 秒；时间表返回
`inited`	`boolean`	是否已初始化；表详情及结构操作返回
`table_rows`	`integer`	表的记录数
`table_size`	`integer`	表的数据大小，单位为字节
`replica_num`	`integer`	副本数量
`s3_synced_at`	`number` / `null`	数据同步时间，Unix 秒
`subtables`	`object[]`	该表关联的数据表
`parent`	`object`	所属主表的 ID 和类型
`label`	`string`	说明文字或展示分类
`relations`	`object[]`	相关数据表

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 columns — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string`	名称
`type`	`string`	字段逻辑类型，取值见数据类型参考，见数据类型
`is_system`	`boolean`	是否为系统字段或索引

显示 indexes — 每项的字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`columns`	`string[]`	按索引顺序排列的字段名
`is_primary`	`boolean`	是否为主键索引
`is_system`	`boolean`	是否为系统字段或索引
`is_hidden`	`boolean`	是否隐藏索引

显示 view — 每个值的字段

字段	类型	说明
`sort`	`integer`	列的展示顺序，从 0 开始

显示 subtables — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

显示 parent — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`table_type`	`string`	表类型

显示 relations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/table/start_height/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "demo.pool_reserves.eth",
  "start_height": 21000000
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.pool_reserves.eth",
    "space": "demo",
    "name": "pool_reserves.eth",
    "chain_id": "eth",
    "table_type": "block_state",
    "description": "Asset notes",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "columns": [
      {
        "id": "id",
        "name": "id",
        "type": "HASH",
        "is_system": true
      },
      {
        "id": "block_height",
        "name": "block_height",
        "type": "BLOCKHEIGHT",
        "is_system": true
      },
      {
        "id": "block_id",
        "name": "block_id",
        "type": "HASH",
        "is_system": true
      },
      {
        "id": "block_timestamp",
        "name": "block_timestamp",
        "type": "TIMESTAMP",
        "is_system": true
      }
    ],
    "indexes": [
      {
        "columns": [
          "id"
        ],
        "is_primary": true,
        "is_system": true
      }
    ],
    "table_rows": 0,
    "table_size": 0,
    "replica_num": 1,
    "inited": true,
    "subtables": [],
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "view": {},
    "start_height": 21000000
  }
}

GET /v1/table/stats/block — 读取区块写入统计

recent 为最近区块数；返回的延迟值以毫秒计。Method: GET
Path: /v1/table/stats/block参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`recent`	`integer`	否	最近区块数；≥ 1；≤ 60；默认 `30`

返回字段

字段	类型	说明
`start_height`	`integer`	起始区块高度
`consensus_height`	`integer` / `null`	表的共识高度；不可用时为 null
`chain_height`	`integer` / `null`	链的当前高度；不可用时为 null
`completeness`	`object[]`	已完成处理的区块高度区间
`blocks`	`object[]`	逐区块写入统计
`completeness_count`	`integer`	已处理区间的总数；区间过多时 completeness 可能为空

显示 completeness — 每项的字段

字段	类型	说明
`start`	`integer`	已处理区间的起始高度
`end`	`integer`	区间结束高度

显示 blocks — 每项的字段

字段	类型	说明
`block_height`	`integer`	区块高度
`rows`	`integer`	该区块写入的记录数
`lag_ms`	`integer` / `null`	处理延迟，毫秒；不可用时为 null
`processed`	`boolean`	区块是否已处理

请求示例

curl --get https://api.chaintable.com/v1/table/stats/block \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=demo.pool_reserves.eth \
  --data-urlencode recent=2

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "start_height": 21000000,
    "consensus_height": 21000001,
    "chain_height": 21000001,
    "completeness": [
      {
        "start": 21000000,
        "end": 21000001
      }
    ],
    "completeness_count": 1,
    "blocks": [
      {
        "block_height": 21000000,
        "rows": 1,
        "lag_ms": 50,
        "processed": true
      },
      {
        "block_height": 21000001,
        "rows": 0,
        "lag_ms": 45,
        "processed": true
      }
    ]
  }
}

GET /v1/table/stats/daily — 读取每日写入统计

使用 year，或成对提供 from、to（YYYY-MM-DD）。Method: GET
Path: /v1/table/stats/daily参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`year`	`integer` / `null`	否	统计年份；≥ 1；≤ 9999
`from`	`string` / `null`	否	开始日期；`date`
`to`	`string` / `null`	否	结束日期；`date`

返回字段

字段	类型	说明
`buckets`	`object[]`	按时间分组的写入统计

显示 buckets — 每项的字段

字段	类型	说明
`time_at`	`string` / `number`	每日统计为日期，每分钟统计为 Unix 秒
`rows`	`integer`	该时间段内的记录数

请求示例

curl --get https://api.chaintable.com/v1/table/stats/daily \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=demo.price_samples \
  --data-urlencode from=2026-09-01 \
  --data-urlencode to=2026-09-01

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "buckets": [
      {
        "time_at": "2026-09-01",
        "rows": 1
      }
    ]
  }
}

GET /v1/table/stats/minute — 读取每分钟写入统计

读取每分钟写入统计。Method: GET
Path: /v1/table/stats/minute参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`minutes`	`integer`	否	最近分钟数；≥ 1；≤ 60；默认 `30`

返回字段

字段	类型	说明
`buckets`	`object[]`	按时间分组的写入统计

显示 buckets — 每项的字段

字段	类型	说明
`time_at`	`string` / `number`	每日统计为日期，每分钟统计为 Unix 秒
`rows`	`integer`	该时间段内的记录数

请求示例

curl --get https://api.chaintable.com/v1/table/stats/minute \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=demo.price_samples \
  --data-urlencode minutes=1

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "buckets": [
      {
        "time_at": 1788220800.0,
        "rows": 1
      }
    ]
  }
}

GET /v1/table/templates — 读取建表模板

读取建表模板。Method: GET
Path: /v1/table/templates参数

字段	类型	必填	说明
`table_type`	`string`	否	表类型；取值：`"normal"`, `"block_event"`, `"block_state"`, `"time"`；默认 `"normal"`

返回字段

字段	类型	说明
`columns`	`object[]`	字段定义
`indexes`	`object[]`	索引定义

显示 columns — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string`	名称
`type`	`string`	字段逻辑类型，取值见数据类型参考，见数据类型
`is_system`	`boolean`	是否为系统字段或索引

显示 indexes — 每项的字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`columns`	`string[]`	按索引顺序排列的字段名
`is_primary`	`boolean`	是否为主键索引
`is_system`	`boolean`	是否为系统字段或索引
`is_hidden`	`boolean`	是否隐藏索引

请求示例

curl --get https://api.chaintable.com/v1/table/templates \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode table_type=normal

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "columns": [
      {
        "name": "id",
        "type": "STRING"
      }
    ],
    "indexes": []
  }
}

POST /v1/table/view/update — 更新表展示配置

更新表展示配置。Method: POST
Path: /v1/table/view/update参数

字段	类型	必填	说明
`id`	`string`	是	完整表 ID，如 demo.asset_notes；1–255 字符
`view`	`object` / `null`	是	表展示配置

显示 view — 每个值的字段

字段	类型	必填	说明
`sort`	`integer`	否	列的展示顺序，从 0 开始

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`chain_id`	`string` / `null`	平台链标识，如 eth；非区块表为空字符串或 null
`table_type`	`string`	表类型
`description`	`string` / `null`	用途说明
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`columns`	`object[]`	已初始化的字段定义；列表接口不返回
`indexes`	`object[]`	已初始化的索引；列表接口不返回
`view`	`object` / `null`	表展示配置
`start_height`	`integer` / `null`	起始区块高度
`deps`	`integer`	读取该表的依赖数量
`last_write_at_ms`	`integer` / `null`	最后写入时间，Unix 毫秒；没有记录时为 null
`first_write_at`	`number` / `null`	首次写入时间，Unix 秒；时间表返回
`inited`	`boolean`	是否已初始化；表详情及结构操作返回
`table_rows`	`integer`	表的记录数
`table_size`	`integer`	表的数据大小，单位为字节
`replica_num`	`integer`	副本数量
`s3_synced_at`	`number` / `null`	数据同步时间，Unix 秒
`subtables`	`object[]`	该表关联的数据表
`parent`	`object`	所属主表的 ID 和类型
`label`	`string`	说明文字或展示分类
`relations`	`object[]`	相关数据表

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 columns — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string`	名称
`type`	`string`	字段逻辑类型，取值见数据类型参考，见数据类型
`is_system`	`boolean`	是否为系统字段或索引

显示 indexes — 每项的字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`columns`	`string[]`	按索引顺序排列的字段名
`is_primary`	`boolean`	是否为主键索引
`is_system`	`boolean`	是否为系统字段或索引
`is_hidden`	`boolean`	是否隐藏索引

显示 view — 每个值的字段

字段	类型	说明
`sort`	`integer`	列的展示顺序，从 0 开始

显示 subtables — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

显示 parent — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`table_type`	`string`	表类型

显示 relations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`label`	`string`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/table/view/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "demo.asset_notes",
  "view": {
    "id": {
      "sort": 0
    },
    "note": {
      "sort": 1
    }
  }
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.asset_notes",
    "space": "demo",
    "name": "asset_notes",
    "chain_id": "",
    "table_type": "normal",
    "description": "Asset notes",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "columns": [
      {
        "id": "id",
        "name": "id",
        "type": "STRING",
        "is_system": true
      },
      {
        "id": "note",
        "name": "note",
        "type": "STRING",
        "is_system": false
      }
    ],
    "indexes": [
      {
        "columns": [
          "id"
        ],
        "is_primary": true,
        "is_system": true
      }
    ],
    "table_rows": 1,
    "table_size": 64,
    "replica_num": 1,
    "inited": true,
    "subtables": [],
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "view": {
      "id": {
        "sort": 0
      },
      "note": {
        "sort": 1
      }
    },
    "deps": 0,
    "last_write_at_ms": 1788220800000
  }
}

function

GET /v1/function — 读取 Function

读取 Function。Method: GET
Path: /v1/function参数

字段	类型	必填	说明
`id`	`string`	是	完整 Function ID，如 demo.usdc_amount；1–255 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	执行代码；Query 使用 SQL
`parameters`	`object[]`	参数定义
`return_type`	`string` / `null`	返回值类型
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl --get https://api.chaintable.com/v1/function \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=demo.usdc_amount

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.usdc_amount",
    "space": "demo",
    "name": "usdc_amount",
    "language": "python",
    "code": "def usdc_amount(raw_amount):\n    return raw_amount / 10**6",
    "parameters": [
      {
        "name": "raw_amount",
        "type": "INT",
        "options": null,
        "default": null,
        "id": "01900000000070008000000000000014",
        "order": 0
      }
    ],
    "return_type": "FLOAT",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    }
  }
}

POST /v1/function/create — 创建 Function

创建 Function。Method: POST
Path: /v1/function/create参数

字段	类型	必填	说明
`name`	`string`	是	名称；1–255 字符
`language`	`string`	是	代码语言；取值：`"python"`, `"go"`, `"javascript"`, `"sql"`
`code`	`string`	否	执行代码；Query 使用 SQL；默认 `""`
`parameters`	`object[]`	否	参数定义；更新时整体替换
`return_type`	`string`	否	返回值类型；默认 `""`
`space`	`string`	是	Space ID；1–64 字符

显示 parameters — 每项的字段

字段	类型	必填	说明
`name`	`string` / `null`	是	形参名称
`type`	`string`	是	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	否	参数的可选值列表
`default`	`object` / `null`	否	默认参数值
`id`	`JSON` / `null`	否	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	否	参数顺序；Function 中须全部省略或从 0 连续编号；≥ 0

显示 default — 子字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	执行代码；Query 使用 SQL
`parameters`	`object[]`	参数定义
`return_type`	`string` / `null`	返回值类型
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/function/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "space": "demo",
  "name": "usdc_amount",
  "language": "python",
  "code": "def usdc_amount(raw_amount):\n    return raw_amount / 10**6",
  "parameters": [
    {
      "name": "raw_amount",
      "type": "INT"
    }
  ],
  "return_type": "FLOAT"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.usdc_amount",
    "space": "demo",
    "name": "usdc_amount",
    "language": "python",
    "code": "def usdc_amount(raw_amount):\n    return raw_amount / 10**6",
    "parameters": [
      {
        "name": "raw_amount",
        "type": "INT",
        "options": null,
        "default": null,
        "id": "01900000000070008000000000000014",
        "order": 0
      }
    ],
    "return_type": "FLOAT",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    }
  }
}

POST /v1/function/delete — 删除 Function

删除 Function。Method: POST
Path: /v1/function/delete参数

字段	类型	必填	说明
`id`	`string`	是	完整 Function ID，如 demo.usdc_amount；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/function/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "demo.usdc_amount"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/function/invoke — 调用已保存的 Function

执行已保存的 Function。arguments 按位置传值，无参数时传 []。Method: POST
Path: /v1/function/invoke参数

字段	类型	必填	说明
`id`	`string`	是	完整 Function ID，如 demo.usdc_amount；1–255 字符
`arguments`	`JSON[]`	是	位置参数值数组；无参数时传 []

返回字段

字段	类型	说明
`data`	`JSON`	函数返回的 JSON 值，由 Function 的返回类型和实现决定

请求示例

curl https://api.chaintable.com/v1/function/invoke \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "demo.usdc_amount",
  "arguments": [
    1500000
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": 1.5
}

GET /v1/function/list — 列出 Function

列出 Function。Method: GET
Path: /v1/function/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 10000；默认 `20`
`order_by`	`string`	否	排序字段；取值：`"id"`, `"name"`, `"created_at"`, `"updated_at"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`
`space`	`string` / `null`	否	按 Space 筛选；省略时列出可见 Space 内的资源；1–64 字符
`name`	`string` / `null`	否	名称，按子串筛选
`keyword`	`string` / `null`	否	搜索关键词
`match_type`	`string`	否	搜索范围；取值：`"name"`, `"code"`；默认 `"name"`

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	执行代码；Query 使用 SQL
`parameters`	`object[]`	参数定义
`return_type`	`string` / `null`	返回值类型
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`matched_lines`	`object[]`	按代码关键词搜索时返回，最多 10 行
`matched_line_count`	`integer`	按代码关键词搜索时返回的完整命中行数

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 matched_lines — 每项的字段

字段	类型	说明
`line`	`integer`	代码行号，从 1 开始
`text`	`string`	匹配的代码行内容

请求示例

curl --get https://api.chaintable.com/v1/function/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode space=demo \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "demo.usdc_amount",
        "space": "demo",
        "name": "usdc_amount",
        "language": "python",
        "code": "def usdc_amount(raw_amount):\n    return raw_amount / 10**6",
        "parameters": [
          {
            "name": "raw_amount",
            "type": "INT",
            "options": null,
            "default": null,
            "id": "01900000000070008000000000000014",
            "order": 0
          }
        ],
        "return_type": "FLOAT",
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "space_entity": {
          "id": "demo",
          "description": "Example resources",
          "account_id": "0190000000007000800000000000000b",
          "status": "active",
          "visibility": "public",
          "dep_count": 0,
          "content_count": 6,
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "account": {
            "id": "0190000000007000800000000000000b",
            "type": "org",
            "slug": "example-team",
            "display_name": "Example team",
            "avatar_url": null,
            "avatar_thumbnail_url": null
          }
        }
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

POST /v1/function/run — 运行调试代码

执行传入代码并返回调试记录。status 表示执行状态，output 包含调试输出和错误信息。Method: POST
Path: /v1/function/run参数

字段	类型	必填	说明
`language`	`string`	是	代码语言；取值：`"python"`, `"go"`, `"javascript"`, `"sql"`
`code`	`string`	是	执行代码；Query 使用 SQL；≥ 1 字符
`func_name`	`string`	否	函数入口名称；默认 `""`
`parameters`	`object[]`	否	参数定义；更新时整体替换
`arguments`	`object[]`	否	本次执行的参数值

显示 parameters — 每项的字段

字段	类型	必填	说明
`name`	`string` / `null`	是	形参名称
`type`	`string`	是	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	否	参数的可选值列表
`default`	`object` / `null`	否	默认参数值
`id`	`JSON` / `null`	否	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	否	参数顺序；Function 中须全部省略或从 0 连续编号；≥ 0

显示 default — 子字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值

显示 arguments — 每项的字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值
`name`	`string` / `null`	否	匹配的形参名称
`order`	`integer` / `null`	否	须全部省略或从 0 连续编号；按此顺序匹配参数；≥ 0

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`language`	`string`	代码语言
`code`	`string`	执行代码；Query 使用 SQL
`parameters`	`object[]`	参数定义
`args`	`JSON[]`	按位置排列的实际参数值
`status`	`string`	执行结果状态；取值：`"succeeded"`, `"failed"`, `"timeout"`
`output`	`object`	调试输出及错误信息
`return_value`	`JSON`	函数返回的 JSON 值；失败时为 null
`creator_id`	`string`	创建者的用户 ID
`created_at`	`number`	创建时间，Unix 秒
`started_at`	`number`	开始时间，Unix 秒；尚未开始时为 null
`finished_at`	`number`	完成时间，Unix 秒；未结束时为 null
`arguments`	`object[]`	本次执行的参数值

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 output — 子字段

字段	类型	说明
`text`	`string`	捕获的标准输出和标准错误文本
`truncated`	`boolean`	捕获的输出是否被截断
`original_size_bytes`	`integer`	截断前的输出大小，字节
`failure`	`object` / `null`	失败详情；成功时为 null
`error_stack`	`string`	错误堆栈文本
`local_vars_json`	`string`	失败位置的局部变量，JSON 编码的字符串
`execution_duration_ms`	`integer`	执行耗时，毫秒
`queue_wait_ms`	`integer`	排队时间，毫秒
`call_id`	`string` / `null`	上游调用 ID

显示 failure — 子字段

字段	类型	说明
`code`	`string`	上游失败类型标识
`message`	`string`	说明或错误消息
`retryable`	`boolean`	上游是否将失败标记为可重试

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

请求示例

curl https://api.chaintable.com/v1/function/run \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "language": "python",
  "code": "def usdc_amount(raw_amount):\n    return raw_amount / 10**6",
  "func_name": "usdc_amount",
  "parameters": [
    {
      "name": "raw_amount",
      "type": "INT"
    }
  ],
  "arguments": [
    {
      "name": "raw_amount",
      "value": 1500000
    }
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000017",
    "language": "python",
    "code": "def usdc_amount(raw_amount):\n    return raw_amount / 10**6",
    "parameters": [
      {
        "name": "raw_amount",
        "type": "INT",
        "options": null,
        "default": null,
        "id": "01900000000070008000000000000014",
        "order": 0
      }
    ],
    "args": [
      1500000
    ],
    "arguments": [
      {
        "name": "raw_amount",
        "value": 1500000,
        "order": null
      }
    ],
    "status": "succeeded",
    "output": {
      "text": "",
      "truncated": false,
      "original_size_bytes": 0,
      "failure": null,
      "error_stack": "",
      "local_vars_json": "",
      "execution_duration_ms": 2,
      "queue_wait_ms": 0,
      "call_id": "01900000000070008000000000000018"
    },
    "return_value": 1.5,
    "creator_id": "0190000000007000800000000000000c",
    "created_at": 1788220800.0,
    "started_at": 1788220800.0,
    "finished_at": 1788220800.002
  }
}

GET /v1/function/testcase — 读取测试用例

读取测试用例。Method: GET
Path: /v1/function/testcase参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`function_id`	`string` / `null`	完整 Function ID
`arguments`	`JSON[]`	用于测试的位置参数值数组
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

请求示例

curl --get https://api.chaintable.com/v1/function/testcase \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000008

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000008",
    "function_id": "demo.usdc_amount",
    "arguments": [
      1500000
    ],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0
  }
}

POST /v1/function/testcase/create — 创建测试用例

arguments 为 JSON 值数组；同一 Function 下重复参数会返回 409。Method: POST
Path: /v1/function/testcase/create参数

字段	类型	必填	说明
`function_id`	`string`	是	完整 Function ID；1–255 字符
`arguments`	`JSON[]`	否	用于测试的位置参数值数组

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`function_id`	`string` / `null`	完整 Function ID
`arguments`	`JSON[]`	用于测试的位置参数值数组
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

请求示例

curl https://api.chaintable.com/v1/function/testcase/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "function_id": "demo.usdc_amount",
  "arguments": [
    1500000
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000008",
    "function_id": "demo.usdc_amount",
    "arguments": [
      1500000
    ],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0
  }
}

POST /v1/function/testcase/delete — 删除测试用例

删除测试用例。Method: POST
Path: /v1/function/testcase/delete参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/function/testcase/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000008"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

GET /v1/function/testcase/list — 列出测试用例

列出测试用例。Method: GET
Path: /v1/function/testcase/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 100；默认 `20`
`function_id`	`string`	是	完整 Function ID；1–255 字符
`order_by`	`string`	否	排序字段；取值：`"id"`, `"created_at"`, `"updated_at"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`function_id`	`string` / `null`	完整 Function ID
`arguments`	`JSON[]`	本次执行的参数值
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

请求示例

curl --get https://api.chaintable.com/v1/function/testcase/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode function_id=demo.usdc_amount \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "01900000000070008000000000000008",
        "function_id": "demo.usdc_amount",
        "arguments": [
          1500000
        ],
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

POST /v1/function/testcase/update — 更新测试用例

整体替换 arguments，不能改变所属 Function。Method: POST
Path: /v1/function/testcase/update参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`arguments`	`JSON[]`	否	用于测试的位置参数值数组

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`function_id`	`string` / `null`	完整 Function ID
`arguments`	`JSON[]`	用于测试的位置参数值数组
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

请求示例

curl https://api.chaintable.com/v1/function/testcase/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000008",
  "arguments": [
    2000000
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000008",
    "function_id": "demo.usdc_amount",
    "arguments": [
      2000000
    ],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0
  }
}

POST /v1/function/update — 更新 Function

更新 Function 定义，未提交的字段保持不变。修改名称不会改变 Function ID；参数定义整体替换。Method: POST
Path: /v1/function/update参数

字段	类型	必填	说明
`id`	`string`	是	完整 Function ID，如 demo.usdc_amount；1–255 字符
`name`	`string`	否	名称；1–255 字符
`language`	`string`	否	代码语言；取值：`"python"`, `"go"`, `"javascript"`, `"sql"`
`code`	`string`	否	执行代码；Query 使用 SQL
`parameters`	`object[]`	否	参数定义；更新时整体替换
`return_type`	`string`	否	返回值类型

显示 parameters — 每项的字段

字段	类型	必填	说明
`name`	`string` / `null`	是	形参名称
`type`	`string`	是	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	否	参数的可选值列表
`default`	`object` / `null`	否	默认参数值
`id`	`JSON` / `null`	否	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	否	参数顺序；Function 中须全部省略或从 0 连续编号；≥ 0

显示 default — 子字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	执行代码；Query 使用 SQL
`parameters`	`object[]`	参数定义
`return_type`	`string` / `null`	返回值类型
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/function/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "demo.usdc_amount",
  "code": "def usdc_amount(raw_amount):\n    return raw_amount / 10**6"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "demo.usdc_amount",
    "space": "demo",
    "name": "usdc_amount",
    "language": "python",
    "code": "def usdc_amount(raw_amount):\n    return raw_amount / 10**6",
    "parameters": [
      {
        "name": "raw_amount",
        "type": "INT",
        "options": null,
        "default": null,
        "id": "01900000000070008000000000000014",
        "order": 0
      }
    ],
    "return_type": "FLOAT",
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    }
  }
}

notebook

GET /v1/notebook — 读取 Notebook

读取 Notebook。Method: GET
Path: /v1/notebook参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	Notebook 代码；列表不返回
`parameters`	`object[]`	参数定义
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	对象的唯一 ID
`order`	`integer` / `null`	参数顺序，不要求连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl --get https://api.chaintable.com/v1/notebook \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000002

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000002",
    "space": "demo",
    "name": "print_message",
    "language": "python",
    "code": "print(\"Hello, Chaintable\")",
    "parameters": [],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    }
  }
}

POST /v1/notebook/create — 创建 Notebook

创建 Notebook。名称须以小写字母开头，仅使用小写字母、数字和下划线，可用点分隔合法片段。Method: POST
Path: /v1/notebook/create参数

字段	类型	必填	说明
`space`	`string`	是	Space ID；1–64 字符
`name`	`string`	是	名称；1–255 字符
`language`	`string`	否	代码语言；取值：`"python"`；默认 `"python"`
`code`	`string` / `null`	否	执行代码；Query 使用 SQL；默认 `""`
`parameters`	`object[]` / `null`	否	参数定义；更新时整体替换

显示 parameters — 每项的字段

字段	类型	必填	说明
`name`	`string` / `null`	是	名称
`type`	`string`	是	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	否	参数可选值列表
`default`	`object` / `null`	否	默认参数值
`id`	`JSON` / `null`	否	对象的唯一 ID
`order`	`integer` / `null`	否	参数顺序，不要求连续编号；≥ 0

显示 default — 子字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	Notebook 代码；列表不返回
`parameters`	`object[]`	参数定义
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	对象的唯一 ID
`order`	`integer` / `null`	参数顺序，不要求连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/notebook/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "space": "demo",
  "name": "print_message",
  "language": "python",
  "code": "print(\"Hello, Chaintable\")",
  "parameters": []
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000002",
    "space": "demo",
    "name": "print_message",
    "language": "python",
    "code": "print(\"Hello, Chaintable\")",
    "parameters": [],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    }
  }
}

POST /v1/notebook/delete — 删除 Notebook

删除 Notebook。Method: POST
Path: /v1/notebook/delete参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/notebook/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000002"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

GET /v1/notebook/instance — 读取执行实例

读取执行实例。Method: GET
Path: /v1/notebook/instance参数

字段	类型	必填	说明
`id`	`string`	是	Notebook 执行实例 ID；1–255 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`notebook_id`	`string` / `null`	Notebook ID
`name`	`string` / `null`	名称
`code`	`string` / `null`	本次执行的代码；实例列表不返回
`parameters`	`object[]`	参数定义
`arguments`	`object[]`	本次执行的参数值
`max_memory`	`integer` / `null`	内存配额，单位为字节
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_network_rx`	`integer` / `null`	记录的网络接收额度配置
`max_network_tx`	`integer` / `null`	记录的网络发送额度配置
`account_id`	`string` / `null`	账户 ID
`user_id`	`string` / `null`	启动执行的用户 ID
`schedule_id`	`string` / `null`	调度 ID
`background`	`boolean` / `null`	是否后台执行
`debug`	`boolean` / `null`	是否使用调试模式
`deadline`	`number` / `null`	前台实例到期时间，Unix 秒；后台为 null
`status`	`string`	状态；取值：`"running"`, `"ended"`
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`oom_killed`	`boolean` / `null`	是否因内存不足被终止
`exited_at`	`number` / `null`	退出时间，Unix 秒；运行中为 null
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`display_status`	`string`	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`, `"starting"`
`launched`	`string`	实例启动方式；取值：`"manual"`, `"schedule"`
`exit_message`	`string` / `null`	退出原因；运行中为 null
`account`	`object` / `null`	账户信息
`user`	`object` / `null`	启动者信息；不存在时为 null
`notebook`	`object` / `null`	关联 Notebook 的摘要；不存在时为 null
`schedule`	`object` / `null`	关联调度；没有调度时为 null

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	对象的唯一 ID
`order`	`integer` / `null`	参数顺序，不要求连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 user — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 notebook — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string` / `null`	名称
`space`	`string`	Space ID

显示 schedule — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`deleted_at`	`number` / `null`	删除时间，Unix 秒；未删除时为 null

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

请求示例

curl --get https://api.chaintable.com/v1/notebook/instance \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000009

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000009",
    "notebook_id": "01900000000070008000000000000002",
    "name": "print_message",
    "code": "print(\"Hello, Chaintable\")",
    "parameters": [],
    "arguments": [],
    "max_cpu": 100,
    "max_memory": 4294967296,
    "max_network_rx": null,
    "max_network_tx": null,
    "account_id": "0190000000007000800000000000000b",
    "user_id": "0190000000007000800000000000000c",
    "schedule_id": null,
    "background": false,
    "debug": false,
    "deadline": 1788220950.0,
    "status": "running",
    "exit_code": null,
    "oom_killed": null,
    "exited_at": null,
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "display_status": "running",
    "launched": "manual",
    "exit_message": null,
    "account": {
      "id": "0190000000007000800000000000000b",
      "type": "org",
      "slug": "example-team",
      "display_name": "Example team",
      "avatar_url": null,
      "avatar_thumbnail_url": null
    },
    "user": {
      "id": "0190000000007000800000000000000c",
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": null
    },
    "notebook": {
      "id": "01900000000070008000000000000002",
      "name": "print_message",
      "space": "demo"
    },
    "schedule": null
  }
}

POST /v1/notebook/instance/cancel — 停止执行实例

停止执行实例。Method: POST
Path: /v1/notebook/instance/cancel参数

字段	类型	必填	说明
`id`	`string`	是	Notebook 执行实例 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/notebook/instance/cancel \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000009"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/notebook/instance/keepalive — 延长前台执行时间

将前台执行的有效期延长到当前时间后 150 秒；后台或已结束实例不受影响。Method: POST
Path: /v1/notebook/instance/keepalive参数

字段	类型	必填	说明
`id`	`string`	是	Notebook 执行实例 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/notebook/instance/keepalive \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000009"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

GET /v1/notebook/instance/list — 列出执行实例

列出调用账户的执行实例，不返回 code。limit 最多按 50 处理；keyword 优先于 name，匹配实例名或启动者的个人账户名称。Method: GET
Path: /v1/notebook/instance/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；默认 `10`
`notebook_id`	`string` / `null`	否	Notebook ID
`schedule_id`	`string` / `null`	否	调度 ID
`display_status`	`string` / `null`	否	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`
`launched`	`string` / `null`	否	实例启动方式；取值：`"manual"`, `"schedule"`
`keyword`	`string` / `null`	否	搜索关键词；≤ 255 字符
`name`	`string` / `null`	否	名称，按子串筛选；≤ 255 字符

返回字段

字段	类型	说明
`total_count`	`integer`	符合筛选条件的总数
`instances`	`object[]`	Notebook 执行实例

显示 instances — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`notebook_id`	`string` / `null`	Notebook ID
`name`	`string` / `null`	名称
`code`	`string` / `null`	本次执行的代码；实例列表不返回
`parameters`	`object[]`	参数定义
`arguments`	`object[]`	本次执行的参数值
`max_memory`	`integer` / `null`	内存配额，单位为字节
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_network_rx`	`integer` / `null`	记录的网络接收额度配置
`max_network_tx`	`integer` / `null`	记录的网络发送额度配置
`account_id`	`string` / `null`	账户 ID
`user_id`	`string` / `null`	启动执行的用户 ID
`schedule_id`	`string` / `null`	调度 ID
`background`	`boolean` / `null`	是否后台执行
`debug`	`boolean` / `null`	是否使用调试模式
`deadline`	`number` / `null`	前台实例到期时间，Unix 秒；后台为 null
`status`	`string`	状态；取值：`"running"`, `"ended"`
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`oom_killed`	`boolean` / `null`	是否因内存不足被终止
`exited_at`	`number` / `null`	退出时间，Unix 秒；运行中为 null
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`display_status`	`string`	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`, `"starting"`
`launched`	`string`	实例启动方式；取值：`"manual"`, `"schedule"`
`exit_message`	`string` / `null`	退出原因；运行中为 null
`account`	`object` / `null`	账户信息
`user`	`object` / `null`	启动者信息；不存在时为 null
`notebook`	`object` / `null`	关联 Notebook 的摘要；不存在时为 null
`schedule`	`object` / `null`	关联调度；没有调度时为 null

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	对象的唯一 ID
`order`	`integer` / `null`	参数顺序，不要求连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 user — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 notebook — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string` / `null`	名称
`space`	`string`	Space ID

显示 schedule — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`deleted_at`	`number` / `null`	删除时间，Unix 秒；未删除时为 null

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

请求示例

curl --get https://api.chaintable.com/v1/notebook/instance/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode notebook_id=01900000000070008000000000000002 \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "total_count": 1,
    "instances": [
      {
        "id": "01900000000070008000000000000009",
        "notebook_id": "01900000000070008000000000000002",
        "name": "print_message",
        "parameters": [],
        "arguments": [],
        "max_cpu": 100,
        "max_memory": 4294967296,
        "max_network_rx": null,
        "max_network_tx": null,
        "account_id": "0190000000007000800000000000000b",
        "user_id": "0190000000007000800000000000000c",
        "schedule_id": null,
        "background": false,
        "debug": false,
        "deadline": 1788220950.0,
        "status": "running",
        "exit_code": null,
        "oom_killed": null,
        "exited_at": null,
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "display_status": "running",
        "launched": "manual",
        "exit_message": null,
        "account": {
          "id": "0190000000007000800000000000000b",
          "type": "org",
          "slug": "example-team",
          "display_name": "Example team",
          "avatar_url": null,
          "avatar_thumbnail_url": null
        },
        "user": {
          "id": "0190000000007000800000000000000c",
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "account": null
        },
        "notebook": {
          "id": "01900000000070008000000000000002",
          "name": "print_message",
          "space": "demo"
        },
        "schedule": null
      }
    ]
  }
}

GET /v1/notebook/instance/logs/history — 读取历史日志

使用响应中的 timestamp 继续读取后续日志。Method: GET
Path: /v1/notebook/instance/logs/history参数

字段	类型	必填	说明
`id`	`string`	是	Notebook 执行实例 ID；1–255 字符
`timestamp`	`integer` / `null`	否	日志时间游标；≥ 0

返回字段

字段	类型	说明
`logs`	`object[]`	日志记录；字段随日志类型变化
`timestamp`	`number`	后续读取使用的日志游标，原样回传即可

请求示例

curl --get https://api.chaintable.com/v1/notebook/instance/logs/history \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000009

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "logs": [],
    "timestamp": 1788220800000
  }
}

GET /v1/notebook/instance/metrics/blockx — 读取计算任务指标

读取计算任务指标。Method: GET
Path: /v1/notebook/instance/metrics/blockx参数

字段	类型	必填	说明
`id`	`string`	是	Notebook 执行实例 ID；1–255 字符

返回字段

字段	类型	说明
`instance_id`	`string`	Notebook 执行实例 ID
`from`	`number`	指标范围开始时间，Unix 秒
`to`	`number`	指标范围结束时间，Unix 秒
`step`	`integer`	采样间隔，秒
`charts`	`object`	按指标名称组织的曲线

显示 charts — 每个值的字段

字段	类型	说明
`unit`	`string`	指标单位
`series`	`object[]`	图表系列

显示 series — 每项的字段

字段	类型	说明
`name`	`string`	名称
`points`	`number[][]`	采样点数组，每项为 [Unix 秒, 数值]

请求示例

curl --get https://api.chaintable.com/v1/notebook/instance/metrics/blockx \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000009

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "instance_id": "01900000000070008000000000000009",
    "from": 1788220800.0,
    "to": 1788220860.0,
    "step": 3,
    "charts": {
      "block_lag": {
        "unit": "ms",
        "series": [
          {
            "name": "block_lag",
            "points": [
              [
                1788220800.0,
                50
              ],
              [
                1788220803.0,
                45
              ]
            ]
          }
        ]
      },
      "tasks": {
        "unit": "per_sec",
        "series": [
          {
            "name": "task_total",
            "points": [
              [
                1788220800.0,
                10
              ]
            ]
          },
          {
            "name": "task_failed",
            "points": [
              [
                1788220800.0,
                0
              ]
            ]
          }
        ]
      },
      "task_duration": {
        "unit": "ms",
        "series": [
          {
            "name": "total",
            "points": [
              [
                1788220800.0,
                20
              ]
            ]
          },
          {
            "name": "builder",
            "points": [
              [
                1788220800.0,
                3
              ]
            ]
          },
          {
            "name": "calls",
            "points": [
              [
                1788220800.0,
                12
              ]
            ]
          },
          {
            "name": "writer",
            "points": [
              [
                1788220800.0,
                5
              ]
            ]
          }
        ]
      },
      "calls": {
        "unit": "per_sec",
        "series": [
          {
            "name": "call_total",
            "points": [
              [
                1788220800.0,
                10
              ]
            ]
          },
          {
            "name": "result_count",
            "points": [
              [
                1788220800.0,
                10
              ]
            ]
          }
        ]
      }
    }
  }
}

GET /v1/notebook/instance/metrics/container — 读取 CPU 和内存指标

读取 CPU 和内存指标。Method: GET
Path: /v1/notebook/instance/metrics/container参数

字段	类型	必填	说明
`id`	`string`	是	Notebook 执行实例 ID；1–255 字符

返回字段

字段	类型	说明
`instance_id`	`string`	Notebook 执行实例 ID
`from`	`number`	指标范围开始时间，Unix 秒
`to`	`number`	指标范围结束时间，Unix 秒
`step`	`integer`	采样间隔，秒
`charts`	`object`	按指标名称组织的曲线

显示 charts — 每个值的字段

字段	类型	说明
`unit`	`string`	指标单位
`series`	`object[]`	图表系列

显示 series — 每项的字段

字段	类型	说明
`name`	`string`	名称
`points`	`number[][]`	采样点数组，每项为 [Unix 秒, 数值]

请求示例

curl --get https://api.chaintable.com/v1/notebook/instance/metrics/container \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000009

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "instance_id": "01900000000070008000000000000009",
    "from": 1788220800.0,
    "to": 1788220860.0,
    "step": 3,
    "charts": {
      "cpu": {
        "unit": "percent",
        "series": [
          {
            "name": "cpu_usage",
            "points": [
              [
                1788220800.0,
                12.5
              ],
              [
                1788220803.0,
                12.5
              ]
            ]
          }
        ]
      },
      "memory": {
        "unit": "bytes",
        "series": [
          {
            "name": "memory_usage",
            "points": [
              [
                1788220800.0,
                104857600
              ],
              [
                1788220803.0,
                104857600
              ]
            ]
          }
        ]
      },
      "net_rx": {
        "unit": "bytes_per_sec",
        "series": [
          {
            "name": "net_rx",
            "points": [
              [
                1788220800.0,
                1024
              ],
              [
                1788220803.0,
                1024
              ]
            ]
          }
        ]
      },
      "net_tx": {
        "unit": "bytes_per_sec",
        "series": [
          {
            "name": "net_tx",
            "points": [
              [
                1788220800.0,
                512
              ],
              [
                1788220803.0,
                512
              ]
            ]
          }
        ]
      }
    }
  }
}

POST /v1/notebook/instance/set_background — 切换为后台执行

传入 background: true。切换后不能再转回前台。Method: POST
Path: /v1/notebook/instance/set_background参数

字段	类型	必填	说明
`id`	`string`	是	Notebook 执行实例 ID；1–255 字符
`background`	`boolean`	否	是否后台执行；默认 `true`

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/notebook/instance/set_background \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000009",
  "background": true
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

GET /v1/notebook/instance/specs — 列出可用计算规格

列出可用计算规格。Method: GET
Path: /v1/notebook/instance/specs参数无请求参数。返回字段

字段	类型	说明
`allowed_quota_spec`	`object[]`	可用的 CPU 和内存组合

显示 allowed_quota_spec — 每项的字段

字段	类型	说明
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节

请求示例

curl https://api.chaintable.com/v1/notebook/instance/specs \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID"

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "allowed_quota_spec": [
      {
        "max_cpu": 100,
        "max_memory": 4294967296
      },
      {
        "max_cpu": 200,
        "max_memory": 8589934592
      },
      {
        "max_cpu": 200,
        "max_memory": 17179869184
      },
      {
        "max_cpu": 200,
        "max_memory": 34359738368
      },
      {
        "max_cpu": 400,
        "max_memory": 17179869184
      },
      {
        "max_cpu": 400,
        "max_memory": 34359738368
      }
    ]
  }
}

GET /v1/notebook/list — 列出 Notebook

列出 Notebook。Method: GET
Path: /v1/notebook/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 100；默认 `10`
`order_by`	`string`	否	排序字段；取值：`"id"`, `"name"`, `"created_at"`, `"updated_at"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`
`space`	`string` / `null`	否	按 Space 筛选；省略时列出可见 Space 内的资源；1–64 字符
`name`	`string` / `null`	否	名称，按子串筛选
`schedule_space`	`string` / `null`	否	按调度所在 Space 筛选；1–64 字符
`with_schedule`	`boolean`	否	附带调度信息；默认 `false`

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`parameters`	`object[]`	参数定义
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`schedule`	`object` / `null`	仅 with_schedule=true 时返回的调度配置摘要；无调度为 null

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	对象的唯一 ID
`order`	`integer` / `null`	参数顺序，不要求连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 schedule — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

请求示例

curl --get https://api.chaintable.com/v1/notebook/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode space=demo \
  --data-urlencode limit=10 \
  --data-urlencode with_schedule=true

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "01900000000070008000000000000002",
        "space": "demo",
        "name": "print_message",
        "language": "python",
        "parameters": [],
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "space_entity": {
          "id": "demo",
          "description": "Example resources",
          "account_id": "0190000000007000800000000000000b",
          "status": "active",
          "visibility": "public",
          "dep_count": 0,
          "content_count": 6,
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "account": {
            "id": "0190000000007000800000000000000b",
            "type": "org",
            "slug": "example-team",
            "display_name": "Example team",
            "avatar_url": null,
            "avatar_thumbnail_url": null
          }
        },
        "schedule": null
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

POST /v1/notebook/run — 运行 Notebook

启动异步执行实例。提供已保存 Notebook 的 id 或内联 code；同时提供时使用传入的代码及参数定义。计算规格须采用 /v1/notebook/instance/specs 返回的一组值。Method: POST
Path: /v1/notebook/run参数

字段	类型	必填	说明
`id`	`string` / `null`	否	对象的唯一 ID；1–32 字符
`code`	`string` / `null`	否	执行代码；Query 使用 SQL
`parameters`	`object[]` / `null`	否	参数定义；更新时整体替换
`arguments`	`object[]`	否	本次执行的参数值
`max_cpu`	`integer`	是	CPU 配额，100 表示 1 vCPU；> 0
`max_memory`	`integer`	是	内存配额，单位为字节；> 0
`debug`	`boolean`	否	是否使用调试模式；默认 `false`
`background`	`boolean`	否	是否后台执行；默认 `false`

显示 parameters — 每项的字段

字段	类型	必填	说明
`name`	`string` / `null`	是	名称
`type`	`string`	是	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	否	参数可选值列表
`default`	`object` / `null`	否	默认参数值
`id`	`JSON` / `null`	否	对象的唯一 ID
`order`	`integer` / `null`	否	参数顺序，不要求连续编号；≥ 0

显示 default — 子字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值

显示 arguments — 每项的字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值
`name`	`string` / `null`	否	匹配的形参名称
`order`	`integer` / `null`	否	须全部省略或从 0 连续编号；按此顺序匹配参数；≥ 0

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`notebook_id`	`string` / `null`	Notebook ID
`name`	`string` / `null`	名称
`code`	`string` / `null`	本次执行的代码；实例列表不返回
`parameters`	`object[]`	参数定义
`arguments`	`object[]`	本次执行的参数值
`max_memory`	`integer` / `null`	内存配额，单位为字节
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_network_rx`	`integer` / `null`	记录的网络接收额度配置
`max_network_tx`	`integer` / `null`	记录的网络发送额度配置
`account_id`	`string` / `null`	账户 ID
`user_id`	`string` / `null`	启动执行的用户 ID
`schedule_id`	`string` / `null`	调度 ID
`background`	`boolean` / `null`	是否后台执行
`debug`	`boolean` / `null`	是否使用调试模式
`deadline`	`number` / `null`	前台实例到期时间，Unix 秒；后台为 null
`status`	`string`	状态；取值：`"running"`, `"ended"`
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`oom_killed`	`boolean` / `null`	是否因内存不足被终止
`exited_at`	`number` / `null`	退出时间，Unix 秒；运行中为 null
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`display_status`	`string`	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`, `"starting"`
`launched`	`string`	实例启动方式；取值：`"manual"`, `"schedule"`
`exit_message`	`string` / `null`	退出原因；运行中为 null
`account`	`object` / `null`	账户信息
`user`	`object` / `null`	启动者信息；不存在时为 null
`notebook`	`object` / `null`	关联 Notebook 的摘要；不存在时为 null
`schedule`	`object` / `null`	关联调度；没有调度时为 null

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	对象的唯一 ID
`order`	`integer` / `null`	参数顺序，不要求连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 user — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 notebook — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`name`	`string` / `null`	名称
`space`	`string`	Space ID

显示 schedule — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`deleted_at`	`number` / `null`	删除时间，Unix 秒；未删除时为 null

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

请求示例

curl https://api.chaintable.com/v1/notebook/run \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000002",
  "max_cpu": 100,
  "max_memory": 4294967296,
  "arguments": []
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000009",
    "notebook_id": "01900000000070008000000000000002",
    "name": "print_message",
    "code": "print(\"Hello, Chaintable\")",
    "parameters": [],
    "arguments": [],
    "max_cpu": 100,
    "max_memory": 4294967296,
    "max_network_rx": null,
    "max_network_tx": null,
    "account_id": "0190000000007000800000000000000b",
    "user_id": "0190000000007000800000000000000c",
    "schedule_id": null,
    "background": false,
    "debug": false,
    "deadline": 1788220950.0,
    "status": "running",
    "exit_code": null,
    "oom_killed": null,
    "exited_at": null,
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "display_status": "running",
    "launched": "manual",
    "exit_message": null,
    "account": {
      "id": "0190000000007000800000000000000b",
      "type": "org",
      "slug": "example-team",
      "display_name": "Example team",
      "avatar_url": null,
      "avatar_thumbnail_url": null
    },
    "user": {
      "id": "0190000000007000800000000000000c",
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": null
    },
    "notebook": {
      "id": "01900000000070008000000000000002",
      "name": "print_message",
      "space": "demo"
    },
    "schedule": null
  }
}

POST /v1/notebook/update — 更新 Notebook

更新 Notebook，未提交的字段保持不变；参数定义整体替换。名称遵循创建时的命名规则。Method: POST
Path: /v1/notebook/update参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`name`	`string`	否	名称；1–255 字符
`language`	`string`	否	代码语言；取值：`"python"`
`code`	`string` / `null`	否	执行代码；Query 使用 SQL
`parameters`	`object[]` / `null`	否	参数定义；更新时整体替换

显示 parameters — 每项的字段

字段	类型	必填	说明
`name`	`string` / `null`	是	名称
`type`	`string`	是	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	否	参数可选值列表
`default`	`object` / `null`	否	默认参数值
`id`	`JSON` / `null`	否	对象的唯一 ID
`order`	`integer` / `null`	否	参数顺序，不要求连续编号；≥ 0

显示 default — 子字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	Notebook 代码；列表不返回
`parameters`	`object[]`	参数定义
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	对象的唯一 ID
`order`	`integer` / `null`	参数顺序，不要求连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/notebook/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000002",
  "name": "print_message"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000002",
    "space": "demo",
    "name": "print_message",
    "language": "python",
    "code": "print(\"Hello, Chaintable\")",
    "parameters": [],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    }
  }
}

query

GET /v1/query — 读取 Query

读取 Query。Method: GET
Path: /v1/query参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	SQL 代码；列表不返回
`parameters`	`object[]`	参数定义
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`visualizations`	`object[]`	详情返回可视化；列表须指定 with_visualizations=true
`is_starred`	`boolean`	调用用户是否已收藏；详情返回，列表需 with_star=true 或按 star_count 排序
`star_count`	`integer`	收藏数量；详情返回，列表需 with_star=true 或按 star_count 排序

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 visualizations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

请求示例

curl --get https://api.chaintable.com/v1/query \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000001

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000001",
    "space": "demo",
    "name": "Asset count",
    "language": "sql",
    "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes",
    "parameters": [],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "visualizations": [
      {
        "id": "01900000000070008000000000000016",
        "query_id": "01900000000070008000000000000001",
        "name": "Query results",
        "type": "table",
        "options": {},
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0
      }
    ],
    "is_starred": false,
    "star_count": 0
  }
}

POST /v1/query/create — 创建 Query

使用调用方提供的唯一 id 创建 Query，并自动创建默认表格可视化。Method: POST
Path: /v1/query/create参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`space`	`string`	是	Space ID；1–64 字符
`name`	`string`	是	名称；1–64 字符
`code`	`string` / `null`	否	执行代码；Query 使用 SQL
`language`	`string`	否	查询语言；执行时使用 sql；取值：`"sql"`, `"python"`；默认 `"sql"`
`parameters`	`object[]` / `null`	否	参数定义；更新时整体替换

显示 parameters — 每项的字段

字段	类型	必填	说明
`name`	`string`	是	名称；1–64 字符
`type`	`string`	是	参数逻辑类型，见数据类型；1–64 字符
`options`	`JSON[]` / `null`	否	参数的可选值列表
`default`	`object` / `null`	否	默认参数值
`id`	`string` / `null`	否	参数的显示 ID，随定义保存；≤ 64 字符
`order`	`integer` / `null`	否	须全部省略或从 0 连续编号；≥ 0

显示 default — 子字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	SQL 代码；列表不返回
`parameters`	`object[]`	参数定义
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`visualizations`	`object[]`	详情返回可视化；列表须指定 with_visualizations=true
`is_starred`	`boolean`	调用用户是否已收藏；详情返回，列表需 with_star=true 或按 star_count 排序
`star_count`	`integer`	收藏数量；详情返回，列表需 with_star=true 或按 star_count 排序

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 visualizations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/query/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000001",
  "space": "demo",
  "name": "Asset count",
  "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes",
  "language": "sql"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000001",
    "space": "demo",
    "name": "Asset count",
    "language": "sql",
    "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes",
    "parameters": [],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "visualizations": [
      {
        "id": "01900000000070008000000000000016",
        "query_id": "01900000000070008000000000000001",
        "name": "Query results",
        "type": "table",
        "options": {},
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0
      }
    ],
    "is_starred": false,
    "star_count": 0
  }
}

POST /v1/query/delete — 删除 Query

删除 Query。Method: POST
Path: /v1/query/delete参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/query/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000001"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

GET /v1/query/job — 读取查询执行状态

检查 job.status；成功结果的信息位于 job_succeeded，失败信息位于 job_failed。Method: GET
Path: /v1/query/job参数

字段	类型	必填	说明
`id`	`string`	是	查询执行 ID；1–255 字符

返回字段

字段	类型	说明
`job`	`object`	执行记录
`job_pending`	`object`	等待阶段信息；其他阶段为空对象
`job_running`	`object`	执行阶段信息；其他阶段为空对象
`job_succeeded`	`object`	成功阶段信息；其他阶段为空对象
`job_failed`	`object`	失败阶段信息；其他阶段为空对象

显示 job — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string`	Query ID
`status`	`string`	状态；取值：`"pending"`, `"running"`, `"canceling"`, `"canceled"`, `"succeeded"`, `"failed"`
`error_msg`	`string` / `null`	执行错误说明；无错误时为 null
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`started_at`	`number` / `null`	开始时间，Unix 秒；尚未开始时为 null
`finished_at`	`number` / `null`	完成时间，Unix 秒；未结束时为 null

显示 job_pending — 子字段

字段	类型	说明
`position`	`integer`	图例位置；省略时自动安排

显示 job_running — 子字段

字段	类型	说明
`progress_percentage`	`number`	执行进度百分比

显示 job_succeeded — 子字段

字段	类型	说明
`query_result_id`	`string`	查询结果 ID，用于读取结果

显示 job_failed — 子字段

字段	类型	说明
`error_msg`	`string` / `null`	执行错误说明；无错误时为 null

请求示例

curl --get https://api.chaintable.com/v1/query/job \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000006

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "job": {
      "id": "01900000000070008000000000000006",
      "query_id": "01900000000070008000000000000001",
      "status": "succeeded",
      "error_msg": null,
      "created_at": 1788220800.0,
      "updated_at": 1788220801.0,
      "started_at": 1788220800.0,
      "finished_at": 1788220801.0
    },
    "job_pending": {},
    "job_running": {},
    "job_succeeded": {
      "query_result_id": "01900000000070008000000000000007"
    },
    "job_failed": {}
  }
}

POST /v1/query/job/cancel — 取消查询执行

取消查询执行。Method: POST
Path: /v1/query/job/cancel参数

字段	类型	必填	说明
`id`	`string`	是	查询执行 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/query/job/cancel \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000006"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/query/job/latest — 查找最近一次执行

按 Query ID、代码和参数匹配，优先返回已结束的执行；无匹配时 job_id 为 null。Method: POST
Path: /v1/query/job/latest参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`code`	`string`	是	执行代码；Query 使用 SQL
`arguments`	`object[]` / `null`	否	本次执行的参数值

显示 arguments — 每项的字段

字段	类型	必填	说明
`name`	`string`	是	SQL 占位符的名称
`value`	`JSON`	是	用于替换 SQL 占位符的值

返回字段

字段	类型	说明
`job_id`	`string` / `null`	查询执行 ID；无匹配记录时为 null

请求示例

curl https://api.chaintable.com/v1/query/job/latest \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000001",
  "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes",
  "arguments": []
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "job_id": "01900000000070008000000000000006"
  }
}

GET /v1/query/list — 列出 Query

列出 Query。Method: GET
Path: /v1/query/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 100；默认 `10`
`order_by`	`string`	否	排序字段；取值：`"id"`, `"name"`, `"created_at"`, `"updated_at"`, `"star_count"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`
`space`	`string` / `null`	否	按 Space 筛选；省略时列出可见 Space 内的资源；1–64 字符
`name`	`string` / `null`	否	名称，按子串筛选
`with_star`	`boolean`	否	附带收藏信息；默认 `false`
`with_schedule`	`boolean`	否	附带调度信息；默认 `false`
`with_visualizations`	`boolean`	否	附带可视化配置；默认 `false`

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`parameters`	`object[]`	参数定义
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`visualizations`	`object[]`	详情返回可视化；列表须指定 with_visualizations=true
`is_starred`	`boolean`	调用用户是否已收藏；详情返回，列表需 with_star=true 或按 star_count 排序
`star_count`	`integer`	收藏数量；详情返回，列表需 with_star=true 或按 star_count 排序
`schedule`	`object` / `null`	仅 with_schedule=true 时返回的调度配置摘要；无调度为 null

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 visualizations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

显示 schedule — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

请求示例

curl --get https://api.chaintable.com/v1/query/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode space=demo \
  --data-urlencode limit=10 \
  --data-urlencode with_visualizations=true

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "01900000000070008000000000000001",
        "space": "demo",
        "name": "Asset count",
        "language": "sql",
        "parameters": [],
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "space_entity": {
          "id": "demo",
          "description": "Example resources",
          "account_id": "0190000000007000800000000000000b",
          "status": "active",
          "visibility": "public",
          "dep_count": 0,
          "content_count": 6,
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "account": {
            "id": "0190000000007000800000000000000b",
            "type": "org",
            "slug": "example-team",
            "display_name": "Example team",
            "avatar_url": null,
            "avatar_thumbnail_url": null
          }
        },
        "visualizations": [
          {
            "id": "01900000000070008000000000000005",
            "query_id": "01900000000070008000000000000001",
            "name": "Asset count",
            "type": "chart",
            "options": {
              "type": "counter",
              "column_name": "row_count",
              "row_number": 0,
              "decimals": 0
            },
            "created_at": 1788220800.0,
            "updated_at": 1788220800.0
          }
        ]
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

GET /v1/query/result — 读取查询结果

id 是查询结果 ID，不是 Query ID 或 job ID。metadata_only=true 只读取结果元数据。Method: GET
Path: /v1/query/result参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 10000；默认 `10`
`id`	`string`	是	查询结果 ID；1–255 字符
`metadata_only`	`boolean`	否	是否只返回元数据；默认 `false`
`search`	`string` / `null`	否	结果搜索内容
`order_by`	`string` / `null`	否	排序字段
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`

返回字段

字段	类型	说明
`metadata`	`object`	结果列和完整结果集的统计
`data`	`object[]`	结果行，以列名为键；metadata_only=true 时为空数组

显示 metadata — 子字段

字段	类型	说明
`columns`	`object[]`	字段定义
`statistics`	`object`	完整结果集的统计

显示 columns — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	类型

显示 statistics — 子字段

字段	类型	说明
`rows_count`	`integer`	返回的记录数
`rows_size_bytes`	`integer`	结果集的内存大小估计，字节

请求示例

curl --get https://api.chaintable.com/v1/query/result \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000007 \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "metadata": {
      "columns": [
        {
          "name": "row_count",
          "type": "BIGINT"
        }
      ],
      "statistics": {
        "rows_count": 1,
        "rows_size_bytes": 256
      }
    },
    "data": [
      {
        "row_count": 1
      }
    ]
  }
}

POST /v1/query/run — 执行 SQL 查询

提交已保存 Query 的一次异步执行，使用本次传入的 SQL 和参数。通过 job_id 查询状态，成功后用 query_result_id 读取结果；已有等待或执行中的任务时返回 409。Method: POST
Path: /v1/query/run参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`code`	`string`	是	执行代码；Query 使用 SQL
`arguments`	`object[]` / `null`	否	本次执行的参数值

显示 arguments — 每项的字段

字段	类型	必填	说明
`name`	`string`	是	SQL 占位符的名称
`value`	`JSON`	是	用于替换 SQL 占位符的值

返回字段

字段	类型	说明
`job_id`	`string` / `null`	查询执行 ID；无匹配记录时为 null

请求示例

curl https://api.chaintable.com/v1/query/run \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000001",
  "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes",
  "arguments": []
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "job_id": "01900000000070008000000000000006"
  }
}

POST /v1/query/update — 更新 Query

更新 Query。Method: POST
Path: /v1/query/update参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`name`	`string`	否	名称；1–64 字符
`code`	`string` / `null`	否	执行代码；Query 使用 SQL
`parameters`	`object[]` / `null`	否	参数定义；更新时整体替换

显示 parameters — 每项的字段

字段	类型	必填	说明
`name`	`string`	是	名称；1–64 字符
`type`	`string`	是	参数逻辑类型，见数据类型；1–64 字符
`options`	`JSON[]` / `null`	否	参数的可选值列表
`default`	`object` / `null`	否	默认参数值
`id`	`string` / `null`	否	参数的显示 ID，随定义保存；≤ 64 字符
`order`	`integer` / `null`	否	须全部省略或从 0 连续编号；≥ 0

显示 default — 子字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`language`	`string` / `null`	代码语言
`code`	`string` / `null`	SQL 代码；列表不返回
`parameters`	`object[]`	参数定义
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`visualizations`	`object[]`	详情返回可视化；列表须指定 with_visualizations=true
`is_starred`	`boolean`	调用用户是否已收藏；详情返回，列表需 with_star=true 或按 star_count 排序
`star_count`	`integer`	收藏数量；详情返回，列表需 with_star=true 或按 star_count 排序

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 visualizations — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/query/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000001",
  "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000001",
    "space": "demo",
    "name": "Asset count",
    "language": "sql",
    "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes",
    "parameters": [],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "visualizations": [
      {
        "id": "01900000000070008000000000000016",
        "query_id": "01900000000070008000000000000001",
        "name": "Query results",
        "type": "table",
        "options": {},
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0
      }
    ],
    "is_starred": false,
    "star_count": 0
  }
}

POST /v1/query/visualization/create — 创建可视化配置

创建展示配置，不执行 SQL。type=table 对应 options.type=table；type=chart 对应 bar、line、area、scatter、pie 或 counter。options 的完整字段见下方参数说明。Method: POST
Path: /v1/query/visualization/create参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`query_id`	`string`	是	Query ID；1–255 字符
`name`	`string`	是	名称；1–64 字符
`type`	`string`	是	类型；取值：`"table"`, `"chart"`, `"counter"`
`options`	`object` / `null`	否	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`description`	`string` / `null`	否	用途说明
`type`	`string`	是	类型；固定为 `"table"`
`columns`	`object` / `null`	否	以结果列名为键的展示配置
`export_options`	`object` / `null`	否	结果导出配置

显示 columns — 每个值的字段

字段	类型	必填	说明
`name`	`string` / `null`	否	名称
`title`	`string` / `null`	否	显示标题
`align`	`string` / `null`	否	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	否	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	否	数值或日期格式串
`hide`	`boolean` / `null`	否	是否隐藏该列
`colored_positive`	`boolean` / `null`	否	是否为正值着色
`colored_negative`	`boolean` / `null`	否	是否为负值着色
`url_template`	`string` / `null`	否	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	必填	说明
`enabled`	`boolean` / `null`	否	是否启用导出
`formats`	`string[]` / `null`	否	允许的导出格式
`filename`	`string` / `null`	否	导出文件名
`include_all_data`	`boolean` / `null`	否	是否导出全部数据

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`description`	`string` / `null`	否	用途说明
`type`	`string`	是	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	否	横轴使用的结果列名
`y_columns`	`string[]` / `null`	否	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	否	横轴配置
`y_axis`	`object` / `null`	否	左侧纵轴配置
`right_y_axis`	`object` / `null`	否	右侧纵轴配置
`legend`	`object` / `null`	否	图例配置
`series`	`object` / `null`	否	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	否	是否堆叠系列
`show_data_labels`	`boolean` / `null`	否	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	否	是否在提示框中显示合计
`group_by`	`string` / `null`	否	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	否	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	否	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	否	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`tick_format`	`string` / `null`	否	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	否	提示框或数据标签的格式串
`type`	`string` / `null`	否	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	否	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	否	坐标轴最小值；不能大于 max
`max`	`number` / `null`	否	坐标轴最大值
`sort_values`	`boolean` / `null`	否	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	否	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	否	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	否	是否自动安排刻度
`nice`	`boolean` / `null`	否	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	否	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	否	刻度数量；≥ 1
`width`	`number` / `null`	否	坐标轴宽度；≥ 0
`reference_lines`	`object[]` / `null`	否	坐标轴参考线
`zones`	`object[]` / `null`	否	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	必填	说明
`value`	`number` / `string`	是	参考线位置；时间轴可用日期字符串
`stroke`	`string`	是	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	否	参考线刻度配置

显示 tick — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	必填	说明
`from`	`number` / `string` / `null`	否	标记区域的起点
`to`	`number` / `string` / `null`	否	标记区域的终点
`color`	`string` / `null`	否	CSS 颜色值
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项

显示 y_axis — 子字段

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`tick_format`	`string` / `null`	否	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	否	提示框或数据标签的格式串
`type`	`string` / `null`	否	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	否	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	否	坐标轴最小值；不能大于 max
`max`	`number` / `null`	否	坐标轴最大值
`sort_values`	`boolean` / `null`	否	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	否	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	否	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	否	是否自动安排刻度
`nice`	`boolean` / `null`	否	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	否	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	否	刻度数量；≥ 1
`width`	`number` / `null`	否	坐标轴宽度；≥ 0
`reference_lines`	`object[]` / `null`	否	坐标轴参考线
`zones`	`object[]` / `null`	否	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	必填	说明
`value`	`number` / `string`	是	参考线位置；时间轴可用日期字符串
`stroke`	`string`	是	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	否	参考线刻度配置

显示 tick — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	必填	说明
`from`	`number` / `string` / `null`	否	标记区域的起点
`to`	`number` / `string` / `null`	否	标记区域的终点
`color`	`string` / `null`	否	CSS 颜色值
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项

显示 right_y_axis — 子字段

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`tick_format`	`string` / `null`	否	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	否	提示框或数据标签的格式串
`type`	`string` / `null`	否	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	否	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	否	坐标轴最小值；不能大于 max
`max`	`number` / `null`	否	坐标轴最大值
`sort_values`	`boolean` / `null`	否	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	否	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	否	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	否	是否自动安排刻度
`nice`	`boolean` / `null`	否	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	否	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	否	刻度数量；≥ 1
`width`	`number` / `null`	否	坐标轴宽度；≥ 0
`reference_lines`	`object[]` / `null`	否	坐标轴参考线
`zones`	`object[]` / `null`	否	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	必填	说明
`value`	`number` / `string`	是	参考线位置；时间轴可用日期字符串
`stroke`	`string`	是	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	否	参考线刻度配置

显示 tick — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	必填	说明
`from`	`number` / `string` / `null`	否	标记区域的起点
`to`	`number` / `string` / `null`	否	标记区域的终点
`color`	`string` / `null`	否	CSS 颜色值
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项

显示 legend — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示；图例省略时显示
`position`	`string` / `null`	否	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	否	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	必填	说明
`title`	`string` / `null`	否	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	否	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	否	CSS 颜色值
`is_right`	`boolean` / `null`	否	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	否	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项
`silent`	`boolean` / `null`	否	是否禁用系列交互

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`description`	`string` / `null`	否	用途说明
`type`	`string`	是	类型；固定为 `"pie"`
`label_column`	`string` / `null`	否	饼图分类列名
`value_column`	`string` / `null`	否	饼图数值列名
`legend`	`object` / `null`	否	图例配置
`show_data_labels`	`boolean` / `null`	否	是否显示数据标签
`y_axis`	`object` / `null`	否	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	否	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	否	提示框中的系列名
`show_legend`	`boolean` / `null`	否	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示；图例省略时显示
`position`	`string` / `null`	否	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	否	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`tick_format`	`string` / `null`	否	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	否	提示框或数据标签的格式串
`type`	`string` / `null`	否	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	否	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	否	坐标轴最小值；不能大于 max
`max`	`number` / `null`	否	坐标轴最大值
`sort_values`	`boolean` / `null`	否	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	否	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	否	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	否	是否自动安排刻度
`nice`	`boolean` / `null`	否	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	否	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	否	刻度数量；≥ 1
`width`	`number` / `null`	否	坐标轴宽度；≥ 0
`reference_lines`	`object[]` / `null`	否	坐标轴参考线
`zones`	`object[]` / `null`	否	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	必填	说明
`value`	`number` / `string`	是	参考线位置；时间轴可用日期字符串
`stroke`	`string`	是	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	否	参考线刻度配置

显示 tick — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	必填	说明
`from`	`number` / `string` / `null`	否	标记区域的起点
`to`	`number` / `string` / `null`	否	标记区域的终点
`color`	`string` / `null`	否	CSS 颜色值
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项

显示 values_options — 每个值的字段

字段	类型	必填	说明
`color`	`string`	是	CSS 颜色值

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`description`	`string` / `null`	否	用途说明
`type`	`string`	是	类型；固定为 `"counter"`
`column_name`	`string` / `null`	否	计数器展示的数值列名
`row_number`	`integer` / `null`	否	结果行下标，从 0 开始，省略时为 0；≥ 0
`prefix`	`string` / `null`	否	数值前缀
`suffix`	`string` / `null`	否	数值后缀
`decimals`	`integer` / `null`	否	小数位数；省略时按列类型格式化；≥ 0；≤ 20
`colored_positive`	`boolean` / `null`	否	是否为正值着色
`colored_negative`	`boolean` / `null`	否	是否为负值着色
`label`	`string` / `null`	否	说明文字或展示分类

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/query/visualization/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000005",
  "query_id": "01900000000070008000000000000001",
  "name": "Asset count",
  "type": "chart",
  "options": {
    "type": "counter",
    "column_name": "row_count",
    "row_number": 0,
    "decimals": 0
  }
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000005",
    "query_id": "01900000000070008000000000000001",
    "name": "Asset count",
    "type": "chart",
    "options": {
      "type": "counter",
      "column_name": "row_count",
      "row_number": 0,
      "decimals": 0
    },
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0
  }
}

POST /v1/query/visualization/delete — 删除可视化配置

删除可视化配置。Method: POST
Path: /v1/query/visualization/delete参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/query/visualization/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000005"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/query/visualization/ensure_default — 获取或创建默认可视化

获取或创建默认可视化。Method: POST
Path: /v1/query/visualization/ensure_default参数

字段	类型	必填	说明
`query_id`	`string`	是	Query ID；1–255 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/query/visualization/ensure_default \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "query_id": "01900000000070008000000000000001"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000016",
    "query_id": "01900000000070008000000000000001",
    "name": "Query results",
    "type": "table",
    "options": {},
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0
  }
}

GET /v1/query/visualization/list — 列出可视化配置

列出可视化配置。Method: GET
Path: /v1/query/visualization/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 1000；默认 `100`
`order_by`	`string`	否	排序字段；取值：`"id"`, `"name"`, `"created_at"`, `"updated_at"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`
`query_id`	`string`	是	Query ID；1–255 字符

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

请求示例

curl --get https://api.chaintable.com/v1/query/visualization/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode query_id=01900000000070008000000000000001 \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "01900000000070008000000000000005",
        "query_id": "01900000000070008000000000000001",
        "name": "Asset count",
        "type": "chart",
        "options": {
          "type": "counter",
          "column_name": "row_count",
          "row_number": 0,
          "decimals": 0
        },
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

POST /v1/query/visualization/update — 更新可视化配置

更新名称或完整的 options，不执行 SQL。options 整体替换，{} 或 null 清空配置；未提交的顶层字段保持不变。Method: POST
Path: /v1/query/visualization/update参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`name`	`string` / `null`	否	名称；1–64 字符
`options`	`object` / `null`	否	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`description`	`string` / `null`	否	用途说明
`type`	`string`	是	类型；固定为 `"table"`
`columns`	`object` / `null`	否	以结果列名为键的展示配置
`export_options`	`object` / `null`	否	结果导出配置

显示 columns — 每个值的字段

字段	类型	必填	说明
`name`	`string` / `null`	否	名称
`title`	`string` / `null`	否	显示标题
`align`	`string` / `null`	否	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	否	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	否	数值或日期格式串
`hide`	`boolean` / `null`	否	是否隐藏该列
`colored_positive`	`boolean` / `null`	否	是否为正值着色
`colored_negative`	`boolean` / `null`	否	是否为负值着色
`url_template`	`string` / `null`	否	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	必填	说明
`enabled`	`boolean` / `null`	否	是否启用导出
`formats`	`string[]` / `null`	否	允许的导出格式
`filename`	`string` / `null`	否	导出文件名
`include_all_data`	`boolean` / `null`	否	是否导出全部数据

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`description`	`string` / `null`	否	用途说明
`type`	`string`	是	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	否	横轴使用的结果列名
`y_columns`	`string[]` / `null`	否	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	否	横轴配置
`y_axis`	`object` / `null`	否	左侧纵轴配置
`right_y_axis`	`object` / `null`	否	右侧纵轴配置
`legend`	`object` / `null`	否	图例配置
`series`	`object` / `null`	否	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	否	是否堆叠系列
`show_data_labels`	`boolean` / `null`	否	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	否	是否在提示框中显示合计
`group_by`	`string` / `null`	否	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	否	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	否	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	否	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`tick_format`	`string` / `null`	否	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	否	提示框或数据标签的格式串
`type`	`string` / `null`	否	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	否	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	否	坐标轴最小值；不能大于 max
`max`	`number` / `null`	否	坐标轴最大值
`sort_values`	`boolean` / `null`	否	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	否	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	否	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	否	是否自动安排刻度
`nice`	`boolean` / `null`	否	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	否	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	否	刻度数量；≥ 1
`width`	`number` / `null`	否	坐标轴宽度；≥ 0
`reference_lines`	`object[]` / `null`	否	坐标轴参考线
`zones`	`object[]` / `null`	否	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	必填	说明
`value`	`number` / `string`	是	参考线位置；时间轴可用日期字符串
`stroke`	`string`	是	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	否	参考线刻度配置

显示 tick — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	必填	说明
`from`	`number` / `string` / `null`	否	标记区域的起点
`to`	`number` / `string` / `null`	否	标记区域的终点
`color`	`string` / `null`	否	CSS 颜色值
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项

显示 y_axis — 子字段

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`tick_format`	`string` / `null`	否	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	否	提示框或数据标签的格式串
`type`	`string` / `null`	否	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	否	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	否	坐标轴最小值；不能大于 max
`max`	`number` / `null`	否	坐标轴最大值
`sort_values`	`boolean` / `null`	否	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	否	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	否	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	否	是否自动安排刻度
`nice`	`boolean` / `null`	否	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	否	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	否	刻度数量；≥ 1
`width`	`number` / `null`	否	坐标轴宽度；≥ 0
`reference_lines`	`object[]` / `null`	否	坐标轴参考线
`zones`	`object[]` / `null`	否	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	必填	说明
`value`	`number` / `string`	是	参考线位置；时间轴可用日期字符串
`stroke`	`string`	是	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	否	参考线刻度配置

显示 tick — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	必填	说明
`from`	`number` / `string` / `null`	否	标记区域的起点
`to`	`number` / `string` / `null`	否	标记区域的终点
`color`	`string` / `null`	否	CSS 颜色值
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项

显示 right_y_axis — 子字段

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`tick_format`	`string` / `null`	否	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	否	提示框或数据标签的格式串
`type`	`string` / `null`	否	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	否	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	否	坐标轴最小值；不能大于 max
`max`	`number` / `null`	否	坐标轴最大值
`sort_values`	`boolean` / `null`	否	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	否	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	否	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	否	是否自动安排刻度
`nice`	`boolean` / `null`	否	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	否	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	否	刻度数量；≥ 1
`width`	`number` / `null`	否	坐标轴宽度；≥ 0
`reference_lines`	`object[]` / `null`	否	坐标轴参考线
`zones`	`object[]` / `null`	否	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	必填	说明
`value`	`number` / `string`	是	参考线位置；时间轴可用日期字符串
`stroke`	`string`	是	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	否	参考线刻度配置

显示 tick — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	必填	说明
`from`	`number` / `string` / `null`	否	标记区域的起点
`to`	`number` / `string` / `null`	否	标记区域的终点
`color`	`string` / `null`	否	CSS 颜色值
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项

显示 legend — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示；图例省略时显示
`position`	`string` / `null`	否	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	否	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	必填	说明
`title`	`string` / `null`	否	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	否	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	否	CSS 颜色值
`is_right`	`boolean` / `null`	否	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	否	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项
`silent`	`boolean` / `null`	否	是否禁用系列交互

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`description`	`string` / `null`	否	用途说明
`type`	`string`	是	类型；固定为 `"pie"`
`label_column`	`string` / `null`	否	饼图分类列名
`value_column`	`string` / `null`	否	饼图数值列名
`legend`	`object` / `null`	否	图例配置
`show_data_labels`	`boolean` / `null`	否	是否显示数据标签
`y_axis`	`object` / `null`	否	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	否	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	否	提示框中的系列名
`show_legend`	`boolean` / `null`	否	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示；图例省略时显示
`position`	`string` / `null`	否	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	否	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`tick_format`	`string` / `null`	否	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	否	提示框或数据标签的格式串
`type`	`string` / `null`	否	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	否	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	否	坐标轴最小值；不能大于 max
`max`	`number` / `null`	否	坐标轴最大值
`sort_values`	`boolean` / `null`	否	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	否	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	否	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	否	是否自动安排刻度
`nice`	`boolean` / `null`	否	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	否	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	否	刻度数量；≥ 1
`width`	`number` / `null`	否	坐标轴宽度；≥ 0
`reference_lines`	`object[]` / `null`	否	坐标轴参考线
`zones`	`object[]` / `null`	否	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	必填	说明
`value`	`number` / `string`	是	参考线位置；时间轴可用日期字符串
`stroke`	`string`	是	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	否	参考线刻度配置

显示 tick — 子字段

字段	类型	必填	说明
`show`	`boolean` / `null`	否	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	必填	说明
`from`	`number` / `string` / `null`	否	标记区域的起点
`to`	`number` / `string` / `null`	否	标记区域的终点
`color`	`string` / `null`	否	CSS 颜色值
`fill_gradient`	`string[]` / `null`	否	渐变起止颜色，恰好两个 CSS 颜色值；2–2 项

显示 values_options — 每个值的字段

字段	类型	必填	说明
`color`	`string`	是	CSS 颜色值

字段	类型	必填	说明
`title`	`string` / `null`	否	显示标题
`description`	`string` / `null`	否	用途说明
`type`	`string`	是	类型；固定为 `"counter"`
`column_name`	`string` / `null`	否	计数器展示的数值列名
`row_number`	`integer` / `null`	否	结果行下标，从 0 开始，省略时为 0；≥ 0
`prefix`	`string` / `null`	否	数值前缀
`suffix`	`string` / `null`	否	数值后缀
`decimals`	`integer` / `null`	否	小数位数；省略时按列类型格式化；≥ 0；≤ 20
`colored_positive`	`boolean` / `null`	否	是否为正值着色
`colored_negative`	`boolean` / `null`	否	是否为负值着色
`label`	`string` / `null`	否	说明文字或展示分类

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

请求示例

curl https://api.chaintable.com/v1/query/visualization/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000005",
  "name": "Total assets",
  "options": {
    "type": "counter",
    "column_name": "row_count",
    "decimals": 0
  }
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000005",
    "query_id": "01900000000070008000000000000001",
    "name": "Total assets",
    "type": "chart",
    "options": {
      "type": "counter",
      "column_name": "row_count",
      "decimals": 0
    },
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0
  }
}

dashboard

GET /v1/dashboard — 读取 Dashboard

读取 Dashboard。Method: GET
Path: /v1/dashboard参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–32 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`options`	`object`	配置对象
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`widgets`	`object[]`	详情和创建、更新响应中的 Widget；列表不返回
`is_starred`	`boolean`	调用用户是否已收藏；详情返回，列表需 with_star=true 或按 star_count 排序
`star_count`	`integer`	收藏数量；详情返回，列表需 with_star=true 或按 star_count 排序

显示 options — 子字段

字段	类型	说明
`layout`	`object` / `null`	按屏幕尺寸配置 Widget 位置

显示 layout — 子字段

字段	类型	说明
`lg`	`object` / `null`	桌面布局，6 列；键为 Widget ID，x + w 不能超过 6
`sm`	`object` / `null`	移动端布局，1 列；键为 Widget ID，x 必须为 0

显示 lg — 每个值的字段

字段	类型	说明
`x`	`integer`	从 0 开始的列坐标
`y`	`integer`	从 0 开始的行坐标
`w`	`integer`	占用的网格列数
`h`	`integer`	占用的网格行数
`min_w`	`integer` / `null`	最小宽度，网格列数；旧布局字段
`min_h`	`integer` / `null`	最小高度，网格行数；旧布局字段
`max_w`	`integer` / `null`	最大宽度，网格列数；旧布局字段
`max_h`	`integer` / `null`	最大高度，网格行数；旧布局字段

显示 sm — 每个值的字段

字段	类型	说明
`x`	`integer`	从 0 开始的列坐标
`y`	`integer`	从 0 开始的行坐标
`w`	`integer`	占用的网格列数
`h`	`integer`	占用的网格行数
`min_w`	`integer` / `null`	最小宽度，网格列数；旧布局字段
`min_h`	`integer` / `null`	最小高度，网格行数；旧布局字段
`max_w`	`integer` / `null`	最大宽度，网格列数；旧布局字段
`max_h`	`integer` / `null`	最大高度，网格行数；旧布局字段

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 widgets — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`dashboard_id`	`string` / `null`	Dashboard ID
`type`	`string`	类型；取值：`"text"`, `"visualization"`, `"parameter"`
`visualization_id`	`string` / `null`	可视化配置 ID
`text_content`	`string` / `null`	Markdown 文字内容
`options`	`object`	展示配置；写入只接受 {} 或 null。图表配置使用 Visualization，位置使用 Dashboard 布局
`entities`	`object[]`	关联资源列表
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`entities_map`	`object`	按资源类型和 ID 索引的关联内容
`visualization`	`object` / `null`	引用的可视化；不可读或已删除时为 null
`parameters`	`object[]` / `null`	参数定义
`code`	`string` / `null`	执行代码；Query 使用 SQL
`space_entity`	`object` / `null`	所属 Space 的信息
`query_name`	`string` / `null`	引用 Query 的名称；不可用时为 null

显示 entities — 每项的字段

字段	类型	说明
`type`	`string`	类型；取值：`"query"`, `"dashboard"`, `"notebook"`, `"table"`, `"field"`, `"function"`, `"contract"`, `"chain"`, `"schedule"`, `"page"`, `"issue"`
`id`	`string`	对象的唯一 ID
`raw`	`string`	正文中用于引用资源的原始文本

显示 entities_map — 按资源类型

显示按资源 ID 查看字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 visualization — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl --get https://api.chaintable.com/v1/dashboard \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=01900000000070008000000000000003

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000003",
    "space": "demo",
    "name": "Asset overview",
    "options": {},
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "widgets": [
      {
        "id": "01900000000070008000000000000004",
        "dashboard_id": "01900000000070008000000000000003",
        "type": "visualization",
        "visualization_id": "01900000000070008000000000000005",
        "text_content": null,
        "options": {},
        "entities": [],
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "visualization": {
          "id": "01900000000070008000000000000005",
          "query_id": "01900000000070008000000000000001",
          "name": "Asset count",
          "type": "chart",
          "options": {
            "type": "counter",
            "column_name": "row_count",
            "row_number": 0,
            "decimals": 0
          },
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0
        },
        "parameters": [],
        "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes",
        "space_entity": {
          "id": "demo",
          "description": "Example resources",
          "account_id": "0190000000007000800000000000000b",
          "status": "active",
          "visibility": "public",
          "dep_count": 0,
          "content_count": 6,
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "account": {
            "id": "0190000000007000800000000000000b",
            "type": "org",
            "slug": "example-team",
            "display_name": "Example team",
            "avatar_url": null,
            "avatar_thumbnail_url": null
          }
        },
        "query_name": "Asset count",
        "entities_map": {}
      }
    ],
    "is_starred": false,
    "star_count": 0
  }
}

POST /v1/dashboard/create — 创建 Dashboard

id 由调用方生成。创建后通过 Widget 接口添加文字或可视化内容。Method: POST
Path: /v1/dashboard/create参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–32 字符
`name`	`string`	是	名称；1–64 字符
`options`	`object` / `null`	否	配置对象
`space`	`string`	是	Space ID；1–64 字符

显示 options — 子字段

字段	类型	必填	说明
`layout`	`object` / `null`	否	按屏幕尺寸配置 Widget 位置

显示 layout — 子字段

字段	类型	必填	说明
`lg`	`object` / `null`	否	桌面布局，6 列；键为 Widget ID，x + w 不能超过 6
`sm`	`object` / `null`	否	移动端布局，1 列；键为 Widget ID，x 必须为 0

显示 lg — 每个值的字段

字段	类型	必填	说明
`x`	`integer`	是	从 0 开始的列坐标；≥ 0
`y`	`integer`	是	从 0 开始的行坐标；≥ 0
`w`	`integer`	是	占用的网格列数；≥ 1；≤ 6
`h`	`integer`	是	占用的网格行数；≥ 1
`min_w`	`integer` / `null`	否	最小宽度，网格列数；旧布局字段；≥ 1
`min_h`	`integer` / `null`	否	最小高度，网格行数；旧布局字段；≥ 1
`max_w`	`integer` / `null`	否	最大宽度，网格列数；旧布局字段；≥ 1
`max_h`	`integer` / `null`	否	最大高度，网格行数；旧布局字段；≥ 1

显示 sm — 每个值的字段

字段	类型	必填	说明
`x`	`integer`	是	从 0 开始的列坐标；≥ 0
`y`	`integer`	是	从 0 开始的行坐标；≥ 0
`w`	`integer`	是	占用的网格列数；≥ 1；≤ 6
`h`	`integer`	是	占用的网格行数；≥ 1
`min_w`	`integer` / `null`	否	最小宽度，网格列数；旧布局字段；≥ 1
`min_h`	`integer` / `null`	否	最小高度，网格行数；旧布局字段；≥ 1
`max_w`	`integer` / `null`	否	最大宽度，网格列数；旧布局字段；≥ 1
`max_h`	`integer` / `null`	否	最大高度，网格行数；旧布局字段；≥ 1

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`options`	`object`	配置对象
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`widgets`	`object[]`	详情和创建、更新响应中的 Widget；列表不返回
`is_starred`	`boolean`	调用用户是否已收藏；详情返回，列表需 with_star=true 或按 star_count 排序
`star_count`	`integer`	收藏数量；详情返回，列表需 with_star=true 或按 star_count 排序

显示 options — 子字段

字段	类型	说明
`layout`	`object` / `null`	按屏幕尺寸配置 Widget 位置

显示 layout — 子字段

字段	类型	说明
`lg`	`object` / `null`	桌面布局，6 列；键为 Widget ID，x + w 不能超过 6
`sm`	`object` / `null`	移动端布局，1 列；键为 Widget ID，x 必须为 0

显示 lg — 每个值的字段

字段	类型	说明
`x`	`integer`	从 0 开始的列坐标
`y`	`integer`	从 0 开始的行坐标
`w`	`integer`	占用的网格列数
`h`	`integer`	占用的网格行数
`min_w`	`integer` / `null`	最小宽度，网格列数；旧布局字段
`min_h`	`integer` / `null`	最小高度，网格行数；旧布局字段
`max_w`	`integer` / `null`	最大宽度，网格列数；旧布局字段
`max_h`	`integer` / `null`	最大高度，网格行数；旧布局字段

显示 sm — 每个值的字段

字段	类型	说明
`x`	`integer`	从 0 开始的列坐标
`y`	`integer`	从 0 开始的行坐标
`w`	`integer`	占用的网格列数
`h`	`integer`	占用的网格行数
`min_w`	`integer` / `null`	最小宽度，网格列数；旧布局字段
`min_h`	`integer` / `null`	最小高度，网格行数；旧布局字段
`max_w`	`integer` / `null`	最大宽度，网格列数；旧布局字段
`max_h`	`integer` / `null`	最大高度，网格行数；旧布局字段

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 widgets — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`dashboard_id`	`string` / `null`	Dashboard ID
`type`	`string`	类型；取值：`"text"`, `"visualization"`, `"parameter"`
`visualization_id`	`string` / `null`	可视化配置 ID
`text_content`	`string` / `null`	Markdown 文字内容
`options`	`object`	展示配置；写入只接受 {} 或 null。图表配置使用 Visualization，位置使用 Dashboard 布局
`entities`	`object[]`	关联资源列表
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`entities_map`	`object`	按资源类型和 ID 索引的关联内容
`visualization`	`object` / `null`	引用的可视化；不可读或已删除时为 null
`parameters`	`object[]` / `null`	参数定义
`code`	`string` / `null`	执行代码；Query 使用 SQL
`space_entity`	`object` / `null`	所属 Space 的信息
`query_name`	`string` / `null`	引用 Query 的名称；不可用时为 null

显示 entities — 每项的字段

字段	类型	说明
`type`	`string`	类型；取值：`"query"`, `"dashboard"`, `"notebook"`, `"table"`, `"field"`, `"function"`, `"contract"`, `"chain"`, `"schedule"`, `"page"`, `"issue"`
`id`	`string`	对象的唯一 ID
`raw`	`string`	正文中用于引用资源的原始文本

显示 entities_map — 按资源类型

显示按资源 ID 查看字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 visualization — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/dashboard/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000003",
  "space": "demo",
  "name": "Asset overview"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000003",
    "space": "demo",
    "name": "Asset overview",
    "options": {},
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "widgets": [],
    "is_starred": false,
    "star_count": 0
  }
}

POST /v1/dashboard/delete — 删除 Dashboard

删除 Dashboard。Method: POST
Path: /v1/dashboard/delete参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–32 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/dashboard/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000003"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

GET /v1/dashboard/list — 列出 Dashboard

列出 Dashboard。Method: GET
Path: /v1/dashboard/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 100；默认 `10`
`order_by`	`string`	否	排序字段；取值：`"id"`, `"name"`, `"created_at"`, `"updated_at"`, `"star_count"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`
`space`	`string` / `null`	否	按 Space 筛选；省略时列出可见 Space 内的资源；1–64 字符
`name`	`string` / `null`	否	名称，按子串筛选
`with_star`	`boolean`	否	附带收藏信息；默认 `false`
`with_schedule`	`boolean`	否	附带调度信息；默认 `false`

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`options`	`object`	配置对象
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`is_starred`	`boolean`	调用用户是否已收藏；详情返回，列表需 with_star=true 或按 star_count 排序
`star_count`	`integer`	收藏数量；详情返回，列表需 with_star=true 或按 star_count 排序
`schedule`	`object` / `null`	仅 with_schedule=true 时返回的调度配置摘要；无调度为 null

显示 options — 子字段

字段	类型	说明
`layout`	`object` / `null`	按屏幕尺寸配置 Widget 位置

显示 layout — 子字段

字段	类型	说明
`lg`	`object` / `null`	桌面布局，6 列；键为 Widget ID，x + w 不能超过 6
`sm`	`object` / `null`	移动端布局，1 列；键为 Widget ID，x 必须为 0

显示 lg — 每个值的字段

字段	类型	说明
`x`	`integer`	从 0 开始的列坐标
`y`	`integer`	从 0 开始的行坐标
`w`	`integer`	占用的网格列数
`h`	`integer`	占用的网格行数
`min_w`	`integer` / `null`	最小宽度，网格列数；旧布局字段
`min_h`	`integer` / `null`	最小高度，网格行数；旧布局字段
`max_w`	`integer` / `null`	最大宽度，网格列数；旧布局字段
`max_h`	`integer` / `null`	最大高度，网格行数；旧布局字段

显示 sm — 每个值的字段

字段	类型	说明
`x`	`integer`	从 0 开始的列坐标
`y`	`integer`	从 0 开始的行坐标
`w`	`integer`	占用的网格列数
`h`	`integer`	占用的网格行数
`min_w`	`integer` / `null`	最小宽度，网格列数；旧布局字段
`min_h`	`integer` / `null`	最小高度，网格行数；旧布局字段
`max_w`	`integer` / `null`	最大宽度，网格列数；旧布局字段
`max_h`	`integer` / `null`	最大高度，网格行数；旧布局字段

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 schedule — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

请求示例

curl --get https://api.chaintable.com/v1/dashboard/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode space=demo \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "01900000000070008000000000000003",
        "space": "demo",
        "name": "Asset overview",
        "options": {},
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "space_entity": {
          "id": "demo",
          "description": "Example resources",
          "account_id": "0190000000007000800000000000000b",
          "status": "active",
          "visibility": "public",
          "dep_count": 0,
          "content_count": 6,
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "account": {
            "id": "0190000000007000800000000000000b",
            "type": "org",
            "slug": "example-team",
            "display_name": "Example team",
            "avatar_url": null,
            "avatar_thumbnail_url": null
          }
        }
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

POST /v1/dashboard/update — 更新 Dashboard

更新名称、完整布局或所属 Space。options 整体替换；target_space 只能是同一账户下可编辑的 Space。Method: POST
Path: /v1/dashboard/update参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–32 字符
`name`	`string`	否	名称；1–64 字符
`options`	`object` / `null`	否	配置对象
`target_space`	`string`	否	目标 Space ID；1–64 字符

显示 options — 子字段

字段	类型	必填	说明
`layout`	`object` / `null`	否	按屏幕尺寸配置 Widget 位置

显示 layout — 子字段

字段	类型	必填	说明
`lg`	`object` / `null`	否	桌面布局，6 列；键为 Widget ID，x + w 不能超过 6
`sm`	`object` / `null`	否	移动端布局，1 列；键为 Widget ID，x 必须为 0

显示 lg — 每个值的字段

字段	类型	必填	说明
`x`	`integer`	是	从 0 开始的列坐标；≥ 0
`y`	`integer`	是	从 0 开始的行坐标；≥ 0
`w`	`integer`	是	占用的网格列数；≥ 1；≤ 6
`h`	`integer`	是	占用的网格行数；≥ 1
`min_w`	`integer` / `null`	否	最小宽度，网格列数；旧布局字段；≥ 1
`min_h`	`integer` / `null`	否	最小高度，网格行数；旧布局字段；≥ 1
`max_w`	`integer` / `null`	否	最大宽度，网格列数；旧布局字段；≥ 1
`max_h`	`integer` / `null`	否	最大高度，网格行数；旧布局字段；≥ 1

显示 sm — 每个值的字段

字段	类型	必填	说明
`x`	`integer`	是	从 0 开始的列坐标；≥ 0
`y`	`integer`	是	从 0 开始的行坐标；≥ 0
`w`	`integer`	是	占用的网格列数；≥ 1；≤ 6
`h`	`integer`	是	占用的网格行数；≥ 1
`min_w`	`integer` / `null`	否	最小宽度，网格列数；旧布局字段；≥ 1
`min_h`	`integer` / `null`	否	最小高度，网格行数；旧布局字段；≥ 1
`max_w`	`integer` / `null`	否	最大宽度，网格列数；旧布局字段；≥ 1
`max_h`	`integer` / `null`	否	最大高度，网格行数；旧布局字段；≥ 1

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`options`	`object`	配置对象
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`widgets`	`object[]`	详情和创建、更新响应中的 Widget；列表不返回
`is_starred`	`boolean`	调用用户是否已收藏；详情返回，列表需 with_star=true 或按 star_count 排序
`star_count`	`integer`	收藏数量；详情返回，列表需 with_star=true 或按 star_count 排序

显示 options — 子字段

字段	类型	说明
`layout`	`object` / `null`	按屏幕尺寸配置 Widget 位置

显示 layout — 子字段

字段	类型	说明
`lg`	`object` / `null`	桌面布局，6 列；键为 Widget ID，x + w 不能超过 6
`sm`	`object` / `null`	移动端布局，1 列；键为 Widget ID，x 必须为 0

显示 lg — 每个值的字段

字段	类型	说明
`x`	`integer`	从 0 开始的列坐标
`y`	`integer`	从 0 开始的行坐标
`w`	`integer`	占用的网格列数
`h`	`integer`	占用的网格行数
`min_w`	`integer` / `null`	最小宽度，网格列数；旧布局字段
`min_h`	`integer` / `null`	最小高度，网格行数；旧布局字段
`max_w`	`integer` / `null`	最大宽度，网格列数；旧布局字段
`max_h`	`integer` / `null`	最大高度，网格行数；旧布局字段

显示 sm — 每个值的字段

字段	类型	说明
`x`	`integer`	从 0 开始的列坐标
`y`	`integer`	从 0 开始的行坐标
`w`	`integer`	占用的网格列数
`h`	`integer`	占用的网格行数
`min_w`	`integer` / `null`	最小宽度，网格列数；旧布局字段
`min_h`	`integer` / `null`	最小高度，网格行数；旧布局字段
`max_w`	`integer` / `null`	最大宽度，网格列数；旧布局字段
`max_h`	`integer` / `null`	最大高度，网格行数；旧布局字段

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 widgets — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`dashboard_id`	`string` / `null`	Dashboard ID
`type`	`string`	类型；取值：`"text"`, `"visualization"`, `"parameter"`
`visualization_id`	`string` / `null`	可视化配置 ID
`text_content`	`string` / `null`	Markdown 文字内容
`options`	`object`	展示配置；写入只接受 {} 或 null。图表配置使用 Visualization，位置使用 Dashboard 布局
`entities`	`object[]`	关联资源列表
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`entities_map`	`object`	按资源类型和 ID 索引的关联内容
`visualization`	`object` / `null`	引用的可视化；不可读或已删除时为 null
`parameters`	`object[]` / `null`	参数定义
`code`	`string` / `null`	执行代码；Query 使用 SQL
`space_entity`	`object` / `null`	所属 Space 的信息
`query_name`	`string` / `null`	引用 Query 的名称；不可用时为 null

显示 entities — 每项的字段

字段	类型	说明
`type`	`string`	类型；取值：`"query"`, `"dashboard"`, `"notebook"`, `"table"`, `"field"`, `"function"`, `"contract"`, `"chain"`, `"schedule"`, `"page"`, `"issue"`
`id`	`string`	对象的唯一 ID
`raw`	`string`	正文中用于引用资源的原始文本

显示 entities_map — 按资源类型

显示按资源 ID 查看字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 visualization — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/dashboard/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000003",
  "options": {
    "layout": {
      "lg": {
        "01900000000070008000000000000004": {
          "x": 0,
          "y": 0,
          "w": 3,
          "h": 8
        }
      },
      "sm": {
        "01900000000070008000000000000004": {
          "x": 0,
          "y": 0,
          "w": 1,
          "h": 8
        }
      }
    }
  }
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000003",
    "space": "demo",
    "name": "Asset overview",
    "options": {
      "layout": {
        "lg": {
          "01900000000070008000000000000004": {
            "x": 0,
            "y": 0,
            "w": 3,
            "h": 8
          }
        },
        "sm": {
          "01900000000070008000000000000004": {
            "x": 0,
            "y": 0,
            "w": 1,
            "h": 8
          }
        }
      }
    },
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "widgets": [],
    "is_starred": false,
    "star_count": 0
  }
}

POST /v1/dashboard/widget/create — 添加 Widget

添加文本或已有可视化。type=visualization 时必须提供 visualization_id，其他类型不能提供。图表配置保存在 Visualization，位置保存在 Dashboard 的布局中。Method: POST
Path: /v1/dashboard/widget/create参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–32 字符
`dashboard_id`	`string`	是	Dashboard ID；1–32 字符
`type`	`string`	是	类型；取值：`"text"`, `"visualization"`, `"parameter"`
`text_content`	`string` / `null`	否	Markdown 文字内容
`visualization_id`	`string` / `null`	否	可视化配置 ID；1–32 字符
`options`	`object` / `null`	否	展示配置；写入只接受 {} 或 null。图表配置使用 Visualization，位置使用 Dashboard 布局
`entities`	`object[]`	否	关联资源列表

显示 entities — 每项的字段

字段	类型	必填	说明
`type`	`string`	是	类型；取值：`"query"`, `"dashboard"`, `"notebook"`, `"table"`, `"field"`, `"function"`, `"contract"`, `"chain"`, `"schedule"`, `"page"`, `"issue"`
`id`	`string`	是	对象的唯一 ID；1–255 字符
`raw`	`string`	是	正文中用于引用资源的原始文本；1–255 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`dashboard_id`	`string` / `null`	Dashboard ID
`type`	`string`	类型；取值：`"text"`, `"visualization"`, `"parameter"`
`visualization_id`	`string` / `null`	可视化配置 ID
`text_content`	`string` / `null`	Markdown 文字内容
`options`	`object`	展示配置；写入只接受 {} 或 null。图表配置使用 Visualization，位置使用 Dashboard 布局
`entities`	`object[]`	关联资源列表
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`entities_map`	`object`	按资源类型和 ID 索引的关联内容
`visualization`	`object` / `null`	引用的可视化；不可读或已删除时为 null
`parameters`	`object[]` / `null`	参数定义
`code`	`string` / `null`	执行代码；Query 使用 SQL
`space_entity`	`object` / `null`	所属 Space 的信息
`query_name`	`string` / `null`	引用 Query 的名称；不可用时为 null

显示 entities — 每项的字段

字段	类型	说明
`type`	`string`	类型；取值：`"query"`, `"dashboard"`, `"notebook"`, `"table"`, `"field"`, `"function"`, `"contract"`, `"chain"`, `"schedule"`, `"page"`, `"issue"`
`id`	`string`	对象的唯一 ID
`raw`	`string`	正文中用于引用资源的原始文本

显示 entities_map — 按资源类型

显示按资源 ID 查看字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 visualization — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/dashboard/widget/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000004",
  "dashboard_id": "01900000000070008000000000000003",
  "type": "visualization",
  "visualization_id": "01900000000070008000000000000005"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000004",
    "dashboard_id": "01900000000070008000000000000003",
    "type": "visualization",
    "visualization_id": "01900000000070008000000000000005",
    "text_content": null,
    "options": {},
    "entities": [],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "entities_map": {},
    "visualization": {
      "id": "01900000000070008000000000000005",
      "query_id": "01900000000070008000000000000001",
      "name": "Asset count",
      "type": "chart",
      "options": {
        "type": "counter",
        "column_name": "row_count",
        "row_number": 0,
        "decimals": 0
      },
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0
    },
    "parameters": [],
    "code": "SELECT COUNT(*) AS row_count FROM demo.asset_notes",
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "query_name": "Asset count"
  }
}

POST /v1/dashboard/widget/delete — 删除 Widget

删除 Widget。Method: POST
Path: /v1/dashboard/widget/delete参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–32 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/dashboard/widget/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000004"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/dashboard/widget/update — 更新 Widget

更新 Widget 内容。所属 Dashboard、类型和引用的可视化不可修改；更换可视化需删除并重新创建 Widget。Method: POST
Path: /v1/dashboard/widget/update参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–32 字符
`text_content`	`string` / `null`	否	Markdown 文字内容
`options`	`object` / `null`	否	展示配置；写入只接受 {} 或 null。图表配置使用 Visualization，位置使用 Dashboard 布局
`entities`	`object[]` / `null`	否	关联资源列表

显示 entities — 每项的字段

字段	类型	必填	说明
`type`	`string`	是	类型；取值：`"query"`, `"dashboard"`, `"notebook"`, `"table"`, `"field"`, `"function"`, `"contract"`, `"chain"`, `"schedule"`, `"page"`, `"issue"`
`id`	`string`	是	对象的唯一 ID；1–255 字符
`raw`	`string`	是	正文中用于引用资源的原始文本；1–255 字符

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`dashboard_id`	`string` / `null`	Dashboard ID
`type`	`string`	类型；取值：`"text"`, `"visualization"`, `"parameter"`
`visualization_id`	`string` / `null`	可视化配置 ID
`text_content`	`string` / `null`	Markdown 文字内容
`options`	`object`	展示配置；写入只接受 {} 或 null。图表配置使用 Visualization，位置使用 Dashboard 布局
`entities`	`object[]`	关联资源列表
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`entities_map`	`object`	按资源类型和 ID 索引的关联内容
`visualization`	`object` / `null`	引用的可视化；不可读或已删除时为 null
`parameters`	`object[]` / `null`	参数定义
`code`	`string` / `null`	执行代码；Query 使用 SQL
`space_entity`	`object` / `null`	所属 Space 的信息
`query_name`	`string` / `null`	引用 Query 的名称；不可用时为 null

显示 entities — 每项的字段

字段	类型	说明
`type`	`string`	类型；取值：`"query"`, `"dashboard"`, `"notebook"`, `"table"`, `"field"`, `"function"`, `"contract"`, `"chain"`, `"schedule"`, `"page"`, `"issue"`
`id`	`string`	对象的唯一 ID
`raw`	`string`	正文中用于引用资源的原始文本

显示 entities_map — 按资源类型

显示按资源 ID 查看字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 visualization — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`query_id`	`string` / `null`	Query ID
`name`	`string` / `null`	名称
`type`	`string`	类型；取值：`"table"`, `"chart"`, `"counter"`, `"pivot"`
`options`	`object` / `null`	按 options.type 选择配置；{} 或 null 清空配置。未指定展示列时由网页按结果列选择；嵌套字段使用 snake_case，未知字段会被拒绝
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒

显示 options — 子字段

表格
柱状图 / 折线图 / 面积图 / 散点图
饼图
计数器

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"table"`
`columns`	`object` / `null`	以结果列名为键的展示配置
`export_options`	`object` / `null`	结果导出配置

显示 columns — 每个值的字段

字段	类型	说明
`name`	`string` / `null`	名称
`title`	`string` / `null`	显示标题
`align`	`string` / `null`	单元格对齐方式；取值：`"left"`, `"center"`, `"right"`
`type`	`string` / `null`	normal 为普通单元格，progress 为进度条；取值：`"normal"`, `"progress"`
`format`	`string` / `null`	数值或日期格式串
`hide`	`boolean` / `null`	是否隐藏该列
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`url_template`	`string` / `null`	单元格链接模板，{value} 替换为单元格值

显示 export_options — 子字段

字段	类型	说明
`enabled`	`boolean` / `null`	是否启用导出
`formats`	`string[]` / `null`	允许的导出格式
`filename`	`string` / `null`	导出文件名
`include_all_data`	`boolean` / `null`	是否导出全部数据

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`x_column`	`string` / `null`	横轴使用的结果列名
`y_columns`	`string[]` / `null`	数值列名，每列一个系列；不能重复
`x_axis`	`object` / `null`	横轴配置
`y_axis`	`object` / `null`	左侧纵轴配置
`right_y_axis`	`object` / `null`	右侧纵轴配置
`legend`	`object` / `null`	图例配置
`series`	`object` / `null`	以 y 列名为键；group_by 启用时以分组值为键
`enable_stacking`	`boolean` / `null`	是否堆叠系列
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`show_total_in_tooltip`	`boolean` / `null`	是否在提示框中显示合计
`group_by`	`string` / `null`	按此列取值分组；只使用 y_columns 的第一列，空字符串取消分组
`normalize_to_percentage`	`boolean` / `null`	将同一横轴值下的分组归一到 100%
`when_duplicate_x`	`string` / `null`	横轴值重复时：first 取第一行，all 保留全部，sum 求和；取值：`"first"`, `"all"`, `"sum"`
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 x_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 right_y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 series — 每个值的字段

字段	类型	说明
`title`	`string` / `null`	图例和提示框名称；省略时使用系列名
`type`	`string` / `null`	系列图形类型；省略时沿用 options.type；取值：`"bar"`, `"line"`, `"area"`, `"scatter"`
`color`	`string` / `null`	CSS 颜色值
`is_right`	`boolean` / `null`	是否使用右轴，需启用 y_axis.enable_right_axis
`connect_nulls`	`boolean` / `null`	折线是否跨过空值连接
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值
`silent`	`boolean` / `null`	是否禁用系列交互

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"pie"`
`label_column`	`string` / `null`	饼图分类列名
`value_column`	`string` / `null`	饼图数值列名
`legend`	`object` / `null`	图例配置
`show_data_labels`	`boolean` / `null`	是否显示数据标签
`y_axis`	`object` / `null`	仅使用 label_format 设置数值格式
`values_options`	`object` / `null`	键为分类值，值为该扇区的颜色配置
`series_title`	`string` / `null`	提示框中的系列名
`show_legend`	`boolean` / `null`	旧版图例开关；使用 legend.show

显示 legend — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示；图例省略时显示
`position`	`string` / `null`	图例位置；省略时自动安排；取值：`"top"`, `"right"`, `"bottom"`, `"left"`
`show_all`	`boolean` / `null`	饼图图例是否列出所有分类

显示 y_axis — 子字段

字段	类型	说明
`title`	`string` / `null`	显示标题
`tick_format`	`string` / `null`	刻度格式串，如 YYYY-MM-DD
`label_format`	`string` / `null`	提示框或数据标签的格式串
`type`	`string` / `null`	横轴可自动按列类型推导；纵轴使用 linear 或 log；取值：`"linear"`, `"band"`, `"time"`, `"log"`
`include_zero`	`boolean` / `null`	纵轴是否包含 0；省略时包含
`min`	`number` / `null`	坐标轴最小值；不能大于 max
`max`	`number` / `null`	坐标轴最大值
`sort_values`	`boolean` / `null`	横轴是否排序；省略时排序
`reverse_values`	`boolean` / `null`	是否反转坐标轴顺序
`enable_right_axis`	`boolean` / `null`	是否启用右轴，配合系列的 is_right 使用
`auto_tick`	`boolean` / `null`	是否自动安排刻度
`nice`	`boolean` / `null`	是否将坐标轴范围调整到整齐的刻度
`asymmetric_equal_domain`	`boolean` / `null`	坐标范围相同时是否采用非对称扩展
`num_ticks`	`integer` / `null`	刻度数量
`width`	`number` / `null`	坐标轴宽度
`reference_lines`	`object[]` / `null`	坐标轴参考线
`zones`	`object[]` / `null`	坐标轴标记区域

显示 reference_lines — 每项的字段

字段	类型	说明
`value`	`number` / `string`	参考线位置；时间轴可用日期字符串
`stroke`	`string`	参考线颜色，CSS 颜色值
`tick`	`object` / `null`	参考线刻度配置

显示 tick — 子字段

字段	类型	说明
`show`	`boolean` / `null`	是否显示参考线刻度

显示 zones — 每项的字段

字段	类型	说明
`from`	`number` / `string` / `null`	标记区域的起点
`to`	`number` / `string` / `null`	标记区域的终点
`color`	`string` / `null`	CSS 颜色值
`fill_gradient`	`string[]` / `null`	渐变起止颜色，恰好两个 CSS 颜色值

显示 values_options — 每个值的字段

字段	类型	说明
`color`	`string`	CSS 颜色值

字段	类型	说明
`title`	`string` / `null`	显示标题
`description`	`string` / `null`	用途说明
`type`	`string`	类型；固定为 `"counter"`
`column_name`	`string` / `null`	计数器展示的数值列名
`row_number`	`integer` / `null`	结果行下标，从 0 开始，省略时为 0
`prefix`	`string` / `null`	数值前缀
`suffix`	`string` / `null`	数值后缀
`decimals`	`integer` / `null`	小数位数；省略时按列类型格式化
`colored_positive`	`boolean` / `null`	是否为正值着色
`colored_negative`	`boolean` / `null`	是否为负值着色
`label`	`string` / `null`	说明文字或展示分类

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string`	名称
`type`	`string`	参数逻辑类型，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`string` / `null`	参数的显示 ID，随定义保存
`order`	`integer` / `null`	须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/dashboard/widget/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000015",
  "text_content": "# Asset overview"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "01900000000070008000000000000015",
    "dashboard_id": "01900000000070008000000000000003",
    "type": "text",
    "visualization_id": null,
    "text_content": "# Asset overview",
    "options": {},
    "entities": [],
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "entities_map": {}
  }
}

schedule

调用账户须拥有调度所在 Space，调用用户须有该 Space 的写权限。目标内容须属于同一账户。

GET /v1/schedule — 读取调度

按 id 或完整的 space、content_type、content_id 组合查找，不能混用。按内容查找时返回最近更新的调度，无匹配时为 null。Method: GET
Path: /v1/schedule参数

字段	类型	必填	说明
`id`	`string` / `null`	否	对象的唯一 ID；1–255 字符
`space`	`string` / `null`	否	Space ID；1–64 字符
`content_type`	`string` / `null`	否	目标内容类型；取值：`"query"`, `"dashboard"`, `"notebook"`
`content_id`	`string` / `null`	否	目标内容 ID；1–255 字符

返回字段按内容查找无匹配调度时，data 为 null。

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`account_id`	`string`	账户 ID
`enabled`	`boolean` / `null`	调度是否启用
`next_run_at`	`number` / `null`	下次执行时间，Unix 秒；无计划时为 null
`runtime_status`	`string` / `null`	持续运行状态；定时调度为 null；取值：`"running"`, `"stopping"`, `"starting"`, `"stopped"`
`instance`	`object` / `null`	持续运行调度的实例摘要
`recent_runs`	`object[]`	最近的调度执行记录
`content`	`object` / `null`	调度目标的内容摘要；不可用时为 null

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 instance — 子字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`status`	`string` / `null`	状态
`display_status`	`string`	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`, `"starting"`
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`exit_message`	`string` / `null`	退出原因；运行中为 null
`created_at`	`number` / `null`	创建时间，Unix 秒
`exited_at`	`number` / `null`	退出时间，Unix 秒；运行中为 null

显示 recent_runs — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`status`	`string`	状态
`display_status`	`string`	实例展示状态
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`planned_at`	`number` / `null`	计划执行时间，Unix 秒
`started_at`	`number` / `null`	开始时间，Unix 秒；尚未开始时为 null
`finished_at`	`number` / `null`	完成时间，Unix 秒；未结束时为 null
`message`	`string` / `null`	说明或错误消息
`instance_id`	`string` / `null`	Notebook 执行实例 ID

显示 content — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`language`	`string` / `null`	代码语言
`parameters`	`object[]`	参数定义
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl --get https://api.chaintable.com/v1/schedule \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode id=0190000000007000800000000000000a

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "0190000000007000800000000000000a",
    "space": "demo",
    "content_type": "notebook",
    "content_id": "01900000000070008000000000000002",
    "name": "Hourly message",
    "mode": "crontab",
    "cron": "0 * * * *",
    "arguments": [],
    "max_cpu": 100,
    "max_memory": 4294967296,
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "account_id": "0190000000007000800000000000000b",
    "enabled": true,
    "next_run_at": 1788224400.0,
    "runtime_status": null,
    "instance": null,
    "recent_runs": [],
    "content": {
      "id": "01900000000070008000000000000002",
      "name": "print_message",
      "space": "demo",
      "language": "python",
      "parameters": [],
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "space_entity": {
        "id": "demo",
        "description": "Example resources",
        "account_id": "0190000000007000800000000000000b",
        "status": "active",
        "visibility": "public",
        "dep_count": 0,
        "content_count": 6,
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "account": {
          "id": "0190000000007000800000000000000b",
          "type": "org",
          "slug": "example-team",
          "display_name": "Example team",
          "avatar_url": null,
          "avatar_thumbnail_url": null
        }
      }
    }
  }
}

POST /v1/schedule/create — 创建调度

创建后立即启用。crontab 模式须提供 Cron 表达式；perpetual 仅用于 Notebook。Notebook 调度须提供有效的 CPU 和内存组合。Method: POST
Path: /v1/schedule/create参数

字段	类型	必填	说明
`content_type`	`string`	是	目标内容类型；取值：`"query"`, `"dashboard"`, `"notebook"`
`content_id`	`string`	是	目标内容 ID；32–32 字符；格式：`^[0-9a-f]{32}$`
`name`	`string` / `null`	否	名称；≤ 128 字符
`mode`	`string`	否	调度模式；取值：`"crontab"`, `"perpetual"`；默认 `"crontab"`
`cron`	`string` / `null`	否	Cron 表达式；≤ 128 字符
`arguments`	`object[]`	否	本次执行的参数值
`max_cpu`	`integer` / `null`	否	CPU 配额，100 表示 1 vCPU；> 0
`max_memory`	`integer` / `null`	否	内存配额，单位为字节；> 0
`space`	`string`	是	Space ID；1–64 字符

显示 arguments — 每项的字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值
`name`	`string` / `null`	否	匹配的形参名称
`order`	`integer` / `null`	否	须全部省略或从 0 连续编号；按此顺序匹配参数；≥ 0

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`account_id`	`string`	账户 ID
`enabled`	`boolean` / `null`	调度是否启用
`next_run_at`	`number` / `null`	下次执行时间，Unix 秒；无计划时为 null
`runtime_status`	`string` / `null`	持续运行状态；定时调度为 null；取值：`"running"`, `"stopping"`, `"starting"`, `"stopped"`
`instance`	`object` / `null`	持续运行调度的实例摘要
`recent_runs`	`object[]`	最近的调度执行记录
`content`	`object` / `null`	调度目标的内容摘要；不可用时为 null

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 instance — 子字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`status`	`string` / `null`	状态
`display_status`	`string`	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`, `"starting"`
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`exit_message`	`string` / `null`	退出原因；运行中为 null
`created_at`	`number` / `null`	创建时间，Unix 秒
`exited_at`	`number` / `null`	退出时间，Unix 秒；运行中为 null

显示 recent_runs — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`status`	`string`	状态
`display_status`	`string`	实例展示状态
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`planned_at`	`number` / `null`	计划执行时间，Unix 秒
`started_at`	`number` / `null`	开始时间，Unix 秒；尚未开始时为 null
`finished_at`	`number` / `null`	完成时间，Unix 秒；未结束时为 null
`message`	`string` / `null`	说明或错误消息
`instance_id`	`string` / `null`	Notebook 执行实例 ID

显示 content — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`language`	`string` / `null`	代码语言
`parameters`	`object[]`	参数定义
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/schedule/create \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "space": "demo",
  "content_type": "notebook",
  "content_id": "01900000000070008000000000000002",
  "name": "Hourly message",
  "mode": "crontab",
  "cron": "0 * * * *",
  "arguments": [],
  "max_cpu": 100,
  "max_memory": 4294967296
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "0190000000007000800000000000000a",
    "space": "demo",
    "content_type": "notebook",
    "content_id": "01900000000070008000000000000002",
    "name": "Hourly message",
    "mode": "crontab",
    "cron": "0 * * * *",
    "arguments": [],
    "max_cpu": 100,
    "max_memory": 4294967296,
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "account_id": "0190000000007000800000000000000b",
    "enabled": true,
    "next_run_at": 1788224400.0,
    "runtime_status": null,
    "instance": null,
    "recent_runs": [],
    "content": {
      "id": "01900000000070008000000000000002",
      "name": "print_message",
      "space": "demo",
      "language": "python",
      "parameters": [],
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "space_entity": {
        "id": "demo",
        "description": "Example resources",
        "account_id": "0190000000007000800000000000000b",
        "status": "active",
        "visibility": "public",
        "dep_count": 0,
        "content_count": 6,
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "account": {
          "id": "0190000000007000800000000000000b",
          "type": "org",
          "slug": "example-team",
          "display_name": "Example team",
          "avatar_url": null,
          "avatar_thumbnail_url": null
        }
      }
    }
  }
}

POST /v1/schedule/delete — 删除调度

删除调度。Method: POST
Path: /v1/schedule/delete参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/schedule/delete \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "0190000000007000800000000000000a"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/schedule/disable — 停用调度

停用调度。Method: POST
Path: /v1/schedule/disable参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/schedule/disable \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "0190000000007000800000000000000a"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/schedule/enable — 启用调度

启用调度。Method: POST
Path: /v1/schedule/enable参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/schedule/enable \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "0190000000007000800000000000000a"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

GET /v1/schedule/list — 列出调度

列出调度。Method: GET
Path: /v1/schedule/list参数

字段	类型	必填	说明
`start`	`integer`	否	分页起始位置，从 0 开始；≥ 0；默认 `0`
`limit`	`integer`	否	最多返回条数；≥ 1；≤ 100；默认 `20`
`order_by`	`string`	否	排序字段；取值：`"id"`, `"name"`, `"created_at"`, `"updated_at"`；默认 `"updated_at"`
`direction`	`string`	否	排序方向；取值：`"asc"`, `"desc"`；默认 `"desc"`
`space`	`string`	是	按 Space 筛选；省略时列出可见 Space 内的资源；1–64 字符
`content_type`	`string` / `null`	否	目标内容类型；取值：`"query"`, `"dashboard"`, `"notebook"`
`content_id`	`string` / `null`	否	目标内容 ID；1–255 字符
`mode`	`string` / `null`	否	调度模式；取值：`"crontab"`, `"perpetual"`
`keyword`	`string` / `null`	否	搜索关键词；≤ 128 字符

返回字段

字段	类型	说明
`start`	`integer`	分页起始位置，从 0 开始
`limit`	`integer`	最多返回条数
`items`	`object[]`	当前页的条目
`total_count`	`integer`	符合筛选条件的总数

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`account_id`	`string`	账户 ID
`enabled`	`boolean` / `null`	调度是否启用
`next_run_at`	`number` / `null`	下次执行时间，Unix 秒；无计划时为 null
`runtime_status`	`string` / `null`	持续运行状态；定时调度为 null；取值：`"running"`, `"stopping"`, `"starting"`, `"stopped"`
`instance`	`object` / `null`	持续运行调度的实例摘要
`recent_runs`	`object[]`	最近的调度执行记录
`content`	`object` / `null`	调度目标的内容摘要；不可用时为 null

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 instance — 子字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`status`	`string` / `null`	状态
`display_status`	`string`	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`, `"starting"`
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`exit_message`	`string` / `null`	退出原因；运行中为 null
`created_at`	`number` / `null`	创建时间，Unix 秒
`exited_at`	`number` / `null`	退出时间，Unix 秒；运行中为 null

显示 recent_runs — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`status`	`string`	状态
`display_status`	`string`	实例展示状态
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`planned_at`	`number` / `null`	计划执行时间，Unix 秒
`started_at`	`number` / `null`	开始时间，Unix 秒；尚未开始时为 null
`finished_at`	`number` / `null`	完成时间，Unix 秒；未结束时为 null
`message`	`string` / `null`	说明或错误消息
`instance_id`	`string` / `null`	Notebook 执行实例 ID

显示 content — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`language`	`string` / `null`	代码语言
`parameters`	`object[]`	参数定义
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl --get https://api.chaintable.com/v1/schedule/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  --data-urlencode space=demo \
  --data-urlencode limit=10

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "0190000000007000800000000000000a",
        "space": "demo",
        "content_type": "notebook",
        "content_id": "01900000000070008000000000000002",
        "name": "Hourly message",
        "mode": "crontab",
        "cron": "0 * * * *",
        "arguments": [],
        "max_cpu": 100,
        "max_memory": 4294967296,
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "space_entity": {
          "id": "demo",
          "description": "Example resources",
          "account_id": "0190000000007000800000000000000b",
          "status": "active",
          "visibility": "public",
          "dep_count": 0,
          "content_count": 6,
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "account": {
            "id": "0190000000007000800000000000000b",
            "type": "org",
            "slug": "example-team",
            "display_name": "Example team",
            "avatar_url": null,
            "avatar_thumbnail_url": null
          }
        },
        "account_id": "0190000000007000800000000000000b",
        "enabled": true,
        "next_run_at": 1788224400.0,
        "runtime_status": null,
        "instance": null,
        "recent_runs": [],
        "content": {
          "id": "01900000000070008000000000000002",
          "name": "print_message",
          "space": "demo",
          "language": "python",
          "parameters": [],
          "created_at": 1788220800.0,
          "updated_at": 1788220800.0,
          "space_entity": {
            "id": "demo",
            "description": "Example resources",
            "account_id": "0190000000007000800000000000000b",
            "status": "active",
            "visibility": "public",
            "dep_count": 0,
            "content_count": 6,
            "created_at": 1788220800.0,
            "updated_at": 1788220800.0,
            "account": {
              "id": "0190000000007000800000000000000b",
              "type": "org",
              "slug": "example-team",
              "display_name": "Example team",
              "avatar_url": null,
              "avatar_thumbnail_url": null
            }
          }
        }
      }
    ],
    "total_count": 1,
    "start": 0,
    "limit": 10
  }
}

POST /v1/schedule/restart — 重启持续运行调度

仅用于 perpetual；其他模式返回 409。Method: POST
Path: /v1/schedule/restart参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符

返回字段

字段	类型	说明
`data`	`null`	操作完成，无返回数据

请求示例

curl https://api.chaintable.com/v1/schedule/restart \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "01900000000070008000000000000019"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": null
}

POST /v1/schedule/update — 更新调度

更新执行配置，不能改变目标内容、Space 或调度模式。持续运行调度的配置变更不会自动重启实例，需调用重启接口。修改计算规格时须同时提供 max_cpu 和 max_memory。Method: POST
Path: /v1/schedule/update参数

字段	类型	必填	说明
`id`	`string`	是	对象的唯一 ID；1–255 字符
`name`	`string` / `null`	否	名称；≤ 128 字符
`cron`	`string` / `null`	否	Cron 表达式；≤ 128 字符
`arguments`	`object[]`	否	本次执行的参数值
`max_cpu`	`integer`	否	CPU 配额，100 表示 1 vCPU；> 0
`max_memory`	`integer`	否	内存配额，单位为字节；> 0

显示 arguments — 每项的字段

字段	类型	必填	说明
`value`	`JSON`	是	参数值
`name`	`string` / `null`	否	匹配的形参名称
`order`	`integer` / `null`	否	须全部省略或从 0 连续编号；按此顺序匹配参数；≥ 0

返回字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`content_type`	`string` / `null`	目标内容类型
`content_id`	`string` / `null`	目标内容 ID
`cron`	`string` / `null`	Cron 表达式
`arguments`	`object[]`	本次执行的参数值
`name`	`string` / `null`	名称
`mode`	`string` / `null`	调度模式
`max_cpu`	`integer` / `null`	CPU 配额，100 表示 1 vCPU
`max_memory`	`integer` / `null`	内存配额，单位为字节
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`space_entity`	`object` / `null`	所属 Space 的信息
`account_id`	`string`	账户 ID
`enabled`	`boolean` / `null`	调度是否启用
`next_run_at`	`number` / `null`	下次执行时间，Unix 秒；无计划时为 null
`runtime_status`	`string` / `null`	持续运行状态；定时调度为 null；取值：`"running"`, `"stopping"`, `"starting"`, `"stopped"`
`instance`	`object` / `null`	持续运行调度的实例摘要
`recent_runs`	`object[]`	最近的调度执行记录
`content`	`object` / `null`	调度目标的内容摘要；不可用时为 null

显示 arguments — 每项的字段

字段	类型	说明
`value`	`JSON`	参数值
`name`	`string` / `null`	匹配的形参名称
`order`	`integer` / `null`	须全部省略或从 0 连续编号；按此顺序匹配参数

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

显示 instance — 子字段

字段	类型	说明
`id`	`string` / `null`	对象的唯一 ID
`status`	`string` / `null`	状态
`display_status`	`string`	实例展示状态；取值：`"running"`, `"succeeded"`, `"failed"`, `"canceled"`, `"starting"`
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`exit_message`	`string` / `null`	退出原因；运行中为 null
`created_at`	`number` / `null`	创建时间，Unix 秒
`exited_at`	`number` / `null`	退出时间，Unix 秒；运行中为 null

显示 recent_runs — 每项的字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`status`	`string`	状态
`display_status`	`string`	实例展示状态
`exit_code`	`integer` / `null`	退出码；运行中为 null，0 为成功
`planned_at`	`number` / `null`	计划执行时间，Unix 秒
`started_at`	`number` / `null`	开始时间，Unix 秒；尚未开始时为 null
`finished_at`	`number` / `null`	完成时间，Unix 秒；未结束时为 null
`message`	`string` / `null`	说明或错误消息
`instance_id`	`string` / `null`	Notebook 执行实例 ID

显示 content — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`space`	`string`	Space ID
`name`	`string` / `null`	名称
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`language`	`string` / `null`	代码语言
`parameters`	`object[]`	参数定义
`space_entity`	`object` / `null`	所属 Space 的信息

显示 parameters — 每项的字段

字段	类型	说明
`name`	`string` / `null`	形参名称
`type`	`string`	参数逻辑类型，如 INT、STRING 或 ADDRESS，见数据类型
`options`	`JSON[]` / `null`	参数的可选值列表
`default`	`object` / `null`	默认参数值
`id`	`JSON` / `null`	参数显示 ID；响应中由服务生成
`order`	`integer` / `null`	参数顺序；Function 中须全部省略或从 0 连续编号

显示 default — 子字段

字段	类型	说明
`value`	`JSON`	参数值

显示 space_entity — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`description`	`string` / `null`	用途说明
`account_id`	`string`	账户 ID
`status`	`string`	状态
`visibility`	`string`	可见范围：public、org 或 private
`dep_count`	`integer`	依赖计数
`content_count`	`integer`	内容条目数
`created_at`	`number`	创建时间，Unix 秒
`updated_at`	`number`	最后更新时间，Unix 秒
`account`	`object` / `null`	账户信息

显示 account — 子字段

字段	类型	说明
`id`	`string`	对象的唯一 ID
`type`	`string`	账户类型：personal 或 org
`slug`	`string` / `null`	账户名称，用于展示和 URL
`display_name`	`string` / `null`	账户显示名称
`avatar_url`	`string` / `null`	头像 URL
`avatar_thumbnail_url`	`string` / `null`	头像缩略图 URL

请求示例

curl https://api.chaintable.com/v1/schedule/update \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": "0190000000007000800000000000000a",
  "cron": "*/30 * * * *"
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "0190000000007000800000000000000a",
    "space": "demo",
    "content_type": "notebook",
    "content_id": "01900000000070008000000000000002",
    "name": "Hourly message",
    "mode": "crontab",
    "cron": "*/30 * * * *",
    "arguments": [],
    "max_cpu": 100,
    "max_memory": 4294967296,
    "created_at": 1788220800.0,
    "updated_at": 1788220800.0,
    "space_entity": {
      "id": "demo",
      "description": "Example resources",
      "account_id": "0190000000007000800000000000000b",
      "status": "active",
      "visibility": "public",
      "dep_count": 0,
      "content_count": 6,
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "account": {
        "id": "0190000000007000800000000000000b",
        "type": "org",
        "slug": "example-team",
        "display_name": "Example team",
        "avatar_url": null,
        "avatar_thumbnail_url": null
      }
    },
    "account_id": "0190000000007000800000000000000b",
    "enabled": true,
    "next_run_at": 1788222600.0,
    "runtime_status": null,
    "instance": null,
    "recent_runs": [],
    "content": {
      "id": "01900000000070008000000000000002",
      "name": "print_message",
      "space": "demo",
      "language": "python",
      "parameters": [],
      "created_at": 1788220800.0,
      "updated_at": 1788220800.0,
      "space_entity": {
        "id": "demo",
        "description": "Example resources",
        "account_id": "0190000000007000800000000000000b",
        "status": "active",
        "visibility": "public",
        "dep_count": 0,
        "content_count": 6,
        "created_at": 1788220800.0,
        "updated_at": 1788220800.0,
        "account": {
          "id": "0190000000007000800000000000000b",
          "type": "org",
          "slug": "example-team",
          "display_name": "Example team",
          "avatar_url": null,
          "avatar_thumbnail_url": null
        }
      }
    }
  }
}

chain

GET /v1/chain/list — 列出支持的链

返回支持的链，items 不分页。Method: GET
Path: /v1/chain/list参数无请求参数。返回字段

字段	类型	说明
`items`	`object[]`	当前页的条目

显示 items — 每项的字段

字段	类型	说明
`id`	`string`	平台链标识，如 eth
`name`	`string`	名称
`avatar_url`	`string`	头像 URL
`chain_id`	`integer`	EIP-155 链编号，如以太坊为 1
`status`	`string`	链状态：supported、developing 或 deprecated

请求示例

curl https://api.chaintable.com/v1/chain/list \
  -H "Authorization: Bearer $CHAINTABLE_PERSONAL_ACCESS_TOKEN" \
  -H "X-Account-ID: $CHAINTABLE_ACCOUNT_ID"

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "eth",
        "name": "Ethereum",
        "avatar_url": "https://example.com/eth.png",
        "chain_id": 1,
        "status": "supported"
      }
    ]
  }
}

leafage

通过 Chaintable 读取 EVM 链上数据或模拟合约调用。下列 method 共用一个 JSON-RPC 请求入口。 HTTP method: POST
Path: /v1/leafage/{chain_id} 请求格式

字段	类型	必填	说明
`chain_id`	`integer`	是	路径参数，EIP-155 链编号，例如以太坊为 1

字段	类型	必填	说明
`jsonrpc`	`string`	是	JSON-RPC 版本；固定为 `"2.0"`
`id`	`integer` / `string` / `null`	否	JSON-RPC 请求 ID，用于匹配响应
`method`	`string`	是	Leafage 方法名
`params`	`JSON[]`	否	方法的位置参数

params 按各方法列出的顺序传值。? 表示可省略的尾部参数；需要指定后面的参数时，用 null 占位。 响应格式

字段	类型	说明
`jsonrpc`	`string`	JSON-RPC 版本；固定为 `"2.0"`
`id`	`JSON`	与请求对应的 JSON-RPC ID
`result`	`JSON`	上游服务返回的结果，与 error 二选一
`error`	`object`	上游服务返回的错误，与 result 二选一

显示 error — 子字段

字段	类型	说明
`code`	`integer`	上游 JSON-RPC 错误码
`message`	`string`	说明或错误消息
`data`	`JSON`	上游错误附带的数据，可能省略

blockIsValid — 检查区块是否有效

检查指定区块是否有效。Method: blockIsValid参数params: [block_id]

字段	类型	必填	说明
`block_id`	`string`	是	区块哈希

返回字段

字段	类型	说明
`result`	`boolean`	区块是否有效

请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "blockIsValid",
  "params": [
    "0xf5e1d15a3e380006bd271e73c8eeed75fafc3ae6942b16f63c21361079bba709"
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": true
  }
}

getLatestBlock — 读取最新区块

读取最新区块的信息。Method: getLatestBlock参数无参数，params 传 []。返回字段

字段	类型	说明
`result`	`object`	最新区块的信息

显示 result — 子字段

字段	类型	说明
`id`	`string`	区块哈希
`height`	`integer`	区块高度
`timestamp`	`integer`	区块时间，Unix 秒
`parent_id`	`string`	父区块哈希
`base_fee_per_gas`	`integer`	区块的基础 Gas 费
`miner`	`string`	区块生产者地址
`gas_limit`	`integer`	Gas 上限
`gas_used`	`integer`	已使用的 Gas

请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLatestBlock",
  "params": []
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "base_fee_per_gas": 102802309,
      "gas_limit": 60000000,
      "gas_used": 7510076,
      "height": 26154104,
      "id": "0xb66a4b6766bd638be6968689ce4e94d2685f4ef9b6d3374d2e1796365c55bdd0",
      "miner": "0x388c818ca8b9251b393131c08a736a67ccb19297",
      "parent_id": "0x3a3efad4b46701971a6df1f5d9255e8d0da0c908c7879158e1e81a8c1abf268f",
      "timestamp": 1791539891
    }
  }
}

getBlockById — 按哈希读取区块

根据区块哈希读取区块信息。Method: getBlockById参数params: [block_id]

字段	类型	必填	说明
`block_id`	`string`	是	区块哈希

返回字段

字段	类型	说明
`result`	`object`	指定区块的信息

显示 result — 子字段

字段	类型	说明
`id`	`string`	区块哈希
`height`	`integer`	区块高度
`timestamp`	`integer`	区块时间，Unix 秒
`parent_id`	`string`	父区块哈希
`base_fee_per_gas`	`integer`	区块的基础 Gas 费
`miner`	`string`	区块生产者地址
`gas_limit`	`integer`	Gas 上限
`gas_used`	`integer`	已使用的 Gas

请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlockById",
  "params": [
    "0xf5e1d15a3e380006bd271e73c8eeed75fafc3ae6942b16f63c21361079bba709"
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "base_fee_per_gas": 18191470273,
      "gas_limit": 30000000,
      "gas_used": 13952884,
      "height": 21000000,
      "id": "0xf5e1d15a3e380006bd271e73c8eeed75fafc3ae6942b16f63c21361079bba709",
      "miner": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5",
      "parent_id": "0x215f1fa046ff46999f1a91973d7cc39c6d4e7aa64d3de3a40d31591f543c3386",
      "timestamp": 1729345547
    }
  }
}

getBlockByHeight — 按高度读取区块

根据区块高度读取区块信息。Method: getBlockByHeight参数params: [block_height]

字段	类型	必填	说明
`block_height`	`integer`	是	区块高度，使用整数

返回字段

字段	类型	说明
`result`	`object`	指定高度的区块信息

显示 result — 子字段

字段	类型	说明
`id`	`string`	区块哈希
`height`	`integer`	区块高度
`timestamp`	`integer`	区块时间，Unix 秒
`parent_id`	`string`	父区块哈希
`base_fee_per_gas`	`integer`	区块的基础 Gas 费
`miner`	`string`	区块生产者地址
`gas_limit`	`integer`	Gas 上限
`gas_used`	`integer`	已使用的 Gas

请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlockByHeight",
  "params": [
    21000000
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "base_fee_per_gas": 18191470273,
      "gas_limit": 30000000,
      "gas_used": 13952884,
      "height": 21000000,
      "id": "0xf5e1d15a3e380006bd271e73c8eeed75fafc3ae6942b16f63c21361079bba709",
      "miner": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5",
      "parent_id": "0x215f1fa046ff46999f1a91973d7cc39c6d4e7aa64d3de3a40d31591f543c3386",
      "timestamp": 1729345547
    }
  }
}

getAddressBalance — 读取地址余额

读取地址的原生代币余额。Method: getAddressBalance参数params: [address, block_context?]

字段	类型	必填	说明
`address`	`string`	是	要查询的 EVM 地址
`block_context`	`object`	否	指定读取的状态；省略时读取最新状态

显示 block_context — 子字段

字段	类型	必填	说明
`block_id`	`string`	是	区块哈希、十六进制高度或 latest
`type`	`string`	是	Equals 严格读取指定区块；Contains 校验区块有效且非分叉后读取最新状态，否则报错；取值：`"Equals"`, `"Contains"`

返回字段

字段	类型	说明
`result`	`string`	原生代币余额，最小单位的十六进制 U256 字符串

请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getAddressBalance",
  "params": [
    "0x3333333333333333333333333333333333333333",
    {
      "block_id": "latest",
      "type": "Equals"
    }
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0xde0b6b3a7640000"
  }
}

getAddressNonce — 读取地址 nonce

读取地址的 nonce。Method: getAddressNonce参数params: [address, block_context?]

字段	类型	必填	说明
`address`	`string`	是	要查询的 EVM 地址
`block_context`	`object`	否	指定读取的状态；省略时读取最新状态

显示 block_context — 子字段

字段	类型	必填	说明
`block_id`	`string`	是	区块哈希、十六进制高度或 latest
`type`	`string`	是	Equals 严格读取指定区块；Contains 校验区块有效且非分叉后读取最新状态，否则报错；取值：`"Equals"`, `"Contains"`

返回字段

字段	类型	说明
`result`	`string`	地址 nonce，十六进制 U256 字符串

请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getAddressNonce",
  "params": [
    "0x3333333333333333333333333333333333333333",
    {
      "block_id": "latest",
      "type": "Equals"
    }
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x2a"
  }
}

getAddressCode — 读取合约代码

读取指定地址的合约字节码。Method: getAddressCode参数params: [address, block_context?]

字段	类型	必填	说明
`address`	`string`	是	要查询的 EVM 地址
`block_context`	`object`	否	指定读取的状态；省略时读取最新状态

显示 block_context — 子字段

字段	类型	必填	说明
`block_id`	`string`	是	区块哈希、十六进制高度或 latest
`type`	`string`	是	Equals 严格读取指定区块；Contains 校验区块有效且非分叉后读取最新状态，否则报错；取值：`"Equals"`, `"Contains"`

返回字段

字段	类型	说明
`result`	`string`	合约字节码，十六进制字符串；没有代码时为 0x

请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getAddressCode",
  "params": [
    "0x3333333333333333333333333333333333333333",
    {
      "block_id": "latest",
      "type": "Equals"
    }
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x"
  }
}

getStorageAt — 读取存储槽

读取合约指定存储槽中的值。Method: getStorageAt参数params: [address, position, block_context?]

字段	类型	必填	说明
`address`	`string`	是	要查询的 EVM 地址
`position`	`string`	是	存储槽位置，十六进制值
`block_context`	`object`	否	指定读取的状态；省略时读取最新状态

显示 block_context — 子字段

字段	类型	必填	说明
`block_id`	`string`	是	区块哈希、十六进制高度或 latest
`type`	`string`	是	Equals 严格读取指定区块；Contains 校验区块有效且非分叉后读取最新状态，否则报错；取值：`"Equals"`, `"Contains"`

返回字段

字段	类型	说明
`result`	`string`	存储槽值，十六进制字符串

请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getStorageAt",
  "params": [
    "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "0x1",
    {
      "block_id": "latest",
      "type": "Equals"
    }
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x0000000000000000000000000000000000000000000000000000000000000000"
  }
}

contractMultiCall — 批量调用合约

批量模拟合约调用，按调用顺序返回结果。区块环境和账户状态覆盖只用于本次模拟，不改变链上状态。Method: contractMultiCall参数params: [calls, block_context?, block_overrides?, state_overrides?, fast_fail?, use_parallel?, disable_cache?]

字段	类型	必填	说明
`calls`	`object[]`	是	合约调用列表，每项是一条模拟调用
`block_context`	`object`	否	指定读取的状态；省略时读取最新状态
`block_overrides`	`object`	否	覆盖模拟执行的区块环境
`state_overrides`	`object`	否	以 EVM 地址为键的账户状态覆盖
`fast_fail`	`boolean`	否	任一调用失败时提前终止
`use_parallel`	`boolean`	否	是否并行调用
`disable_cache`	`boolean`	否	是否跳过缓存

显示 calls — 每项的字段

字段	类型	必填	说明
`from`	`string` / `null`	否	模拟调用者的 EVM 地址
`to`	`string` / `null`	否	调用目标的 EVM 地址
`gas`	`string` / `null`	否	Gas 上限，十六进制数量
`gasPrice`	`string` / `null`	否	Gas 单价，十六进制数量
`maxFeePerGas`	`string` / `null`	否	每单位 Gas 的费用上限，十六进制数量
`maxPriorityFeePerGas`	`string` / `null`	否	优先费上限，十六进制数量
`value`	`string` / `null`	否	调用携带的原生代币值，最小单位的十六进制数量
`nonce`	`string` / `null`	否	Nonce，十六进制数量
`data`	`string` / `null`	否	input 的兼容字段；推荐使用 input
`input`	`string` / `null`	否	十六进制调用数据
`chainId`	`string` / `null`	否	EIP-155 链编号，十六进制数量
`maxFeePerBlobGas`	`string` / `null`	否	Blob Gas 费用上限，十六进制数量
`accessList`	`object[]` / `null`	否	预先声明的地址和存储槽
`blobVersionedHashes`	`string[]`	否	Blob 的版本化哈希数组
`blobs`	`string[]`	否	Blob 数据数组，十六进制字节
`commitments`	`string[]`	否	Blob KZG commitment 数组，十六进制字节
`proofs`	`string[]`	否	Blob KZG proof 数组，十六进制字节

显示 accessList — 每项的字段

字段	类型	必填	说明
`address`	`string`	是	EVM 地址
`storageKeys`	`string[]`	是	存储槽列表，每项为 32 字节十六进制值

显示 block_context — 子字段

字段	类型	必填	说明
`block_id`	`string`	是	区块哈希、十六进制高度或 latest
`type`	`string`	是	Equals 严格读取指定区块；Contains 校验区块有效且非分叉后读取最新状态，否则报错；取值：`"Equals"`, `"Contains"`

显示 block_overrides — 子字段

字段	类型	必填	说明
`number`	`string` / `null`	否	覆盖的区块高度，十六进制数量
`difficulty`	`string` / `null`	否	覆盖的难度，十六进制数量；合并后的调用不生效
`time`	`string` / `null`	否	覆盖的区块时间，Unix 秒的十六进制数量
`gasLimit`	`string` / `null`	否	覆盖的区块 Gas 上限，十六进制数量
`feeRecipient`	`string` / `null`	否	覆盖的费用接收地址
`prevRandao`	`string` / `null`	否	覆盖的随机值，32 字节十六进制值
`baseFeePerGas`	`string` / `null`	否	覆盖的基础费，十六进制数量
`blobBaseFee`	`string` / `null`	否	覆盖的 Blob 基础费，十六进制数量

显示 state_overrides — 每个值的字段

字段	类型	必填	说明
`balance`	`string` / `null`	否	覆盖的原生代币余额，最小单位的十六进制数量
`nonce`	`string` / `null`	否	Nonce，十六进制数量
`code`	`string` / `null`	否	覆盖的合约字节码，十六进制字节
`movePrecompileToAddress`	`string` / `null`	否	将预编译合约移到此地址
`state`	`object`	否	完整替换存储；键和值均为 32 字节十六进制值
`stateDiff`	`object`	否	只覆盖指定存储槽；键和值均为 32 字节十六进制值

返回字段

字段	类型	说明
`result`	`object`	批量调用结果和执行信息

显示 result — 子字段

字段	类型	说明
`results`	`object[]`	按调用顺序排列的结果
`stats`	`object`	本次批量调用的执行信息

显示 results — 每项的字段

字段	类型	说明
`code`	`integer`	单次调用状态，0 表示成功；负值表示上游调用失败
`err`	`string`	调用错误消息；成功时为空字符串
`from_cache`	`boolean`	是否命中缓存
`result`	`string`	ABI 编码的返回数据，十六进制字节
`gas_used`	`integer`	已使用的 Gas
`time_cost`	`number`	上游报告的单次调用耗时

显示 stats — 子字段

字段	类型	说明
`block_num`	`integer`	执行所用区块高度
`block_hash`	`string`	执行所用区块哈希
`block_time`	`integer`	执行所用区块时间，Unix 秒
`success`	`boolean`	批量调用的整体成功状态
`cache_enabled`	`boolean`	是否启用了缓存

stats.success 表示批量调用的整体状态。results 中每项的 code 为 0 时表示成功，负值表示上游调用失败。请求示例

curl https://api.chaintable.com/v1/leafage/1 \
  -H "AccessKey: $CHAINTABLE_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "contractMultiCall",
  "params": [
    [
      {
        "to": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "input": "0x18160ddd"
      }
    ],
    {
      "block_id": "latest",
      "type": "Equals"
    }
  ]
}'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "results": [
        {
          "code": 0,
          "err": "",
          "from_cache": false,
          "result": "0x00000000000000000000000000000000000000000000000000000000000f4240",
          "gas_used": 2100,
          "time_cost": 0.003
        }
      ],
      "stats": {
        "block_num": 21000000,
        "block_hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
        "block_time": 1788220800,
        "success": true,
        "cache_enabled": true
      }
    }
  }
}

上游错误码 上游错误码与 Chaintable 外层 code 是两套状态，出现在 error.code 或批量调用的单项 code 中。

上游错误码	含义
`-32700`、`-32600`、`-32601`、`-32602`	JSON 无效、请求对象无效、方法不支持、参数无效
`-32603`	节点内部错误
`-39000`～`-39004`	合约 revert、Gas 耗尽、余额不足、nonce 错误、其他 EVM 执行失败
`-39005`	状态数据读取失败
`-39006`、`-39007`	找不到区块、区块 ID 无效
`-41000`	查询区块高度超出限制
`-41001`、`-41004`	请求过多、网关限速
`-41002`、`-41003`	网关超时、方法不允许

概览

快速开始

使用指南

参考

凭证访问范围

接口列表

space

table

function

notebook

query

dashboard

schedule

chain

leafage

​凭证访问范围

​接口列表

​space

​table

​function

​notebook

​query

​dashboard

​schedule

​chain

​leafage

凭证访问范围

接口列表

space

table

function

notebook

query

dashboard

schedule

chain

leafage