小程序
  • 中文
  • EN
取消
开发
  • 中文
  • EN
中文
EN
取消
  • 云开发

    • # 数据模型 SDK

    # 初始化 SDK

    参考 引入和初始化数据模型 SDK

    # 数据模型命名空间

    # models

    在初始化 SDK 之后，会自动在 models 上挂载针对当前云开发环境下的数据模型的操作方法

    通过 models.<model_name> 可以访问某个模型的操作方法

    例如：

    // const wxCloud = client.init(wx.cloud);
// const models = wxCloud.models;

models.<model_name>.create() // 创建单条数据
models.<model_name>.createMany()  // 创建多条数据
models.<model_name>.update() // 更新单条数据
models.<model_name>.updateMany() // 更新多条数据
models.<model_name>.delete() // 删除单条数据
models.<model_name>.deleteMany() // 删除多条数据
models.<model_name>.get() // 查询单条数据
models.<model_name>.list() // 查询多条数据

    数据模型的方法可以在云函数中和小程序中均可使用

    • 在小程序端运行时，默认是当前登录用户的身份调用
    • 在云函数中运行时，默认是管理员权限，后续会支持选择以客户端小程序用户身份调用

    # 模型查询方法

    # create()

    create 方法会创建一条新的数据

    (params) => Promise<MethodResponse<CreateResponse<T>>>

    # 参数

    属性 类型 默认值 示例 必填 说明
    params.data T 无 {name: "hello"} 是 对应数据模型的字段结构

    # 返回值

    Promise<MethodResponse<CreateResponse<T>>>

    属性 类型 默认值 示例 必填 说明
    data.id string 无 "7L5G32U9PE" 是 id 为对应创建数据对应的标识

    # 示例

    创建新文章：

    const { data } = await models.post.create({
  data: {
    body: "你好，世界👋nnfrom china",
    title: "你好，世界👋",
    slug: "hello-world-cn",
  },
});

// 返回创建的文章 id
console.log(data);
// { id: "7d8ff72c665eb6c30243b6313aa8539e"}

    # createMany()

    createMany 方法用于创建多条新的数据记录。

    (params) => Promise<MethodResponse<CreateManyResponse<T>>>

    # 参数

    属性 类型 默认值 示例 必填 说明
    params.data T[] 无 [{name: "hello"}, {name: "world"}] 是 不能为空数组, 传入空对象会被忽略

    # 返回值

    Promise<MethodResponse<CreateManyResponse<T>>>

    属性 类型 默认值 示例 说明
    data.idList idList: string[] 无 ["7L5G32U9PE"] idList 为对应创建数据对应的标识列表

    # 示例

    创建新文章：

    const { data } = await models.post.createMany({
  data: [
    {
      title: "Hello World👋",
    },
    {
      title: "Hola Mundo 👋",
    },
    {
      title: "你好，世界👋",
    },
    {
      title: "Bonjour le Monde👋",
    },
  ],
});

// 返回创建的文章 idList
console.log(data);
// {
//   "idList": [
//       "7d8ff72c665ebe5c02442a1a7b29685e",
//       "7d8ff72c665ebe5c02442a1b77feba4b",
//       "7d8ff72c665ebe5c02442a1c48263dc6",
//       "7d8ff72c665ebe5c02442a1d53c311b0"
//   ]
// }

    # update()

    update 方法用于更新一条已存在的数据记录。

    (params) => Promise<MethodResponse<UpdateResponse<T>>>

    # 参数

    属性 类型 默认值 示例 必填 说明
    params.data T 无 {name: "hello"} 是 对应数据模型的字段结构
    params.filter FilterParams<T> 无 {filter: {where: {_id:{$eq:"foo"}}}} 是 过滤条件

    FilterParams<T> 为查询参数的结构，请参考查询参数说明 该方法为单条更新方法，如果使用筛选条件，筛选得到多条数据，则不能用这个方法更新

    # 返回值

    Promise<MethodResponse<UpdateResponse<T>>>

    属性 类型 默认值 示例 说明
    data.count count: 0 or 1 无 1 变更的条数，返回非 0 值代表更新成功。

    # 示例

    更新文章内容：

    const { data } = await models.post.update({
  data: {
    title: "Hello World",
    body: "Hello World",
  },
  filter: {
    where: {
      _id: {
        $eq: "xxxx", // 推荐传入_id数据标识进行操作
      },
    },
  },
});

