跳到主要内容

增删改查

🔧 SDK 初始化

请参考 SDK 初始化 文档进行 SDK 初始化配置。初始化后拿到对应的数据库实例 db ,即可开始进行数据操作。

查询操作符

数据库 API 提供了大于、小于等多种动态查询指令,这些指令都暴露在 db.command 对象上。

📖 详细文档wxCloud 数据库操作符

操作符说明示例
eq等于{age: _.eq(18)}
neq不等于{status: _.neq('deleted')}
gt大于{score: _.gt(80)}
gte大于等于{age: _.gte(18)}
lt小于{price: _.lt(100)}
lte小于等于{discount: _.lte(0.5)}
in在数组中{category: _.in(['tech', 'news'])}
nin不在数组中{status: _.nin(['deleted', 'banned'])}

🔍 查询数据

单条查询

通过文档 ID 查询指定记录。

参数说明

参数类型必填说明
docIdstring✅ 是文档的唯一标识符

代码示例

// 根据文档 ID 查询单条记录
const result = await db.collection('todos')
.doc('docId')
.get()

console.log('查询结果:', result.data)

返回结果

{
data: {
_id: "todo-id-123",
title: "学习 CloudBase",
completed: false,
// ... 其他字段
},
errMsg: "document.get:ok"
}

多条查询

查询集合中的多条记录,支持条件筛选、排序、分页等。

参数说明

方法参数类型必填说明
where()object❌ 否查询条件,支持操作符
orderBy()string, string❌ 否排序字段和方向('asc' 或 'desc')
limit()number❌ 否限制返回记录数, 默认 100 条, 最多返回 1000 条
skip()number❌ 否跳过记录数,用于分页
field()object❌ 否指定返回字段,true 表示返回,false 表示不返回
// 查询所有记录
const result = await db.collection('todos').get()
console.log('查询结果:', result.data)

// 条件查询
const result = await db.collection('todos')
.where({
completed: false,
priority: 'high'
})
.get()

高级查询

const _ = db.command

// 复杂条件查询
const result = await db.collection('todos')
.where({
// 年龄大于 18
age: _.gt(18),
// 标签包含 '技术'
tags: _.in(['技术', '学习']),
// 创建时间在最近一周内
createdAt: _.gte(new Date(Date.now() - 7 * 24 * 60 * 60 * 1000))
})
.orderBy('createdAt', 'desc') // 按创建时间倒序
.limit(10) // 限制 10 条
.skip(0) // 跳过 0 条(分页)
.field({ // 只返回指定字段
title: true,
completed: true,
createdAt: true
})
.get()

分页查询

// 分页查询示例
const pageSize = 10
const pageNum = 1

const result = await db.collection('todos')
.orderBy('createdAt', 'desc')
.skip((pageNum - 1) * pageSize)
.limit(pageSize)
.get()

console.log(`${pageNum} 页数据:`, result.data)

聚合查询

// 统计查询
const result = await db.collection('todos')
.aggregate()
.group({
_id: '$priority',
count: {
$sum: 1
}
})
.end()

console.log('按优先级统计:', result.list)

➕ 新增数据

单条新增

向集合中添加一条新记录。

参数说明

参数类型必填说明
dataobject✅ 是要新增的数据对象

代码示例

// 添加单条记录
const result = await db.collection('todos').add({
data: {
title: '学习 CloudBase',
content: '完成数据库操作教程',
completed: false,
priority: 'high',
createdAt: new Date(),
tags: ['学习', '技术']
}
})

console.log('新增成功,文档 ID:', result._id)

批量新增

一次性向集合中添加多条记录。

参数说明

参数类型必填说明
dataarray✅ 是包含多个数据对象的数组,每个对象包含 data 字段

代码示例

// 批量添加多条记录
const batchResult = await db.collection('todos').add([{
data: {
title: '任务1',
priority: 'high',
completed: false
}
},
{
data: {
title: '任务2',
priority: 'medium',
completed: false
}
}
])

console.log('批量新增成功:', batchResult)

📝 更新数据

单条更新

通过文档 ID 更新指定记录。

参数说明

参数类型必填说明
docIdstring✅ 是要更新的文档 ID
dataobject✅ 是要更新的数据对象

代码示例

// 更新指定文档
const result = await db.collection('todos')
.doc('todo-id')
.update({
data: {
title: '学习 CloudBase 数据库',
completed: true,
updatedAt: new Date(),
completedBy: 'user123'
}
})

console.log('更新成功,影响记录数:', result.stats.updated)

批量更新

根据查询条件批量更新多条记录。

参数说明

参数类型必填说明
whereobject✅ 是查询条件,确定要更新的记录
dataobject✅ 是要更新的数据对象

代码示例

// 批量更新多条记录
const batchResult = await db.collection('todos')
.where({
completed: false,
priority: 'low'
})
.update({
data: {
priority: 'normal',
updatedAt: new Date()
}
})

console.log('批量更新结果:', batchResult)

🗑️ 删除数据

单条删除

通过文档 ID 删除指定记录。

参数说明

参数类型必填说明
docIdstring✅ 是要删除的文档 ID

代码示例

// 删除指定文档
const result = await db.collection('todos')
.doc('todo-id')
.remove()

console.log('删除成功,影响记录数:', result.stats.removed)

批量删除

根据查询条件批量删除多条记录。

参数说明

参数类型必填说明
whereobject✅ 是查询条件,确定要删除的记录

代码示例

// 批量删除多条记录
const _ = db.command
const batchResult = await db.collection('todos')
.where({
completed: true,
createdAt: _.lt(new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)) // 30天前
})
.remove()

console.log('批量删除结果:', batchResult)

⚠️ 注意事项

错误处理

所有数据库操作都应该使用 try-catch 进行错误处理:

try {
const result = await db.collection('todos').get()
console.log('查询成功:', result.data)
} catch (error) {
console.error('查询失败:', error)
}

重要提醒

注意事项说明建议
权限控制确保已正确配置数据库安全规则使用最小权限原则
数据校验在客户端和服务端都要进行数据校验防止无效数据入库
性能优化合理使用索引和查询条件避免全表扫描

💡 最佳实践

数据结构设计

  • 合理设计集合结构:避免过度嵌套,保持数据结构清晰
  • 建立索引:为常用查询字段建立索引提升性能
  • 数据类型:使用合适的数据类型,如日期使用 时间戳

查询优化

  • 限制返回数据量:使用 limit() 控制返回记录数
  • 字段投影:使用 field() 只返回需要的字段

安全考虑

  • 安全规则:配置合适的数据库安全规则
  • 输入验证:验证用户输入数据的合法性
  • 敏感信息:避免在客户端存储敏感信息