Aggregate.dateToString

1. Operator Description

Function: Converts a date/time string to a date object.

Declaration: db.command.aggregate.dateToString({date: <date expression>,format: <format expression>,timezone: <timezone expression>,onNull: <null value expression> })

2. Operator Parameters

Field	Type	Required	Description
date	string	Required	Date expression
format	string	No	Format expression
timezone	string	No	Timezone expression
onNull	string	No	Null value expression

The following is a detailed description of the four expressions:

Name	Description
Date expression	Required. Specifies that the field value should be a date that can be converted to a string.
Format expression	Optional. It can be any valid string containing "format specifiers".
Timezone expression	Optional. Specifies the time zone for the operation result. It can parse strings in the format of UTC Offset or Olson Timezone Identifier.
Null value expression	Optional. Returns the value specified by this expression when the <Date expression> returns null or does not exist.

The following is a detailed description of format specifiers:

Specifier	Description	Valid Values
%d	Day of the month (2-digit, zero-padded)	01 - 31
%G	Year in ISO 8601 format	0000 - 9999
%H	Hour (2-digit, zero-padded, 24-hour clock)	00 - 23
%j	Day of the year (3-digit, zero-padded)	001 - 366
%L	Milliseconds (3-digit, zero-padded)	000 - 999
%m	Month (2-digit, zero-padded)	01 - 12
%M	Minutes (2-digit, zero-padded)	00 - 59
%S	Seconds (2-digit, zero-padded)	00 - 60
%w	Day of the week	1 - 7
%u	Day of the week in ISO 8601 format	1 - 7
%U	Week of the year (2-digit, zero-padded)	00 - 53
%V	Week of the year in ISO 8601 format	1 - 53
%Y	Year (4-digit, zero-padded)	0000 - 9999
%z	Time zone offset from UTC	+/-[hh][mm]
%Z	Time zone offset from UTC in minutes	+/-mmm
%%	Literal percent sign	%

3. Sample Code

Suppose the collection students contains the following records:

{ "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" }

Formatting Dates

Below is the formatting of the date field's value into a string in the pattern year-month-day:

// Sample code in the Cloud Function environment
const tcb = require('@cloudbase/node-sdk')
const app = tcb.init({
  env: 'xxx'
})

const db = app.database()
const $ = db.command.aggregate

exports.main = async (event, context) => {
  const res = await db
    .collection('students')
    .aggregate()
    .project({
      _id: 0,
      formatDate: $.dateToString({
        date: '$date',
        format: '%Y-%m-%d'
      })
    })
    .end()
  console.log(res.data)
}

The returned result is as follows:

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

Time Zone Time

Below is an example of formatting the date field value to Shanghai time zone time:

// Sample code in the Cloud Function environment
const tcb = require('@cloudbase/node-sdk')
const app = tcb.init({
  env: 'xxx'
})

const db = app.database()
const $ = db.command.aggregate

exports.main = async (event, context) => {
  const res = await db
    .collection('students')
    .aggregate()
    .project({
      _id: 0,
      formatDate: $.dateToString({
        date: '$date',
        format: '%H:%M:%S',
        timezone: 'Asia/Shanghai'
      })
    })
    .end()
  console.log(res.data)
}

The returned result is as follows:

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

Default Value for Missing Cases

When the specified <Date expression> returns null or does not exist, you can set a default value for missing cases:

// Sample code in the Cloud Function environment
const tcb = require('@cloudbase/node-sdk')
const app = tcb.init({
  env: 'xxx'
})

const db = app.database()
const $ = db.command.aggregate

exports.main = async (event, context) => {
  const res = await db
    .collection('students')
    .aggregate()
    .project({
      _id: 0,
      formatDate: $.dateToString({
        date: '$empty',
        onNull: 'null'
      })
    })
    .end()
  console.log(res.data)
}

The returned result is as follows:

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