// 返回更新成功的条数
console.log(data);
// { count: 1}

    # upsert()

    upsert 方法用于创建或更新一条记录

    (params) => Promise<MethodResponse<UpsertResponse<T>>>

    # 参数

    属性 类型 默认值 示例 必填 说明
    params.update T 无 {name: "hello", _id: "foo" } 是 对应数据模型的字段结构, 更新记录时会用根据这个来更新
    params.create T 无 {name: "hello", _id: "foo"} 是 对应数据模型的字段结构，新增记录是会根据这个来新增
    params.filter FilterParams<T> 无 {filter: {where: {_id:{$eq:"foo"}}}} 是 过滤条件

    FilterParams<T> 为查询参数的结构，请参考查询参数说明 该方法为单条更新方法，如果使用筛选条件，筛选得到多条数据，则不能用这个方法更新

    # 返回值

    Promise<MethodResponse<UpsertResponse<T>>>

    属性 类型 默认值 示例 说明
    data.count count: 0 or 1 无 1 变更的条数，返回非 0 值代表更新成功。
    data.id string 无 1 新增的记录的 id

    # 示例

    创建或更新文章内容：

    const post = {
  title: "Hello World",
  body: "Hello World",
  _id: "foo",
};
const { data } = await models.post.upsert({
  create: post,
  update: post,
  filter: {
    where: {
      _id: {
        $eq: post._id,
      },
    },
  },
});
console.log(data);
// 新增时返回
//   {
//     "count": 0,
//     "id": "foo"
// }

// 更新时返回
//   {
//     "count": 1,
//     "id": ""
// }

    # updateMany()

    updateMany 方法用于更新多条匹配特定条件的数据记录。

    (params) => Promise<MethodResponse<CreateManyResponse<T>>>

    # 参数

    属性 类型 默认值 示例 必填 说明
    params.data T 无 {name: "hello"} 是 对应数据模型的字段结构
    params.filter FilterParams<T> 无 {filter: {where: {}}} 是 查询条件

    FilterParams<T> 为查询参数的结构，请参考查询参数说明 批量更新一次最多只能更新 200 条

    # 返回值

    Promise<MethodResponse<CreateManyResponse<T>>>

    属性 类型 默认值 示例 说明
    data.count count: 0 or 1 无 1 变更的条数，返回非 0 值代表更新成功

    # 示例

    例如筛选内容不为空的数据，更新文章内容和别名：

    const { data } = await models.post.updateMany({
  data: {
    slug: "hello-world",
    body: `
        "你好世界"可以翻译成以下几种语言：
        
        英语：Hello World 西班牙语：Hola Mundo 法语：Bonjour le Monde 德语：Hallo Welt 意大利语：Ciao Mondo 葡萄牙语：Olá Mundo 荷兰语：Hallo Wereld 日语：こんにちは、世界 (Konnichiwa, Sekai) 韩语：안녕하세요, 세계 (Annyeonghaseyo, Segye)`,
  },
  filter: {
    where: {
      title: {
        $nempty: 1, // 不为空的数据
      },
    },
  },
});

// 返回更新成功的条数
console.log(data);
// {
//   "count": 33
// }

    # delete()

    delete 方法用于删除一条数据记录。

    (params) => Promise<MethodResponse<DeleteResponse<T>>>

    # 参数

    属性 类型 默认值 示例 必填 说明
    params.filter FilterParams<T> 无 {filter: {where: {}}} 是 查询结构

    FilterParams<T> 为查询参数的结构，请参考查询参数说明 数据源筛选条件满足条数为 1 以上进行时进行单条更新会出错

    # 返回值

    Promise<MethodResponse<DeleteResponse<T>>>

    属性 类型 默认值 示例 说明
    data.count count: 0 or 1 无 1 变更的条数，返回非 0 值代表更新成功

    # 示例

    删除指定 _id 的文章：

    const { data } = await models.post.delete({
  filter: {
    where: {
      _id: {
        $eq: "xxx", // 推荐传入_id数据标识进行操作
      },
    },
  },
});

// 返回删除成功的条数
console.log(data);
// {
//   "count": 1
// }

    # deleteMany()

    deleteMany 方法用于删除多条匹配特定条件的数据记录。

    (params) => Promise<MethodResponse<DeleteManyResponse<T>>>

    # 参数

    属性 类型 默认值 示例 必填 说明
    params.filter FilterParams<T> 无 {filter: {where: {}}} 是 查询过滤参数

    FilterParams<T> 为查询参数的结构，请参考查询参数说明 批量删除一次最多只能删除 200 条

    # 返回值

    Promise<MethodResponse<DeleteManyResponse<T>>>

    属性 类型 默认值 示例 说明
    data.count count: 0 or 1 无 1 变更的条数，返回非 0 值代表更新成功

    # 示例

    例如删除标题为 'Hello World👋' 的文章：

    const { data } = await models.post.deleteMany({
  filter: {
    where: {
      title: {
        $eq: "Hello World👋",
      },
    },
  },
});

