AppBase 云控制台
浏览全部文档 · 16/37
AppBase 增强已进入 main

Row Aggregation

Database、Table、Column 与 Row

版本验证信息发布状态与验证 Commit
发布状态
已进入 main
后端验证 Commit
0363062a1c7ea08741975bb5ba0c3361663c9353

功能简介

Aggregation 在调用者可见的 Row 集合上执行 count、sum、avg、min、max 与 groupBy。它复用 Query 过滤和资源权限，并可在 transactionId 存在时把本事务内尚未提交的变化纳入统计。

当前支持范围

  • 行聚合（APPBASE_ENHANCED）：按行权限执行 count、sum、avg、min、max 与分组统计，并可把当前事务的未提交变更纳入结果。

适用场景

  • 按状态、地区或类别汇总业务数据。
  • 生成受用户权限约束的统计卡片。
  • 在事务提交前校验聚合结果。

前置条件

  • 目标字段类型适合对应聚合函数。
  • Table 已有支撑过滤条件的 Index。
  • 调用者拥有 rows.read，并能读取参与统计的 Row。

Console 操作路径

Console 当前没有独立 Aggregation 构建器。请在应用或服务端通过 Web/Server SDK、REST 调用；Console 可用于检查 Table、Columns、Indexes 与 Row Permissions。

SDK 示例

SDK · TypeScript
import { Client } from 'appbase-web-sdk';

const client = new Client()
  .setEndpoint('https://<APPBASE_HOST>/v1')
  .setProject('<PROJECT_ID>');
import { TablesDB, Query } from 'appbase-web-sdk';
const tables = new TablesDB(client);

const result = await tables.aggregateRows({
  databaseId: '<DATABASE_ID>',
  tableId: '<TABLE_ID>',
  select: ['status', 'count(*) AS total', 'sum(amount) AS amountTotal'],
  groupBy: ['status'],
  queries: [Query.equal('enabled', [true])]
});

REST 示例

REST · Bash
curl --get 'https://<APPBASE_HOST>/v1/tablesdb/<DATABASE_ID>/tables/<TABLE_ID>/aggregation' \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-JWT: <USER_JWT>' \
  --data-urlencode 'select[]=status' \
  --data-urlencode 'select[]=count(*) AS total' \
  --data-urlencode 'groupBy[]=status'

权限模型

接口接受 Admin、Session、JWT 或 API Key，并要求 rows.read/兼容 read Scope。服务端先确定可见 Row，再执行聚合；统计结果不应泄漏调用者无权读取的数据。

常见错误

现象处理建议
general_query_invalid移除分页、排序、cursor 或不支持的 select 组合，并检查字段类型。
database_timeout缩小过滤范围、补充 Index 或拆分聚合。
transaction_not_readytransactionId 已提交、回滚或过期。
403检查 rows.read 与 Table/Row read Permission。

当前限制

  • Pagination、ordering、cursor 与普通 select Query 不适用于该接口。
  • groupBy、select 表达式数量和事务变更规模有处理上限。
  • Aggregation 不是任意 SQL，也不开放数据库直连。

Appwrite 兼容说明

Query 与 Permission 概念保持兼容；聚合表达式、事务视图和响应模型属于 AppBase 增强。

AppBase 增强说明

AppBase 把聚合放在 Row 权限和 Schema 可见列边界内，并提供 aggregateRows SDK 方法。

发布状态和验证 Commit

origin/main 已核验。验证 Commit：0363062a1c7ea08741975bb5ba0c3361663c9353。

权威来源文件列表

  • backend-candidate:docs/products/v2.3.x/tablesdb/aggregation.md
  • backend-candidate:src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Tables/Aggregation/Get.php
  • backend-candidate:src/Appwrite/Platform/Modules/Databases/Services/RowAggregationService.php
  • backend-candidate:tests/e2e/Services/TablesDB/TablesDBAggregationTest.php

Appwrite taxonomy 仅作信息架构参考：https://appwrite.io/docs/products/databases。上游页面不是 AppBase 实现证据。

继续阅读