校友会小程序云开发提供了一个 JSON 数据库,顾名思义,数据库中的每条记录都是一个 JSON 格式的对象。
一个数据库可以有多个集合(相当于关系型数据中的表),集合可看做一个 JSON 数组,数组中的每个对象就是一条记录,记录的格式是 JSON 对象。
以下是一个示例的集合数据,假设我们有一个 t_user集合存放了校友记录,其中有2名新注册的校友:
[
{
"_id": "ohl4L0Rnhq7vmmbT_D2aNQa4ePaz0",
"USER_NAME": "刘敏",
"USER_SEX": "男",
"USER_ITEM": {
"enroll": 2002,
"grad": 2006,
"class": "计算机科学与技术024班"
}
},
{
"_id": "ohl4L0Rnhq2vmmbT_D2aNQa4ePaz0",
"USER_NAME": "艾思",
"USER_SEX": "女",
"USER_ITEM": {
"enroll": 2012,
"grad": 2016,
"class": "国际金融121班"
}
}
]
在校友信息中,我们用 USER_NAME来记录校友姓名,用 USER_ITEM
对象来记录其毕业班级,入学年份,毕业年份,
在其中我们可以看到,字段既可以是字符串或数字,还可以是对象或数组,就是一个 JSON 对象。
每条校友记录都有一个 _id
字段用以唯一标志一条记录、一个 _openid
字段用以标志记录的创建者,即小程序的用户。
需要特别注意的是,在管理端(控制台和云函数)中创建的不会有 _openid
字段,因为这是属于管理员创建的记录。
开发者可以自定义 _id
,但不可自定义和修改 _openid
。
_openid
是在文档创建时由系统根据小程序用户默认创建的,开发者可使用其来标识和定位文档。
校友会小程序数据库 API 分为小程序端和服务端两部分,校友会小程序小程序端 API 拥有严格的调用权限控制,校友会小程序开发者可在小程序内直接调用 API 进行非敏感数据的操作。
对于有更高安全要求的数据,可在校友会小程序云函数内通过服务端 API 进行操作。
校友会小程序云函数的环境是与客户端完全隔离的,在云函数上可以私密且安全的操作数据库。
校友会小程序数据库 API 包含增删改查的能力,使用 API 操作数据库只需三步:获取数据库引用、构造查询/更新条件、发出请求。
以下是一个在校友会小程序中查询数据库找校友的例子:
// 1. 获取数据库引用
const db = wx.cloud.database()
// 2. 构造查询语句
// collection 方法获取一个集合的引用
// where 方法传入一个对象,数据库返回集合中字段等于指定值的 JSON 文档。API 也支持高级的查询条件(比如大于、小于、in 等),具体见文档查看支持列表
// get 方法会触发网络请求,往数据库取数据
db.collection('t_user').where({
USER_ITEM: {
enroll: '2012' //查询2012年 入学的校友
}
}).get({
success: function(res) {
// 输出 [{ "USER_NAME": "校友姓名", ... }]
console.log(res)
}
})
数据类型
校友会小程序云开发数据库提供以下几种数据类型:
String:字符串
Number:数字
Object:对象
Array:数组
Bool:布尔值
Date:时间
Geo:多种地理位置类型,详见下
Null
下面对几个需要额外说明的字段做下补充说明。
Date
Date 类型用于表示时间,精确到毫秒,在校友会小程序端可用 JavaScript 内置 Date 对象创建。
需要特别注意的是,在校友会小程序创建的时间是客户端时间,不是服务端时间,这意味着在校友会小程序的时间与服务端时间不一定吻合,如果需要使用服务端时间,
应该用 API 中提供的 serverDate 对象来创建一个服务端当前时间的标记,当使用了 serverDate 对象的请求抵达服务端处理时,该字段会被转换成服务端当前的时间,
更棒的是,我们在构造 serverDate 对象时还可通过传入一个有 offset 字段的对象来标记一个与当前服务端时间偏移 offset 毫秒的时间,
这样我们就可以达到比如如下效果:指定一个字段为服务端时间往后一个小时。
那么当我们需要使用校友会小程序客户端时间时,存放 Date 对象和存放毫秒数是否是一样的效果呢?
不是的,我们的数据库有针对日期类型的优化,建议大家使用时都用 Date 或 serverDate 构造时间对象。
地理位置
除 db.Geo.Point 外,需校友会小程序基础库版本 2.6.3 或以上。控制台需开发者工具版本 1.02.1903251 或以上。
校友会小程序云开发数据库提供了多种地理位置数据类型的增删查改支持,支持的地理位置数据类型有以下几种(API 文档):
字段 说明 最低基础库版本
Point 点 2.2.3
LineString 线段 2.6.3
Polygon 多边形 2.6.3
MultiPoint 点集合 2.6.3
MultiLineString 线段集合 2.6.3
MultiPolygon 多边形集合 2.6.3
要使用地理位置查询功能时,必须建立地理位置索引,建议用于存储地理位置数据的字段均建立地理位置索引。
地理位置索引可在云控制台建立索引的入口中选择地理位置索引(2dsphere)。
Null
null 相当于一个占位符,表示一个字段存在但是值为空。