AggregateCommand.concat(value: Expression[]): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。连接字符串，返回拼接后的字符串。

参数

value: Expression[]

[<表达式1>, <表达式2>, ...]

返回值

Object

API 说明

concat 的语法如下：

db.command.aggregate.concat([<表达式1>, <表达式2>, ...])

表达式可以是形如 $ + 指定字段，也可以是普通字符串。只要能够被解析成字符串即可。

示例代码

假设集合 students 的记录如下：

{ "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }
{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }
{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

借助 concat 可以拼接 lastName 和 firstName 字段，得到每位学生的名字全称：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    fullName: $.concat(['$firstName', ' ', '$lastName'])
  })
  .end()

返回的结果如下：

{ "fullName": "Yuanxin Dong" }
{ "fullName": "Weijia Wang" }
{ "fullName": "Chengxi Li" }

---

AggregateCommand.dateFromString(value: any): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。将一个日期/时间字符串转换为日期对象

参数

value: any

返回值

Object

API 说明

语法如下：

db.command.aggregate.dateFromString({
    dateString: <dateStringExpression>,
    timezone: <tzExpression>
})

示例代码

const $ = db.command.aggregate
db
  .collection('dates')
  .aggregate()
  .project({
    _id: 0,
    date: $.dateFromString({
        dateString: "2019-05-14T09:38:51.686Z"
    })
  })
  .end()

输出如下：

{
    "date": ISODate("2019-05-14T09:38:51.686Z")
}

---

AggregateCommand.dateToString(value: any): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。根据指定的表达式将日期对象格式化为符合要求的字符串。

参数

value: any

返回值

Object

API 说明

dateToString 的调用形式如下：

db.command.aggregate.dateToString({
  date: <日期表达式>,
  format: <格式化表达式>,
  timezone: <时区表达式>,
  onNull: <空值表达式>
})

下面是四种表达式的详细说明：

名称	描述
日期表达式	必选。指定字段值应该是能转化为字符串的日期。
格式化表达式	可选。它可以是任何包含“格式说明符”的有效字符串。
时区表达式	可选。指明运算结果的时区。它可以解析格式为 UTC Offset 或者 Olson Timezone Identifier 的字符串。
空值表达式	可选。当 <日期表达式> 返回空或者不存在的时候，会返回此表达式指明的值。

下面是格式说明符的详细说明：

说明符	描述	合法值
%d	月份的日期（2位数，0填充）	01 - 31
%G	ISO 8601 格式的年份	0000 - 9999
%H	小时（2位数，0填充，24小时制）	00 - 23
%j	一年中的一天（3位数，0填充）	001 - 366
%L	毫秒（3位数，0填充）	000 - 999
%m	月份（2位数，0填充）	01 - 12
%M	分钟（2位数，0填充）	00 - 59
%S	秒（2位数，0填充）	00 - 60
%w	星期几	1 - 7
%u	ISO 8601 格式的星期几	1 - 7
%U	一年中的一周（2位数，0填充）	00 - 53
%V	ISO 8601 格式的一年中的一周	1 - 53
%Y	年份（4位数，0填充）	0000 - 9999
%z	与 UTC 的时区偏移量	+/-[hh][mm]
%Z	以分钟为单位，与 UTC 的时区偏移量	+/-mmm
%%	百分号作为字符	%

示例代码

假设集合 students 有如下记录：

{ "date": "1999-12-11T16:00:00.000Z", "firstName": "Yuanxin", "lastName": "Dong" }
{ "date": "1998-11-10T16:00:00.000Z", "firstName": "Weijia", "lastName": "Wang" }
{ "date": "1997-10-09T16:00:00.000Z", "firstName": "Chengxi", "lastName": "Li" }

格式化日期

下面是将 date 字段的值，格式化成形如 年份-月份-日期 的字符串：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    formatDate: $.dateToString({
      date: '$date',
      format: '%Y-%m-%d'
    })
  })
  .end()

