db.command.aggregate.zip

1. Operator Description

Function: Assembles elements at the same index in each sub-array of a two-dimensional array into new arrays, and then combines them to form a new two-dimensional array. For example, it can convert [ [ 1, 2, 3 ], [ "a", "b", "c" ] ] into [ [ 1, "a" ], [ 2, "b" ], [ 3, "c" ] ].

Declaration: db.command.aggregate.zip({ inputs: [array1, array2, ...], useLongestLength: boolean, defaults: array })

2. Operator Parameters

Field	Type	Required	Description
inputs	<Array>Expression	Yes	The inputs field is detailed below
useLongestLength	boolean	Yes	The useLongestLength field is detailed below
defaults	<Array>any	Yes	The defaults field is detailed below

Parameter description:

The inputs parameter is a two-dimensional array (where inputs cannot be a field reference), and each element's expression (which can be a field reference) must resolve to an array. If any expression returns null, <inputs> also returns null. If any expression does not point to a valid field / cannot be resolved to an array / cannot be resolved to null, an error is returned.

The useLongestLength parameter determines whether the output array's length should be set to the length of the longest input array. Defaults to false, meaning the length of the shortest input array determines the length of each element in the output array.

The defaults parameter is an array used to specify default values for array elements when input arrays have varying lengths. Specifying this field requires also specifying useLongestLength, otherwise an error is returned. If useLongestLength is true but defaults is empty or unspecified, zip uses null as the default value for array elements. When specifying element default values, the length of the defaults array must match the maximum length among the input arrays.

3. Sample Code

Suppose the collection stats contains the following records:

{ "_id": 1, "zip1": [1, 2], "zip2": [3, 4], "zip3": [5, 6] ] }
{ "_id": 2, "zip1": [1, 2], "zip2": [3], "zip3": [4, 5, 6] ] }
{ "_id": 3, "zip1": [1, 2], "zip2": [3] ] }

Passing Only inputs

// 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
const _ = db.command

exports.main = async (event, context) => {
  const res = await db
    .collection('items')
    .aggregate()
    .project({
      zip: $.zip({
        inputs: [
          '$zip1', // field reference
          '$zip2',
          '$zip3'
        ]
      })
    })
    .end()
  console.log(res.data)
}

The returned result is as follows:

{ "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }
{ "_id": 2, "zip": [ [1, 3, 4] ] }
{ "_id": 3, "zip": null }

Setting useLongestLength

If useLongestLength is set to true:

// 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
const _ = db.command

exports.main = async (event, context) => {
  const res = await db
    .collection('items')
    .aggregate()
    .project({
      zip: $.zip({
        inputs: [
          '$zip1', // field reference
          '$zip2',
          '$zip3'
        ],
        useLongestLength: true
      })
    })
    .end()
  console.log(res.data)
}

The returned result is as follows:

{ "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }
{ "_id": 2, "zip": [ [1, 3, 4], [2, null, 5], [null, null, 6] ] }
{ "_id": 3, "zip": null }

Setting defaults

// 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
const _ = db.command

exports.main = async (event, context) => {
  const res = await db
    .collection('items')
    .aggregate()
    .project({
      zip: $.zip({
        inputs: [
          '$zip1', // field reference
          '$zip2',
          '$zip3'
        ],
        useLongestLength: true,
        defaults: [-300, -200, -100]
      })
    })
    .end()
  console.log(res.data)
}

The returned result is as follows:

{ "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }
{ "_id": 2, "zip": [ [1, 3, 4], [2, -200, 5], [-300, -200, 6] ] }
{ "_id": 3, "zip": null }