docs: clientDB getTree getTreePath

docs/uniCloud/clientdb.md

@@ -644,6 +644,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"
+    },
+    "code": {
+      "bsonType": "string",
+      "description": "当前code",
+      "parentKey": "parent_code", // 指定父子关系为：如果一条数据库记录A的code和当前数据库记录B的parent_code相等，则A是B的父级。一个表内只能有一个父子关系
+    },
+    "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`方法新增数据记录。