返回的结果如下：

{ "formatDate": "1999-12-11" }
{ "formatDate": "1998-11-10" }
{ "formatDate": "1997-10-09" }

时区时间

下面是将 date 字段值格式化为上海时区时间的例子：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    formatDate: $.dateToString({
      date: '$date',
      format: '%H:%M:%S',
      timezone: 'Asia/Shanghai'
    })
  })
  .end()

返回的结果如下：

{ "formatDate": "00:00:00" }
{ "formatDate": "00:00:00" }
{ "formatDate": "00:00:00" }

缺失情况的默认值

当指定的 <日期表达式> 返回空或者不存在的时候，可以设置缺失情况下的默认值：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    formatDate: $.dateToString({
      date: '$empty',
      onNull: 'null'
    })
  })
  .end()

返回的结果如下：

{ "formatDate": "null" }
{ "formatDate": "null" }
{ "formatDate": "null" }

---

AggregateCommand.indexOfBytes(value: Expression[]): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。在目标字符串中查找子字符串，并返回第一次出现的 UTF-8 的字节索引（从0开始）。如果不存在子字符串，返回 -1。

参数

value: Expression[]

[<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>]

返回值

Object

API 说明

indexOfBytes 的语法如下：

db.command.aggregate.indexOfBytes([<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>])

下面是 4 种表达式的详细描述：

表达式	描述
目标字符串表达式	任何可以被解析为字符串的表达式
子字符串表达式	任何可以被解析为字符串的表达式
开始位置表达式	任何可以被解析为非负整数的表达式
结束位置表达式	任何可以被解析为非负整数的表达式

示例代码

假设集合 students 的记录如下：

{ "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }
{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }
{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

借助 indexOfBytes 查找字符 "a" 在字段 firstName 中的位置：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    aStrIndex: $.indexOfBytes(['$firstName', 'a'])
  })
  .end()

返回的结果如下：

{ "aStrIndex": 2 }
{ "aStrIndex": 5 }
{ "aStrIndex": -1 }

---

AggregateCommand.indexOfCP(value: Expression[]): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。在目标字符串中查找子字符串，并返回第一次出现的 UTF-8 的 code point 索引（从0开始）。如果不存在子字符串，返回 -1。

参数

value: Expression[]

[<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>]

返回值

Object

API 说明

code point 是“码位”，又名“编码位置”。这里特指 Unicode 包中的码位，范围是从0（16进制）到10FFFF（16进制）。

indexOfCP 的语法如下：

db.command.aggregate.indexOfCP([<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>])

下面是 4 种表达式的详细描述：

表达式	描述
目标字符串表达式	任何可以被解析为字符串的表达式
子字符串表达式	任何可以被解析为字符串的表达式
开始位置表达式	任何可以被解析为非负整数的表达式
结束位置表达式	任何可以被解析为非负整数的表达式

示例代码

假设集合 students 的记录如下：

{ "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }
{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }
{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

借助 indexOfCP 查找字符 "a" 在字段 firstName 中的位置：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    aStrIndex: $.indexOfCP(['$firstName', 'a'])
  })
  .end()

返回的结果如下：

{ "aStrIndex": 2 }
{ "aStrIndex": 5 }
{ "aStrIndex": -1 }

---

AggregateCommand.split(value: Expression[]): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。按照分隔符分隔数组，并且删除分隔符，返回子字符串组成的数组。如果字符串无法找到分隔符进行分隔，返回原字符串作为数组的唯一元素。

参数

value: Expression[]

[<字符串表达式>, <分隔符表达式>]

返回值

Object

API 说明

split 的语法如下：

db.command.aggregate.split([<字符串表达式>, <分隔符表达式>])

字符串表达式和分隔符表达式可以是任意形式的表达式，只要它可以被解析为字符串即可。

示例代码

假设集合 students 的记录如下：