console.log(data);
// 返回删除成功的条数
// {
//   "count": 7
// }

    # get()

    get 方法用于获取一条数据记录。

    (params) => Promise<MethodResponse<T>>

    # 参数

    属性 类型 默认值 示例 必填 说明
    params.filter FilterParams<T> 无 {filter: {where: {}}} 是 查询参数
    params.select SelectParams<T> 无 { $master: true } 是 可以指定返回本表或者关联表的字段，如果想查询本表所有字段，请使用 { $master: true }

    # 返回值

    Promise<MethodResponse<T>>

    属性 类型 默认值 示例 说明
    data T 无 { name: "hello" } 返回满足筛选条件的模型行记录

    # 示例

    获取特定文章：

    const { data } = await models.post.get({
  filter: {
    where: {
      _id: {
        $eq: _id, // 推荐传入_id数据标识进行操作
      },
    },
  },
});

// 返回查询到的数据
console.log(data);
// {
//     "owner": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//     "createdAt": 1717488585078,
//     "createBy": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//     "updateBy": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//     "_openid": "95fblM7nvPi01yQmYxBvBg",
//     "_id": "e2764d2d665ecbc9024b058f1d6b33a4",
//     "title": "你好，世界👋",
//     "body": ""你好世界"可以翻译成以下几种语言：nn英语：Hello Worldn西班牙语：Hola Mundon法语：Bonjour le Monden德语：Hallo Weltn意大利语：Ciao Mondon葡萄牙语：Olá Mundon荷兰语：Hallo Wereldn日语：こんにちは、世界 (Konnichiwa, Sekai)n韩语：안녕하세요, 세계 (Annyeonghaseyo, Segye)",
//     "slug": "hello-world",
//     "updatedAt": 1717490751944
// }

    # list()

    list 方法用于获取多条数据记录。

    (params) => Promise<MethodResponse<{ records: T[]; total?: number }>>

    # 参数

    入参结构

    属性 类型 默认值 必填 说明
    params.filter? FilterParams<T> 无 是 查询过滤参数
    params.select? SelectParams<T> 无 是 { $master: true } 可以指定返回本表或者关联表的字段，如果想查询本表所有字段，请使用 { $master: true }
    params.getCount? boolean false 否 获取 filter 命中条件的查询条数
    params.pageSize? number 10 否 分页大小，建议指定，如需设置为其它值，需要和 pageNo 配合使用，两者同时指定才会生效
    params.pageNumber? number 1 否 分页数目
    params.orderBy? OrderByParams[] 无 否 排序，当前仅支持最多 3 字段排序

    对于orderBy的排序，在默认情况下以底层数据库查询结果为准，不存在新建数据一定会排在最前的情况。 查询请求单次最大仅支持 200 条

    # 返回值

    Promise<MethodResponse<{ records: T[]; total?: number }>>

    属性 类型 默认值 示例 说明
    data.records T[] 无 [{ name: "hello" }, { name: 'world"'}] records 内的数组为对应的数据源数据对象
    data.total? number 无 3 入参配置了 getCount 为 true 时会返回满足筛选查询条件的大小，注意，此字段不代表返回 records 的长度，可以用作页面大小的计算。当getCount为false的时候，不应该对此值做任何期待

    # 示例

    获取所有文章，返回查询到的数据列表 records 和 总数 total

    const { data } = await models.post.list({
  filter: {
    where: {},
  },
  getCount: true, // 开启用来获取总数
});

