Add Field
Add Field
This stage will add a new field to your document. This stage is used extensively in conjunction with the mongoDB Aggregation Pipeline Operators (https://www.mongodb.com/docs/manual/reference/operator/aggregation/). We also have a maths engine running here to help try simplifying the syntax for you. Please see the examples below to help illustrate this.
Title
This is the field name you would like to add
Parent Field
if the field needs to be added inside another node, the parent field name must be added here. The field finder can help you here. EG: if you want to add a field “UnitCode” inside a node called “Lines”, the title will be “UnitCode”, and the parent field name will be “Lines”. The transform stage will now add “UnitCode” to each “Line” entry.
ADD ALIAS
big documents can mean long field names. Creating an Alias for the field names can often mean a much simpler expression. If you add an Alias, give you field name an Alias e.g.: “A” then select your field name. Now in your expression, instead of writing out the full field name, you can simply use the notation “A” and the substitution for the full field name will be take care of by Utopia.
Expression
This is where you write the expression you need to enrich the field data you will be adding. It could be as simple as just adding a string ‘new field’ to a more complex aggregation stage. Let’s say I have set 3 Alias (A, B and C). I could use some maths calculations and set the expression as A*B+C or (A-B)/C, the maths engine will understand * + - / ( ) characters. You can also add in some aggregation stages for example sum(A) this will some the values in A, or cond(A==B,ifNull(C,’10’),A*B) à This is a bit more complex but essentially follows the cond aggregation stage written in easier syntax. So, this is saying we want a condition where if A equals B, then use the value of C unless C is null, then use 10. If A does not equal B then use A multiplied by B. end of condition. Please see our examples section to see more examples. Add Field functions (any function not seen here is available via the JSON stage):
Returns the absolute value of a number.
abs(A)
A = Value
Returns the arccosine (inverse cosine) of a number.
acos(A)
A = Value
Returns the inverse hyperbolic cosine of a number.
acosh(A)
A = Value
Adds two numbers together.
add(A, B)
A = Value, B = Value
Adds elements to an array if not already present.
addToSet(A, B)
A = array field, B = Value
Returns true if all elements in an array are true.
allElementsTrue( A)
A = array expression
Performs a logical AND operation on expressions.
and(A, B, ...)
A = Value/Expression1, B = Value/Expression2
Returns true if any element in an array is true.
anyElementTrue( A)
A = array expression
Returns an element at a specified position.
arrayElemAt(A, B)
A= arrayExpression, B = Index
Converts an array into an object.
arrayToObject( A)
A= arrayexpression
Returns the arcsine (inverse sine) of a number.
asin(A)
A = Value
Returns the inverse hyperbolic sine of a number.
asinh(A)
A = Value
Returns the arctangent (inverse tangent) of a number.
atan(A)
A = Value
Returns the arctangent of a quotient of two numbers.
atan2(A,B)
A = Value, B = Value
Returns the inverse hyperbolic tangent of a number.
atanh(A)
A = Value
Calculates the average value of an array.
avg( A)
A = arrayExpression
Returns the size of a BSON object in bytes.
binarySize( A)
A = Value
Returns the size of a BSON object in bytes.
bsonSize( A)
A = Value
Rounds a number up to the nearest whole number.
ceil(A)
A = Value
Compares two values and returns -1, 0, or 1.
cmp(A, B)
A = Value, B = Value
Concatenates strings.
concat(A, B, ...)
A = Value, B = Value
Concatenates arrays.
concatArrays(A, B, ...)
A = Array1, B = Array2
Conditional operation with a ternary-like syntax.
cond( if( <condition>, then(A), else( B ))
A = Value, B = Value
Returns the cosine of a number.
cos(A)
A = Value
Returns the hyperbolic cosine of a number.
cosh(A)
A = Value
Extracts the day of the month from a date.
dayOfMonth(A)
A = DateExpression
Extracts the day of the week from a date.
dayOfWeek(A)
A = DateExpression
Extracts the day of the year from a date.
dayOfYear(A)
A = DateExpression
Converts degrees to radians.
degreesToRadians(A)
A = angleExpression
Divides two numbers.
divide(<dividend>, <divisor>)) ; divide(A,B)
A = Value, B = Value
Checks if two values are equal.
eq(A, B)
A = Value, B = Value (Value must be > 0)
Returns the exponential value of a number.
exp(A)
A = Value
Returns the first element of an array.
first(A)
A = arrayExpression
Rounds a number down to the nearest whole number.
floor(A)
A = value
Checks if one value is greater than another.
gt(A, B)
A = Value, B = Value
Checks if one value is greater than or equal to another.
gte(A, B)
A = Value, B = Value
Extracts the hour from a date.
hour(A)
A = DateExpression
Returns a specified value if the expression is null.
ifNull(A, B)
A = field, B = replacementValue
Checks if a value matches any value in an array.
in(A, B)
A = Value, B = arrayExpression
Returns the index of an element in an array.
indexOfArray( A, B, C (Start - Optional) , D (End - Optional))
A = arrayExpression, B = Value, C is starting index position for the serach (Optional), D is the ending index position for the search
Checks if a value is an array.
isArray( A)
A = Array/Expression
Checks if a value is a number.
isNumber( A)
A = Value/Expression
Returns the ISO day of the week from a date.
isoDayOfWeek(A)
A = An expression that resolves to a Date, a Timestamp, or an ObjectID
Returns the ISO week of the year from a date.
isoWeek(A)
A = An expression that resolves to a Date, a Timestamp, or an ObjectID
Returns the ISO week-based year from a date.
isoWeekYear(A)
A = An expression that resolves to a Date, a Timestamp, or an ObjectID
Returns the last element of an array.
last( A)
A = any valid expression as long as it resolves to an array, null, or missing
Returns a value without parsing it as an expression.
literal( A)
A = Value
Returns the natural logarithm of a number.
ln(A)
A = Number
Returns the logarithm of a number to a specified base.
log( A, B )
A = Number, B = BaseExpression
Returns the base-10 logarithm of a number.
log10(A)
A = Number
Checks if one value is less than another.
lt(A, B)
A = Value1, B = Value2
Checks if one value is less than or equal to another.
lte(A, B)
A = Value1, B = Value2
Removes leading whitespace from a string.
ltrim(A, B )
A = Expression that resolves to string, B = Optional. The character(s) to trim from the beginning of the input
Applies an expression to each element of an array.
map(A, as(B), in(C))
A = An expression that resolves to an array, B = Optional. A name for the variable that represents each individual element of the input array. If no name is specified, the variable name defaults to this, C = An expression that is applied to each element of the input array. The expression references each element individually with the variable name specified in as.
Returns the highest value in an array.
max( A)
A = ArrayExpression
Returns the lowest value in an array.
min( A)
A = ArrayExpression
Extracts milliseconds from a date.
millisecond(A)
A = DateExpression
Extracts minutes from a date.
minute(A)
A = DateExpression
Calculates the remainder of a division.
mod(A, B)
A = dividend, B = divisor
Extracts the month from a date.
month(A)
A = DateExpression
Multiplies two numbers.
multiply(A, B)
A = Value1, B = Value2
Checks if two values are not equal.
ne(A, B)
A = Value1, B = Value2
Negates a boolean value.
not( A)
A = BooleanValue
Converts an object to an array of key-value pairs.
objectToArray(A)
A = any valid expression as long as it resolves to a document object
Performs a logical OR operation on expressions.
or(A, B, ...)
A = Expression1 , B = Expression2
Raises a number to a power.
pow(A, B)
A = Value , B = Exponent
Converts radians to degrees.
radiansToDegrees( <angleExpression>)
A = any valid expression that resolves to a number
Generates a sequence of numbers.
range(A, B, C)
A = Any valid expression that resolves to an Integer, B = doesn't take any arguments, C = Optional. An integer that specifies the increment value. Can be any valid expression that resolves to a non-zero integer. Defaults to 1.
Reverses the order of elements in an array.
reverseArray( A)
A = arrayExpression
Rounds a number to the nearest integer.
round(A, B)
A = value, B = Optional.Decimal Places - Defaults to 0 if unspecified
Extracts seconds from a date.
second(A)
A = DateExpression
Returns the difference between two sets. Takes two sets and returns an array containing the elements that only exist in the first set
setDifference(A, B)
A = Array1, B = Array2
Checks if two sets are equal.
setEquals(A,B)
A = Array1, B = Array2
Returns the intersection of two sets.
setIntersection(A,B)
A = Array1, B = Array2
Checks if one set is a subset of another.
setIsSubset(A,B)
A = Array1, B = Array2
Returns the union of two sets.
setUnion(A,B)
A = Array1, B = Array2
Returns the number of elements in an array.
size( A)
A = Array
Returns the sine of a number.
sin(A)
A = value
Returns the hyperbolic sine of a number.
sinh(A)
A = value
Returns a subset of an array.
slice( A, B, C )
A = Array, B = Optional Value, C = Any valid expression as long as it resolves to an integer
Splits a string into an array of substrings.
split(A,"a")
A = String Expression, "a" = Delimiter
Returns the square root of a number.
sqrt(A)
A = Value
Calculates the population standard deviation.
stdDevPop(A)
A = Value
Calculates the sample standard deviation.
stdDevSamp( A)
A = Value
Compares two strings without case sensitivity.
strcasecmp(A, B)
A = StringExpression1, B = StringExpression1
Calculates the length of a string in bytes.
strLenBytes( A)
A = StringExpression
Calculates the length of a string in code points.
strLenCP( A)
A = StringExpression
Extracts a substring from a string.
substr(A, B, C )
A = StringExpression, B = StartPosition, C = Length
Extracts a substring in bytes from a string.
substrBytes(A, B, C )
A = StringExpression, B = StartPosition, C = Length
Extracts a substring in code points from a string.
substrCP(A, B, C )
A = StringExpression, B = StartPosition, C = Length
Subtracts one number from another.
subtract(A, B)
A = Value, B = Value
Calculates the sum of an array of numbers.
sum( A)
A = Value
Returns the tangent of a number.
tan(A)
A = Value
Returns the hyperbolic tangent of a number.
tanh(A)
A = Value
Converts a value to a boolean.
toBool( A)
A = Value
Converts a value to a date.
toDate( A)
A = Value
Converts a value to a decimal.
toDecimal( A)
A = Value
Converts a value to a double.
toDouble( A)
A = Value
Converts a value to an integer.
toInt( A)
A = Value
Converts a value to a long.
toLong( A)
A = Value
Converts a value to an ObjectId.
toObjectId( A)
A = Value
Converts a value to a string.
toString( A)
A = Value
Converts a string to lowercase.
toLower(A)
A = StringExpression
Converts a string to uppercase.
toUpper(A)
A = StringExpression
Truncates a number to an integer.
trunc(A)
A = Value
Returns the BSON data type of a value.
type( A)
A = Expression
Extracts the week of the year from a date.
week(A)
A = DateExpression
Extracts the year from a date.
year(A)
A = DateExpression
Last updated