{ "birthday": "1999/12/12" }
{ "birthday": "1998/11/11" }
{ "birthday": "1997/10/10" }

通过 split 将每条记录中的 birthday 字段对应值分隔成数组，每个数组分别由代表年、月、日的3个元素组成：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    birthday: $.split(['$birthday', '/'])
  })
  .end()

返回的结果如下：

{ "birthday": [ "1999", "12", "12" ] }
{ "birthday": [ "1998", "11", "11" ] }
{ "birthday": [ "1997", "10", "10" ] }

---

AggregateCommand.strLenBytes(value: Expression): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。计算并返回指定字符串中 utf-8 编码的字节数量。

参数

value: Expression

表达式

返回值

Object

API 说明

strLenBytes 的语法如下：

db.command.aggregate.strLenBytes(<表达式>)

只要表达式可以被解析成字符串，那么它就是有效表达式。

示例代码

假设集合 students 的记录如下：

{ "name": "dongyuanxin", "nickname": "心谭" }

借助 strLenBytes 计算 name 字段和 nickname 字段对应值的字节长度：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    nameLength: $.strLenBytes('$name'),
    nicknameLength: $.strLenBytes('$nickname')
  })
  .end()

返回结果如下：

{ "nameLength": 11, "nicknameLength": 6 }

---

AggregateCommand.strLenCP(value: Expression): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。计算并返回指定字符串的UTF-8 code points 数量。

参数

value: Expression

表达式

返回值

Object

API 说明

strLenCP 的语法如下：

db.command.aggregate.strLenCP(<表达式>)

只要表达式可以被解析成字符串，那么它就是有效表达式。

示例代码

假设集合 students 的记录如下：

{ "name": "dongyuanxin", "nickname": "心谭" }

借助 strLenCP 计算 name 字段和 nickname 字段对应值的UTF-8 code points的数量：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    nameLength: $.strLenCP('$name'),
    nicknameLength: $.strLenCP('$nickname')
  })
  .end()

返回结果如下：

{ "nameLength": 11, "nicknameLength": 2 }

---

AggregateCommand.strcasecmp(value: Expression[]): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。对两个字符串在不区分大小写的情况下进行大小比较，并返回比较的结果。

参数

value: Expression[]

[<表达式1>, <表达式2>]

返回值

Object

API 说明

strcasecmp 的语法如下：

db.command.aggregate.strcasecmp([<表达式1>, <表达式2>])

只要 表达式1和 表达式2 可以被解析成字符串，那么它们就是有效的。

返回的比较结果有1，0和-1三种：

• 1：表达式1 解析的字符串 > 表达式2 解析的字符串
• 0：表达式1 解析的字符串 = 表达式2 解析的字符串
• -1：表达式1 解析的字符串 < 表达式2 解析的字符串

示例代码

假设集合 students 的记录如下：

{ "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }
{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }
{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

借助 strcasecmp 比较 firstName 字段值和 lastName 字段值的大小：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    result: $.strcasecmp(['$firstName', '$lastName']),
  })
  .end()

返回结果如下：

{ "result": 1 }
{ "result": 1 }
{ "result": -1 }

---

AggregateCommand.substr(value: Expression[]): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。它是 db.command.aggregate.substrBytes 的别名，更推荐使用后者。

参数

value: Expression[]

[<表达式1>, <表达式2>, <表达式3>]

返回值

Object

API 说明

substr 的语法如下：

db.command.aggregate.substr([<表达式1>, <表达式2>, <表达式3>])

表达式1 是任何可以解析为字符串的有效表达式，表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

如果 表达式2 是负数，返回的结果为 ""。

如果 表达式3 是负数，返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

示例代码

假设集合 students 的记录如下：

