docs: update database documents (#308)

docs/api/database.md

@@ -73,6 +73,59 @@ sidebarDepth: 2
 
 ### db.get(table, query, fields?)
 
+- **table:** `keyof Tables` 注册在 ORM 中的表名
+- **query:** `QueryExpr<Tables[T]> | QueryShorthand` 搜索表达式
+- **fields:** `Tables.Field<T>[]` 请求的字段，默认为全部字段
+- 返回值: `Promise<Tables[T][]>` 用户数据
+
+参数 query 支持正则以及表达式，你可以使用复杂的嵌套更细致化的去完成你对数据库的查找服务。实现上与 mongo 近似，如果你有使用过 mongodb 经验，那么使用 Koishi ORM 对你来说便不是一件难事。
+
+```ts
+interface FieldQueryExpr<T> {
+  $regex?: RegExp
+  $in?: T[]
+  $nin?: T[]
+  $eq?: T
+  $ne?: T
+  $gt?: T
+  $gte?: T
+  $lt?: T
+  $lte?: T
+}
+interface LogicalQueryExpr<T> {
+  $or?: QueryExpr<T>[]
+  $and?: QueryExpr<T>[]
+  $not?: QueryExpr<T>
+}
+type QueryShorthand<T = IndexType> = T[] | RegExp
+type FieldQuery<T> = FieldQueryExpr<T> | QueryShorthand<T>
+type QueryExpr<T = any> = LogicalQueryExpr<T> & {
+  [K in keyof T]?: FieldQuery<T[K]>
+}
+```
+
+下面是一些简单的示例
+
+```js
+// 获取名为 schedule 的表中 id 为 1 或者 2 的数据行
+// Koishi ORM 自动解析你的 primary key
+const rows = await ctx.database.get('schedule', [1, 2])
+const rows = await ctx.database.get('schedule', { id: [1, 2] })
+
+// 当然 Koishi ORM 也支持了 mongo 的正则写法
+const rows = await ctx.database.get('schedule', { command: /echo.*/ })
+
+// 获取名为 schedule 的表中 id 大于 2 但是小于等于 5 的数据行
+const rows = await ctx.database.get('schedule', { id: { $gt: 2, $lte: 5 } })
+
+// 获取名为 schedule 的表中
+// id 大于 2 但是小于等于 5 或者 id 大于 100 的数据行
+const rows = await ctx.database.get('schedule', {
+  id: { $gt: 2, $lte: 5 },
+  $or: [{ $id: { $gt: 100 } }],
+})
+```
+
 ### db.remove(table, query)
 
 ### db.create(table, data)

docs/guide/database.md

@@ -166,6 +166,15 @@ const rows = await ctx.database.get('schedule', [1234], ['command', 'lastCall'])
 const rows = await ctx.database.get('schedule', { assignee: ['onebot:123456'] })
 ```
 
+对于需要进行复杂的数据库搜索的，ORM 也提供了相对应的方法：
+
+```js
+// 获取名为 schedule 的表中 id 大于 2 但是小于等于 5 的数据行
+const rows = await ctx.database.get('schedule', { id: { $gt: 2, $lte: 5 } })
+```
+
+> 你可以在 [这里](../api/database.md#db-get-table) 看到更多相关的 API。
+
 删除数据的语法与获取数据类似：
 
 ```js