列表 API

本文档介绍如何使用 API 获取表格中的记录列表。

接口说明

获取表格中的记录列表，支持分页、排序和筛选。

请求方法

GET /api/v1/bases/{base_id}/tables/{table_name}/records

路径参数

参数	类型	描述
base_id	string	数据库 ID
table_name	string	表格名称

查询参数

参数	类型	描述	默认值
page	number	页码	1
limit	number	每页记录数	15
filters	string	筛选条件，格式说明	-
viewId	string	指定要返回的视图内容的 ID	-

请求头

x-bm-token: your_api_token

示例请求

基础查询

GET /api/bases/base123/tables/table456/records

分页查询

GET /api/bases/base123/tables/table456/records?page=2&limit=10

筛选查询

GET /api/bases/base123/tables/table456/records?filters=W1sid2hlcmUiLCBbImFnZSIsICI+IiwgMThdXV0=

响应格式

成功响应

{
  "current_page": 1,
  "data": [
    // records
  ],
  "per_page": 15,
  "total": 10,
  "last_page": 1,
  "count": 10
}

错误响应

{
  "message": "筛选条件格式不正确"
}

筛选条件

筛选条件是一段把条件数组使用 base64 编码后的字符串。 每个条件包含两个元素：操作符和操作对象。

操作符

操作符	描述
where	添加筛选条件
orderBy	添加排序条件
select	添加字段选择
with	添加关联字段
withCount	添加关联聚合

操作对象

操作对象	描述	示例
"="	等于	["where", ["age", "=", 18]]
"!="	不等于	["where", ["age", "!=", 18]]
">"	大于	["where", ["age", ">", 18]]
">="	大于等于	["where", ["age", ">=", 18]]
"<"	小于	["where", ["age", "<", 18]]
"<="	小于等于	["where", ["age", "<=", 18]]
"in"	在列表中	["where", ["status", "in", ["active", "pending"]]]
"notin"	不在列表中	["where", ["status", "notin", ["deleted"]]]
"like"	包含	["where", ["name", "like", "test"]]
"notlike"	不包含	["where", ["name", "notlike", "test"]]
"isNull"	为空	["where", ["description", "=", null]]
"isNotNull"	不为空	["where", ["description", "!=", null]]

base64 编码

// SELECT * FROM users
// WHERE age > 18;

const encoded = btoa(JSON.stringify([
  ["where", ["age", ">", 18]]
]));

条件

// SELECT * FROM users
// WHERE age > 18 AND status = 'active';

const encoded = btoa(JSON.stringify([
  ["where", ["age", ">", 18]],
  ["where", ["status", "=", "active"]]
]));

排序

// SELECT * FROM users
// ORDER BY age DESC;

const encoded = btoa(JSON.stringify([
  ["orderBy", ["age", "desc"]]
]));

字段选择

// SELECT name, age FROM users;

const encoded = btoa(JSON.stringify([
  ["select", ["name", "age"]]
]));

关联关系

const encoded = btoa(JSON.stringify([
  ["with", ["posts:id,title"]],
  ["with", ["comments"]],
]));

关联聚合

const encoded = btoa(JSON.stringify([
  ["withCount", ["posts"]]
]));

复合条件

可以使用多个条件组合：

const encoded = btoa(JSON.stringify([
  ["select", ["id", "title", "description"]],
  ["with", ["author:id,name"]],
  ["withCount", ["comments", [
    ["where", ["status", "=", "active"]]
  ]]],
  ["where", ["vote", ">", 10]],
  ["orderBy", ["votes", "desc"]]
]));

fetch(`/api/v1/bases/base123/tables/posts/records?filters=${encoded}`)

// response
{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "title": "Post 1",
      "description": "Description 1",
      "comments_count": 5,
      "author": {
        "id": 1,
        "name": "Alice"
      }
    }
    // ...
  ],
  "per_page": 15,
  "total": 10,
  "last_page": 1,
  "count": 10
}

注意事项

1. 每页最大记录数为 100
2. 复杂的筛选条件可能会影响查询性能
3. 关联字段的数据需要使用专门的查询参数获取