{ "birthday": "1999/12/12", "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }
{ "birthday": "1998/11/11", "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }
{ "birthday": "1997/10/10", "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

借助 substr 可以提取 birthday 中的年、月、日信息，代码如下：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    year: $.substr(['$birthday', 0, 4]),
    month: $.substr(['$birthday', 5, 2]),
    day: $.substr(['$birthday', 8, -1])
  })
  .end()

返回的结果如下：

{ "day": "12", "month": "12", "year": "1999" }
{ "day": "11", "month": "11", "year": "1998" }
{ "day": "10", "month": "10", "year": "1997" }

---

AggregateCommand.substrBytes(value: Expression[]): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始，长度为指定的字节数。

参数

value: Expression[]

[<表达式1>, <表达式2>, <表达式3>]

返回值

Object

API 说明

substrBytes 的语法如下：

db.command.aggregate.substrBytes([<表达式1>, <表达式2>, <表达式3>])

表达式1 是任何可以解析为字符串的有效表达式，表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

如果 表达式2 是负数，返回的结果为 ""。

如果 表达式3 是负数，返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

示例代码

假设集合 students 的记录如下：

{ "birthday": "1999/12/12", "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }
{ "birthday": "1998/11/11", "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }
{ "birthday": "1997/10/10", "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

借助 substrBytes 可以提取 birthday 中的年、月、日信息，代码如下：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    year: $.substrBytes(['$birthday', 0, 4]),
    month: $.substrBytes(['$birthday', 5, 2]),
    day: $.substrBytes(['$birthday', 8, -1])
  })
  .end()

返回的结果如下：

{ "day": "12", "month": "12", "year": "1999" }
{ "day": "11", "month": "11", "year": "1998" }
{ "day": "10", "month": "10", "year": "1997" }

---

AggregateCommand.substrCP(value: Expression[]): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始，长度为指定的字节数。

参数

value: Expression[]

[<表达式1>, <表达式2>, <表达式3>]

返回值

Object

API 说明

substrCP 的语法如下：

db.command.aggregate.substrCP([<表达式1>, <表达式2>, <表达式3>])

表达式1 是任何可以解析为字符串的有效表达式，表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

如果 表达式2 是负数，返回的结果为 ""。

如果 表达式3 是负数，返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

示例代码

假设集合 students 的记录如下：

{ "name": "dongyuanxin", "nickname": "心谭" }

借助 substrCP 可以提取 nickname 字段值的第一个汉字：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    firstCh: $.substrCP(['$nickname', 0, 1])
  })
  .end()

返回的结果如下：

{ "firstCh": "心" }

---

AggregateCommand.toLower(value: any): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。将字符串转化为小写并返回。

参数

value: any

返回值

Object

API 说明

toLower 的语法如下：

db.command.aggregate.toLower(表达式)

只要表达式可以被解析成字符串，那么它就是有效表达式。例如：$ + 指定字段。

示例代码

假设集合 students 的记录如下：

{ "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }
{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }
{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

借助 toLower 将 firstName 的字段值转化为小写：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    result: $.toLower('$firstName'),
  })
  .end()

返回的结果如下：

{ "result": "yuanxin" }
{ "result": "weijia" }
{ "result": "chengxi" }

---

AggregateCommand.toUpper(value: any): Object

支持端：小程序 2.7.4, 云函数 0.8.1, Web

聚合操作符。将字符串转化为大写并返回。

参数

value: any

返回值

Object

API 说明

toUpper 的语法如下：

db.command.aggregate.toUpper(表达式)

只要表达式可以被解析成字符串，那么它就是有效表达式。例如：$ + 指定字段。

示例代码

假设集合 students 的记录如下：

{ "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }
{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }
{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

借助 toUpper 将 lastName 的字段值转化为大写：

const $ = db.command.aggregate
db
  .collection('students')
  .aggregate()
  .project({
    _id: 0,
    result: $.toUpper('$lastName'),
  })
  .end()

返回的结果如下：

{ "result": "DONG" }
{ "result": "WANG" }
{ "result": "LI" }