docs: clientDB tree

docs/uniCloud/clientdb.md

@@ -645,6 +645,175 @@ const db = uniCloud.database()
 }
 ```
 
+### 查询树形结构所有子节点@gettree
+
+自2020-12-26起，clientDB支持在get方法内传入getTree参数对包含父子关系的表查询返回树状结构数据。
+
+```js
+// get方法示例
+get({
+  getTree: {
+    limitLevel: 10, // 最大查询层级（不包含当前层级），可以省略默认10级，最大15最小1
+    startWith: 'parent_code==null'  // 第一层级条件，此初始条件可以省略，不传startWith时默认从最顶级开始查询
+  }
+})
+```
+
+以下面的表结构及数据为例
+
+```js
+// test-tree 表结构
+{
+  "bsonType": "object",
+  "required": [],
+  "properties": {
+    "parent_code": {
+      "bsonType": "string",
+      "description": "父级code",
+      "parentKey": "code", // 指定父子关系为：如果数据库记录A的code和数据库记录B的parent_code相等，则A是B的父级。一个表内只能有一个父子关系
+    },
+    "code": {
+      "bsonType": "string",
+      "description": "当前code
+    },
+    "name": {
+      "bsonType": "string",
+      "description": "名称"
+    }
+  }
+}
+```
+
+假设上述表有以下数据
+
+```js
+{
+  name: 'p1',
+  code: '1'
+}
+{
+  parent_code: '1',
+  name: 'c11',
+  code: '11'
+}
+{
+  parent_code: '1',
+  name: 'c12',
+  code: '12'
+}
+{
+  name: 'p2',
+  code: '2'
+}
+{
+  parent_code: '2',
+  name: 'c21',
+  code: '21'
+}
+{
+  parent_code: '2',
+  name: 'c22',
+  code: '22'
+}
+```
+
+以上面的表结构为例以下两种写法是等价的
+
+```js
+get({
+  getTree: {
+    limitLevel: 10,
+    startWith: 'parent_code==null'
+  }
+})
+
+get({
+  getTree: true
+})
+```
+
+如果要查询code为'1'的数据及其在树形结构所有的子节点，可以使用如下写法
+
+```js
+// 完整写法示例
+const res = await db.collection('opendb-china-cities')
+  .field('name as text,code as value')
+  .get({
+    getTree: {
+      startWith: 'code == "1"'
+    }
+  })
+  
+// 查询结果
+{
+  data: [{
+    text:'p1',
+    value:'1',
+    children:[{
+      text:'c11',
+      value:'11',
+      children: []
+    },{
+      text:'c12',
+      value:'12',
+      children: []
+    }]
+  }]
+}
+```
+
+**注意**
+
+- 目前不支持使用getTree的同时使用其他联表查询语法
+- 如果使用了where条件会对所有查询的节点生效
+- 不可一次查询量特别大的数据，比如一次性加载所有的省市区。推荐在菜单、部门选择等小数据量的场景下使用
+
+### 查询树形结构所有父节点@gettreepath
+
+自2020-12-26起，clientDB支持在get方法内传入getTreePath参数对包含父子关系的表查询返回树状结构数据某节点路径。
+
+```js
+// get方法示例
+get({
+  getTreePath: {
+    limitLevel: 10, // 最大查询层级（不包含当前层级），可以省略默认10级，最大15最小1
+    startWith: 'code=="22"'  // 第一层级条件，此初始条件不可以省略
+  }
+})
+```
+
+仍以上面getTree中的表结构和数据为例
+
+如果要查询code为'22'的数据的在树形结构中的路径可以使用下面的写法
+
+```js
+// 完整写法示例
+const res = await db.collection('opendb-china-cities')
+  .field('name as text,code as value')
+  .get({
+    getTreePath: {
+      startWith: 'code=="22"'
+    }
+  })
+  
+// 查询返回结果
+{
+  data: [{
+      text:'p2',
+      value:'2',
+      children:[{
+        text:'c22',
+        value:'22',
+      }]
+    }]
+}
+```
+
+**注意**
+
+- 目前不支持使用getTreePath的同时使用其他联表查询语法
+- 如果使用了where条件会对所有查询的节点生效
+
 ### 新增数据记录add
 
 获取到db的表对象后，通过`add`方法新增数据记录。

docs/uniCloud/schema.md

@@ -72,7 +72,8 @@ HBuilderX中运行前端项目，在控制台选择连接本地云函数，此
 |errorMessage|string|Object |当数据写入或更新时，校验数据合法性失败后，返回的错误提示|
 |defaultValue|string|Object|默认值|
 |forceDefaultValue|string|Object|强制默认值，不可通过clientDB的代码修改，常用于存放用户id、时间、客户端ip等固定值。具体参考下表的defaultValue|
-|foreignKey|String|关联字段。表示该字段的原始定义指向另一个表的某个字段，值的格式为`表名.字段名`，比如订单表的下单用户uid字段指向uni-id-users表的_id字段，那么值为`uni-id-users._id`。关联字段定义后可用于[联表查询](https://uniapp.dcloud.net.cn/uniCloud/database?id=lookup)，通过关联字段合成虚拟表，极大的简化了联表查询的复杂度|
+|foreignKey|String|关联字段。表示该字段的原始定义指向另一个表的某个字段，值的格式为`表名.字段名`，比如订单表的下单用户uid字段指向uni-id-users表的_id字段，那么值为`uni-id-users._id`。关联字段定义后可用于[联表查询](https://uniapp.dcloud.net.cn/uniCloud/clientdb?id=lookup)，通过关联字段合成虚拟表，极大的简化了联表查询的复杂度|
+|parentKey|String|同一个数据表内父级的字段。详情参考：[树状数据查询](https://uniapp.dcloud.net.cn/uniCloud/clientdb?id=gettree)|
 |permission|Object|数据库权限，控制什么角色可以对什么数据进行读/写，可控制表和字段，可设置where条件。见下文[详述](uniCloud/schema?id=permission)|
 |label|string|字段标题。生成前端表单代码时，渲染表单项前面的label标题|
 |group|string|分组id。生成前端表单代码时，多个字段对应的表单项可以合并显示在一个uni-group组件中|