查询数据库

适用场景

当你需要按条件筛选、排序数据库中的页面记录时，使用这个接口。它返回的是页面记录列表，而不是数据库 schema。

接口信息

权限要求

需要 databases.read。

请求参数

{
  "filter": {
    "property": "Status",
    "select": {
      "equals": "Doing"
    }
  },
  "sorts": [
    {
      "property": "Status",
      "direction": "ascending"
    }
  ],
  "start_cursor": null,
  "page_size": 10
}

filter 用于定义“筛选什么数据”，sorts 用于定义“按什么顺序返回”。

响应结果

{
  "object": "list",
  "results": [
    {
      "object": "page",
      "id": "77777777-7777-4777-8777-777777777777",
      "page_type": "page"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

results 中返回的是数据库里的页面记录。每条记录仍然是 page 对象。

行为说明

• filter 可以嵌套 and / or。
• filter 也可以按 timestamp 或 property 做条件过滤，具体操作符由属性类型决定。
• sorts 中每个排序项只能写 property 或 timestamp，并且要带 direction。
• start_cursor 是分页游标，直接回传即可读取下一页。
• page_size 按统一分页规则处理，未传时默认 20，最大 100。
• 查询结果是页面记录，不会把数据库 schema 一并展开在结果里。

错误提示

• 400 validation_error：参数不正确。
• 400 unsupported_filter：过滤条件或属性类型不支持。
• 400 unsupported_sort：排序条件或属性类型不支持。
• 401 unauthorized：token 无效或已过期。
• 403 forbidden：缺少 databases.read 或无权访问数据库。
• 404 not_found：数据库不存在。

相关文档

前置阅读

• 获取数据库

下一步

• 创建页面

相关参考

• 页面属性模型
• 通用约定
• 错误码