// 返回查询到的数据列表 `records` 和 总数 `total`
console.log(data);
// {
//     "records": [
//         {
//             "owner": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//             "createdAt": 1717488585078,
//             "createBy": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//             "updateBy": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//             "_openid": "95fblM7nvPi01yQmYxBvBg",
//             "_id": "e2764d2d665ecbc9024b058f1d6b33a4",
//             "title": "你好，世界👋",
//             "body": ""你好世界"可以翻译成以下几种语言：nn英语：Hello Worldn西班牙语：Hola Mundon法语：Bonjour le Monden德语：Hallo Weltn意大利语：Ciao Mondon葡萄牙语：Olá Mundon荷兰语：Hallo Wereldn日语：こんにちは、世界 (Konnichiwa, Sekai)n韩语：안녕하세요, 세계 (Annyeonghaseyo, Segye)",
//             "slug": "hello-world",
//             "updatedAt": 1717490751944
//         },
//         {
//          ...
//		   },
//     ],
//     "total": 51
// }

    # 模型查询参数

    # filter

    用于指定记录选择的条件，支持多种过滤方式。

    具体可参考 FilterParams<T>

    # select

    select 指定返回数据对象中应包含的字段。

    具体可参考 SelectParams<T>

    ✅ 建议仅选择需要的字段和关系来减少响应数据的大小并提高查询速度。

    # 示例

    # 返回主模型字段

    例如，我们在查询单篇文章详情的时候，默认查询了文章主模型的所有字段

    const { data } = await models.post.get({
  select: {
    $master: true, // 查询主模型所有的字段
  },
  filter: {
    where: {
      _id: {
        $eq: _id, // 推荐传入_id数据标识进行操作
      },
    },
  },
});
// 返回查询到的数据
console.log(data);
// {
//     "owner": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//     "createdAt": 1717488585078,
//     "createBy": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//     "updateBy": "Anonymous(95fblM7nvPi01yQmYxBvBg)",
//     "_openid": "95fblM7nvPi01yQmYxBvBg",
//     "_id": "e2764d2d665ecbc9024b058f1d6b33a4",
//     "title": "你好，世界👋",
//     "body": ""你好世界"可以翻译成以下几种语言：nn英语：Hello Worldn西班牙语：Hola Mundon法语：Bonjour le Monden德语：Hallo Weltn意大利语：Ciao Mondon葡萄牙语：Olá Mundon荷兰语：Hallo Wereldn日语：こんにちは、世界 (Konnichiwa, Sekai)n韩语：안녕하세요, 세계 (Annyeonghaseyo, Segye)",
//     "slug": "hello-world",
//     "updatedAt": 1717490751944
// }
    # 返回关联模型字段

    筛选关联模型字段，筛选新关联关系

    # 返回指定字段

    在查询文章列表的时候，一般情况下我们并不需要查询所有的列表数据，只需要返回必要的字段即可。

    const { data } = await models.post.list({
  // 只查询必要的字段
  select: {
    _id: true,
    title: true,
    updatedAt: true,
  },
  filter: {
    where: {},
  },
  getCount: true, // 开启用来获取总数
});

// 返回查询到的数据列表 `records` 和 总数 `total
// 返回的内容明显是经过了数据库的过滤，只返回了_id, title, updatedAt三个字段
console.log(data);
// {
//     "records": [
//         {
//             "_id": "e2764d2d665ecbc9024b058f1d6b33a4",
//             "title": "你好，世界👋",
//             "updatedAt": 1717492882289
//         },
//         {
//             "_id": "e2764d2d665ecbc9024b05905902dab4",
//             "title": "Bonjour le Monde👋",
//             "updatedAt": 1717488585078
//         },
//         {
//             "_id": "e2764d2d665ecbc9024b058e75abbbeb",
//             "title": "Hola Mundo 👋",
//             "updatedAt": 1717488585078
//         },
//         {
//             "_id": "e2764d2d665ecbc9024b058d064d8a51",
//             "title": "Hello World👋",
//             "updatedAt": 1717488585078
//         },
//         {
//             "_id": "e8da0808665ecba20249254f15c211b0",
//             "title": "Bonjour le Monde👋",
//             "updatedAt": 1717488546718
//         },
//         {
//             "_id": "e8da0808665ecba20249254e2f20781e",
//             "title": "你好，世界👋",
//             "updatedAt": 1717488546718
//         },
//         {
//             "_id": "e8da0808665ecba20249254d6151ab80",
//             "title": "Hola Mundo 👋",
//             "updatedAt": 1717488546718
//         },
//         {
//             "_id": "e8da0808665ecba20249254c75aa3e64",
//             "title": "Hello World👋",
//             "updatedAt": 1717488546718
//         },
//         {
//             "_id": "57bdf48a665ecb9f004fe19b6398933c",
//             "title": "Bonjour le Monde👋",
//             "updatedAt": 1717488543827
//         },
//         {
//             "_id": "57bdf48a665ecb9f004fe1997b57f79a",
//             "title": "Hola Mundo 👋",
//             "updatedAt": 1717488543827
//         }
//     ],
//     "total": 51
// }

    # getCount

    布尔值，表示是否返回匹配过滤条件的记录总数。

    # orderBy

    指定返回记录的排序方式。

    具体可参考 OrderByParams[]

    # 示例

    [
  {
    title: "asc", // 升序
  },
  {
    createdAt: "desc", // 降序
  },
];

    # 过滤条件和运算符

    # 逻辑运算符

    # $and

    使用逻辑 AND 连接条件。

    # $or

    使用逻辑 OR 连接条件。

    # 比较运算符

    # $eq

    匹配等于指定值的值。

    # $neq

    匹配不等于指定值的所有值。

    # $gt

    匹配大于指定值的值。

    # $gte

    匹配大于或等于指定值的值。

    # $lt

    匹配小于指定值的值。

    # $lte

    匹配小于或等于指定值的值。

    # $in

    匹配数组中指定的任何值。

    # $nin

    不匹配数组中指定的任何值。

    # 特殊运算符

    对字符串字段执行模糊查询。

    # $nsearch

    查找不包含指定字符串值的记录。

    # $empty

    数据为 null

    # nempty

    数据不为 null