Operator behavior
This section defines the behavior of the various M operators.
Operator precedence
When an expression contains multiple operators, the precedence of the operators controls the order in which the individual operators are evaluated. For example, the expression x + y * z
is evaluated as x + (y * z)
because the *
operator has higher precedence than the binary +
operator. The precedence of an operator is established by the definition of its associated grammar production. For example, an additiveexpression consists of a sequence of multiplicativeexpression's separated by +
or 
operators, thus giving the +
and 
operators lower precedence than the *
and /
operators.
The parenthesizedexpression production can be used to change the default precedence ordering.
parenthesizedexpression:
(
expression )
For example:
1 + 2 * 3 // 7
(1 + 2) * 3 // 9
The following table summarizes the M operators, listing the operator categories in order of precedence from highest to lowest. Operators in the same category have equal precedence.
Category  Expression  Description 

Primary  i @i 
Identifier expression 
(x)  Parenthesized expression  
x[i]  Lookup  
x{y}  Item access  
x(...)  Function invocation  
{x, y, ...}  List initialization  
[ i = x, ... ]  Record initialization  
...  Not implemented  
Unary  +x  Identity 
x  Negation  
not x 
Logical negation  
Metadata  x meta y 
Associate metadata 
Multiplicative  x * y  Multiplication 
x / y  Division  
Additive  x + y  Addition 
x  y  Subtraction  
Relational  x < y  Less than 
x > y  Greater than  
x <= y  Less than or equal  
x >= y  Greater than or equal  
Equality  x = y  Equal 
x <> y  Not equal  
Type assertion  x as y 
Is compatible nullableprimitive type or error 
Type conformance  x is y 
Test if compatible nullableprimitive type 
Logical AND  x and y 
Shortcircuiting conjunction 
Logical OR  x or y 
Shortcircuiting disjunction 
Coalesce  x ?? y 
Null coalescing operator 
Operators and metadata
Every value has an associated record value that can carry additional information about the value. This record is referred to as the metadata record for a value. A metadata record can be associated with any kind of value, even null
. The result of such an association is a new value with the given metadata.
A metadata record is just a regular record and can contain any fields and values that a regular record can, and itself has a metadata record. Associating a metadata record with a value is "nonintrusive". It does not change the value's behavior in evaluations except for those that explicitly inspect metadata records.
Every value has a default metadata record, even if one has not been specified. The default metadata record is empty. The following examples show accessing the metadata record of a text value using the Value.Metadata
standard library function:
Value.Metadata( "Mozart" ) // []
Metadata records are generally not preserved when a value is used with an operator or function that constructs a new value. For example, if two text values are concatenated using the &
operator, the metadata of the resulting text value is the empty record []
. The following expressions are equivalent:
"Amadeus " & ("Mozart" meta [ Rating = 5 ])
"Amadeus " & "Mozart"
The standard library functions Value.RemoveMetadata
and Value.ReplaceMetadata
can be used to remove all metadata from a value and to replace a value's metadata (rather than merge metadata into possibly existing metadata).
The only operator that returns results that carry metadata is the meta operator.
Structurally recursive operators
Values can be cyclic. For example:
let l = {0, @l} in l
// {0, {0, {0, ... }}}
[A={B}, B={A}]
// [A = {{ ... }}, B = {{ ... }}]
M handles cyclic values by keeping construction of records, lists, and tables lazy. An attempt to construct a cyclic value that does not benefit from interjected lazy structured values yields an error:
[A=B, B=A]
// [A = Error.Record("Expression.Error",
// "A cyclic reference was encountered during evaluation"),
// B = Error.Record("Expression.Error",
// "A cyclic reference was encountered during evaluation"),
// ]
Some operators in M are defined by structural recursion. For instance, equality of records and lists is defined by the conjoined equality of corresponding record fields and item lists, respectively.
For noncyclic values, applying structural recursion yields a finite expansion of the value: shared nested values will be traversed repeatedly, but the process of recursion always terminates.
A cyclic value has an infinite expansion when applying structural recursion. The semantics of M makes no special accommodations for such infinite expansions—an attempt to compare cyclic values for equality, for instance, will typically run out of resources and terminate exceptionally.
Selection and Projection Operators
The selection and projection operators allow data to be extracted from list and record values.
Item Access
A value may be selected from a list or table based on its zerobased position within that list or table using an itemaccessexpression.
itemaccessexpression:
itemselection
optionalitemselection
itemselection:
primaryexpression {
itemselector }
optionalitemselection:
primaryexpression {
itemselector } ?
itemselector:
expression
The itemaccessexpression x{y}
returns:
For a list
x
and a numbery
, the item of listx
at positiony
. The first item of a list is considered to have an ordinal index of zero. If the requested position does not exist in the list, an error is raised.For a table
x
and a numbery
, the row of tablex
at positiony
. The first row of a table is considered to have an ordinal index of zero. If the requested position does not exist in the table, an error is raised.For a table
x
and a recordy
, the row of tablex
that matches the field values of recordy
for fields with field names that match corresponding tablecolumn names. If there is no unique matching row in the table, an error is raised.
For example:
{"a","b","c"}{0} // "a"
{1, [A=2], 3}{1} // [A=2]
{true, false}{2} // error
#table({"A","B"},{{0,1},{2,1}}){0} // [A=0,B=1]
#table({"A","B"},{{0,1},{2,1}}){[A=2]} // [A=2,B=1]
#table({"A","B"},{{0,1},{2,1}}){[B=3]} // error
#table({"A","B"},{{0,1},{2,1}}){[B=1]} // error
The itemaccessexpression also supports the form x{y}?
, which returns null
when position (or match) y
does not exist in list or table x
. If there are multiple matches for y
, an error is still raised.
For example:
{"a","b","c"}{0}? // "a"
{1, [A=2], 3}{1}? // [A=2]
{true, false}{2}? // null
#table({"A","B"},{{0,1},{2,1}}){0}? // [A=0,B=1]
#table({"A","B"},{{0,1},{2,1}}){[A=2]}? // [A=2,B=1]
#table({"A","B"},{{0,1},{2,1}}){[B=3]}? // null
#table({"A","B"},{{0,1},{2,1}}){[B=1]}? // error
Item access does not force the evaluation of list or table items other than the one being accessed. For example:
{ error "a", 1, error "c"}{1} // 1
{ error "a", error "b"}{1} // error "b"
The following holds when the item access operator x{y}
is evaluated:
Errors raised during the evaluation of expressions
x
ory
are propagated.The expression
x
produces a list or a table value.The expression
y
produces a number value or, ifx
produces a table value, a record value.If
y
produces a number value and the value ofy
is negative, an error with reason code"Expression.Error"
is raised.If
y
produces a number value and the value ofy
is greater than or equal to the count ofx
, an error with reason code"Expression.Error"
is raised unless the optional operator formx{y}?
is used, in which case the valuenull
is returned.If
x
produces a table value andy
produces a record value and there are no matches fory
inx
, an error with reason code"Expression.Error"
is raised unless the optional operator formx{y}?
is used, in which case the valuenull
is returned.If
x
produces a table value andy
produces a record value and there are multiple matches fory
inx
, an error with reason code"Expression.Error"
is raised.
No items in x
other than that at position y
is evaluated during the process of item selection. (For streaming lists or tables, the items or rows preceding that at position y
are skipped over, which may cause their evaluation, depending on the source of the list or table.)
Field Access
The fieldaccessexpression is used to select a value from a record or to project a record or table to one with fewer fields or columns, respectively.
fieldaccessexpression:
fieldselection
implicittargetfieldselection
projection
implicittargetprojection
fieldselection:
primaryexpression fieldselector
fieldselector:
requiredfieldselector
optionalfieldselector
requiredfieldselector:
[
fieldname ]
optionalfieldselector:
[
fieldname ] ?
fieldname:
generalizedidentifier
quotedidentifier
implicittargetfieldselection:
fieldselector
projection:
primaryexpression requiredprojection
primaryexpression optionalprojection
requiredprojection:
[
requiredselectorlist ]
optionalprojection:
[
requiredselectorlist ] ?
requiredselectorlist:
requiredfieldselector
requiredselectorlist ,
requiredfieldselector
implicittargetprojection:
requiredprojection
optionalprojection
The simplest form of field access is required field selection. It uses the operator x[y]
to look up a field in a record by field name. If the field y
does not exist in x
, an error is raised. The form x[y]?
is used to perform optional field selection, and returns null
if the requested field does not exist in the record.
For example:
[A=1,B=2][B] // 2
[A=1,B=2][C] // error
[A=1,B=2][C]? // null
Collective access of multiple fields is supported by the operators for required record projection and optional record projection. The operator x[[y1],[y2],...]
projects the record to a new record with fewer fields (selected by y1
, y2
, ...
). If a selected field does not exist, an error is raised. The operator x[[y1],[y2],...]
projects the record to a new record with the fields selected by y1
, y2
, ...
; if a field is missing, null
is used instead.
For example:
[A=1,B=2][[B]] // [B=2]
[A=1,B=2][[C]] // error
[A=1,B=2][[B],[C]]? // [B=2,C=null]
The forms [y]
and [y]?
are supported as a shorthand reference to the identifier _
(underscore). The following two expressions are equivalent:
[A]
_[A]
The following example illustrates the shorthand form of field access:
let _ = [A=1,B=2] in [A] //1
The form [[y1],[y2],...]
and [[y1],[y2],...]?
are also supported as a shorthand and the following two expressions are likewise equivalent:
[[A],[B]]
_[[A],[B]]
The shorthand form is particularly useful in combination with the each
shorthand, a way to introduce a function of a single parameter named _
(for details, see Simplified declarations. Together, the two shorthands simplify common higherorder functional expressions:
List.Select( {[a=1, b=1], [a=2, b=4]}, each [a] = [b])
// {[a=1, b=1]}
The above expression is equivalent to the following more cryptic looking longhand:
List.Select( {[a=1, b=1], [a=2, b=4]}, (_) => _[a] = _[b])
// {[a=1, b=1]}
Field access does not force the evaluation of fields other than the one(s) being accessed. For example:
[A=error "a", B=1, C=error "c"][B] // 1
[A=error "a", B=error "b"][B] // error "b"
The following holds when a field access operator x[y]
, x[y]?
, x[[y]]
, or x[[y]]?
is evaluated:
Errors raised during the evaluation of expression
x
are propagated.Errors raised when evaluating field
y
are permanently associated with fieldy
, then propagated. Any future access to fieldy
will raise the identical error.The expression
x
produces a record or table value, or an error is raised.If the identifier
y
names a field that does not exist inx
, an error with reason code"Expression.Error"
is raised unless the optional operator form...?
is used, in which case the valuenull
is returned.
No fields of x
other than that named by y
is evaluated during the process of field access.
Metadata operator
The metadata record for a value is amended using the meta operator (x meta y
).
metadataexpression:
unaryexpression
unaryexpression meta
unaryexpression
The following example constructs a text value with a metadata record using the meta
operator and then accesses the metadata record of the resulting value using Value.Metadata
:
Value.Metadata( "Mozart" meta [ Rating = 5 ] )
// [Rating = 5 ]
Value.Metadata( "Mozart" meta [ Rating = 5 ] )[Rating]
// 5
The following holds when applying the metadata combining operator x meta y
:
Errors raised when evaluating the
x
ory
expressions are propagated.The
y
expression must be a record, or an error with reason code"Expression.Error"
is raised.The resulting metadata record is
x
's metadata record merged withy
. (For the semantics of record merge, see Record merge.)The resulting value is the value from the
x
expression, without its metadata, with the newly computed metadata record attached.
The standard library functions Value.RemoveMetadata
and Value.ReplaceMetadata
can be used to remove all metadata from a value and to replace a value's metadata (rather than merge metadata into possibly existing metadata). The following expressions are equivalent:
x meta y
Value.ReplaceMetadata(x, Value.Metadata(x) & y)
Value.RemoveMetadata(x) meta (Value.Metadata(x) & y)
Equality operators
The equality operator =
is used to determine if two values are equal. The inequality operator <>
is used to determine if two values are not equal.
equalityexpression:
relationalexpression
relationalexpression =
equalityexpression
relationalexpression <>
equalityexpression
For example:
1 = 1 // true
1 = 2 // false
1 <> 1 // false
1 <> 2 // true
null = true // false
null = null // true
Metadata is not part of equality or inequality comparison. For example:
(1 meta [ a = 1 ]) = (1 meta [ a = 2 ]) // true
(1 meta [ a = 1 ]) = 1 // true
The following holds when applying the equality operators x = y
and x <> y
:
Errors raised when evaluating the
x
ory
expressions are propagated.The
=
operator has a result oftrue
if the values are equal, andfalse
otherwise.The
<>
operator has a result offalse
if the values are equal, andtrue
otherwise.Metadata records are not included in the comparison.
If values produced by evaluating the
x
andy
expressions are not the same kind of value, then the values are not equal.If the values produced by evaluating the
x
andy
expression are the same kind of value, then there are specific rules for determining if they are equal, as defined below.The following is always true:
(x = y) = not (x <> y)
The equality operators are defined for the following types:
 The
null
value is only equal to itself.
null = null // true
null = true // false
null = false // false
 The logical values
true
andfalse
are only equal to themselves. For example:
true = true // true
false = false // true
true = false // false
true = 1 // false
Numbers are compared using the specified precision:
If either number is
#nan
, then the numbers are not the same.When neither number is
#nan
, then the numbers are compared using a bitwise comparison of the numeric value.#nan
is the only value that is not equal to itself.For example:
1 = 1, // true
1.0 = 1 // true
2 = 1 // false
#nan = #nan // false
#nan <> #nan // true
Two durations are equal if they represent the same number of 100nanosecond ticks.
Two times are equal if the magnitudes of their parts (hour, minute, second) are equal.
Two dates are equal if the magnitudes of their parts (year, month, day) are equal.
Two datetimes are equal if the magnitudes of their parts (year, month, day, hour, minute, second) are equal.
Two datetimezones are equal if the corresponding UTC datetimes are equal. To arrive at the corresponding UTC datetime, the hours/minutes offset is subtracted from the datetime component of the datetimezone.
Two text values are equal if using an ordinal, casesensitive, cultureinsensitive comparison they have the same length and equal characters at corresponding positions.
Two list values are equal if all of the following are true:
Both lists contain the same number of items.
The values of each positionally corresponding item in the lists are equal. This means that not only do the lists need to contain equal items, the items need to be in the same order.
For example:
{1, 2} = {1, 2} // true {2, 1} = {1, 2} // false {1, 2, 3} = {1, 2} // false
Two records are equal if all of the following are true:
The number of fields is the same.
Each field name of one record is also present in the other record.
The value of each field of one record is equal to the likenamed field in the other record.
For example:
[ A = 1, B = 2 ] = [ A = 1, B = 2 ] // true [ B = 2, A = 1 ] = [ A = 1, B = 2 ] // true [ A = 1, B = 2, C = 3 ] = [ A = 1, B = 2 ] // false [ A = 1 ] = [ A = 1, B = 2 ] // false
Two tables are equal if all of the following are true:
The number of columns is the same.
Each column name in one table is also present in the other table.
The number of rows is the same.
Each row has equal values in corresponding cells.
For example:
#table({"A","B"},{{1,2}}) = #table({"A","B"},{{1,2}}) // true #table({"A","B"},{{1,2}}) = #table({"X","Y"},{{1,2}}) // false #table({"A","B"},{{1,2}}) = #table({"B","A"},{{2,1}}) // true
A function value is equal to itself, but may or may not be equal to another function value. If two function values are considered equal, then they will behave identically when invoked.
Two given function values will always have the same equality relationship.
A type value is equal to itself, but may or may not be equal to another type value. If two type values are considered equal, then they will behave identically when queried for conformance.
Two given type values will always have the same equality relationship.
Relational operators
The <
, >
, <=
, and >=
operators are called the relational operators.
relationalexpression:
additiveexpression
additiveexpression <
relationalexpression
additiveexpression >
relationalexpression
additiveexpression <=
_relationalexpression
additiveexpression >=
relationalexpression
These operators are used to determine the relative ordering relationship between two values, as shown in the following table:
Operation  Result 

x < y 
true if x is less than y , false otherwise 
x > y 
true if x is greater than y , false otherwise 
x <= y 
true if x is less than or equal to y , false otherwise 
x >= y 
true if x is greater than or equal to y , false otherwise 
For example:
0 <= 1 // true
null < 1 // null
null <= null // null
"ab" < "abc" // true
#nan >= #nan // false
#nan <= #nan // false
The following holds when evaluating an expression containing the relational operators:
Errors raised when evaluating the
x
ory
operand expressions are propagated.The values produced by evaluating both the
x
andy
expressions must be a binary, date, datetime, datetimezone, duration, logical, number, null, text or time value. Otherwise, an error with reason code"Expression.Error"
is raised.Both operands must be the same kind of value or
null
. Otherwise, an error with reason code"Expression.Error"
is raised.If either or both operands are
null
, the result is thenull
value.Two binaries are compared byte by byte.
Two dates are compared by comparing their year parts and, if equal, their month parts and, if equal, their day parts.
Two datetimes are compared by comparing their year parts and, if equal, their month parts and, if equal, their day parts and, if equal, their hour parts and, if equal, their minute parts and, if equal, their second parts.
Two datetimezones are compared by normalizing them to UTC by subtracting their hour/minute offset and then comparing their datetime components.
Two durations are compared according to the total number of 100nanosecond ticks they represent.
Two logicals are compared such that
true
is considered to be greater thanfalse
.Two numbers
x
andy
are compared according to the rules of the IEEE 754 standard:If either operand is
#nan
, the result isfalse
for all relational operators.When neither operand is
#nan
, the operators compare the values of the two floatingpoint operands with respect to the ordering∞ < max < ... < min < 0.0 = +0.0 < +min < ... < +max < +∞
where min and max are the smallest and largest positive finite values that can be represented. The M names for ∞ and +∞ are#infinity
and#infinity
.Notable effects of this ordering are:
Negative and positive zeros are considered equal.
A
#infinity
value is considered less than all other number values, but equal to another#infinity
.A
#infinity
value is considered greater than all other number values, but equal to another#infinity
.
Two texts are compared by using a characterbycharacter ordinal, casesensitive, cultureinsensitive comparison.
Two times are compared by comparing their hour parts and, if equal, their minute parts and, if equal, their second parts.
Conditional logical operators
The and
and or
operators are called the conditional logical operators.
logicalorexpression:
logicalandexpression
logicalandexpression or
logicalorexpression
logicalandexpression:
isexpression
isexpression and
logicalandexpression
The or
operator returns true
when at least one of its operands is true
. The right operand is evaluated if and only if the left operand is not true
.
The and
operator returns false
when at least one of its operands is false
. The right operand is evaluated if and only if the left operand is not false
.
Truth tables for the or
and and
operators are shown below, with the result of evaluating the left operand expression on the vertical axis and the result of evaluating the right operand expression on the horizontal axis.
and 
true 
false 
null 
error 

true 
true 
false 
null 
error 
false 
false 
false 
false 
false 
null 
null 
false 
null 
error 
error 
error 
error 
error 
error 
or 
true 
false 
null 
error 

or 
true 
false 
null 
error 
true 
true 
true 
true 
true 
false 
true 
false 
null 
error 
null 
true 
null 
null 
error 
error 
error 
error 
error 
error 
The following holds when evaluating an expression containing conditional logical operators:
Errors raised when evaluating the
x
ory
expressions are propagated.The conditional logical operators are defined over the types
logical
andnull
. If the operand values are not of those types, an error with reason code"Expression.Error"
is raised.The result is a logical value.
In the expression
x
ory
, the expressiony
will be evaluated if and only ifx
does not evaluate totrue
.In the expression
x
andy
, the expressiony
will be evaluated if and only ifx
does not evaluate tofalse
.
The last two properties give the conditional logical operators their "conditional" qualification; properties also referred to as "shortcircuiting". These properties are useful to write compact guarded predicates. For example, the following expressions are equivalent:
d <> 0 and n/d > 1 if d <> 0 then n/d > 1 else false
Arithmetic Operators
The +
, 
, *
and /
operators are the arithmetic operators.
additiveexpression:
multiplicativeexpression
additiveexpression +
multiplicativeexpression
additiveexpression 
multiplicativeexpression
multiplicativeexpression:
metadata expression
multiplicativeexpression *
metadataexpression
multiplicativeexpression /
metadataexpression
Precision
Numbers in M are stored using a variety of representations to retain as much information as possible about numbers coming from a variety of sources. Numbers are only converted from one representation to another as needed by operators applied to them. Two precisions are supported in M:
Precision  Semantics 

Precision.Decimal 
128bit decimal representation with a range of ±1.0 x 1028 to ±7.9 x 1028 and 2829 significant digits. 
Precision.Double 
Scientific representation using mantissa and exponent; conforms to the 64bit binary doubleprecision IEEE 754 arithmetic standard IEEE 7542008. 
Arithmetic operations are performed by choosing a precision, converting both operands to that precision (if necessary), then performing the actual operation, and finally returning a number in the chosen precision.
The builtin arithmetic operators (+
, 
, *
, /
) use Double Precision. Standard library functions (Value.Add
, Value.Subtract
, Value.Multiply
, Value.Divide
) can be used to request these operations using a specific precision model.
No numeric overflow is possible:
#infinity
or#infinity
represent values of magnitudes too large to be represented.No numeric underflow is possible:
0
and0
represent values of magnitudes too small to be represented.The IEEE 754 special value
#nan
(NaN—Not a Number) is used to cover arithmetically invalid cases, such as a division of zero by zero.Conversion from Decimal to Double precision is performed by rounding decimal numbers to the nearest equivalent double value.
Conversion from Double to Decimal precision is performed by rounding double numbers to the nearest equivalent decimal value and, if necessary, overflowing to
#infinity
or#infinity
values.
Addition operator
The interpretation of the addition operator (x + y
) is dependent on the kind of value of the evaluated expressions x and y, as follows:
x  y  Result  Interpretation 

type number 
type number 
type number 
Numeric sum 
type number 
null 
null 

null 
type number 
null 

type duration 
type duration 
type duration 
Numeric sum of magnitudes 
type duration 
null 
null 

null 
type duration 
null 

type datetime 
type duration 
type datetime 
Datetime offset by duration 
type duration 
type datetime 
type datetime 

type datetime 
null 
null 

null 
type datetime 
null 
In the table, type
datetime stands for any of type date
, type datetime
, type datetimezone
, or type time
. When adding a duration and a value of some type datetime, the resulting value is of that same type.
For other combinations of values than those listed in the table, an error with reason code "Expression.Error"
is raised. Each combination is covered in the following sections.
Errors raised when evaluating either operand are propagated.
Numeric sum
The sum of two numbers is computed using the addition operator, producing a number.
For example:
1 + 1 // 2
#nan + #infinity // #nan
The addition operator +
over numbers uses Double Precision; the standard library function Value.Add
can be used to specify Decimal Precision. The following holds when computing a sum of numbers:
The sum in Double Precision is computed according to the rules of 64bit binary doubleprecision IEEE 754 arithmetic IEEE 7542008. The following table lists the results of all possible combinations of nonzero finite values, zeros, infinities, and NaN's. In the table,
x
andy
are nonzero finite values, andz
is the result ofx + y
. Ifx
andy
have the same magnitude but opposite signs,z
is positive zero. Ifx + y
is too large to be represented in the destination type,z
is an infinity with the same sign asx + y
.+ y +0 0 +∞ ∞ NaN x z x x +∞ ∞ NaN +0 y +0 +0 +∞ ∞ NaN 0 y +0 0 +∞ ∞ NaN +∞ +∞ +∞ +∞ +∞ NaN NaN ∞ ∞ ∞ ∞ NaN ∞ NaN NaN NaN NaN NaN NaN NaN NaN The sum in Decimal Precision is computed without losing precision. The scale of the result is the larger of the scales of the two operands.
Sum of durations
The sum of two durations is the duration representing the sum of the number of 100nanosecond ticks represented by the durations. For example:
#duration(2,1,0,15.1) + #duration(0,1,30,45.3)
// #duration(2, 2, 31, 0.4)
Datetime offset by duration
A datetime x
and a duration y
may be added using x + y
to compute a new datetime whose distance from x
on a linear timeline is exactly the magnitude of y
. Here, datetime stands for any of Date
, DateTime
, DateTimeZone
, or Time
and a nonnull result will be of the same type. The datetime offset by duration may be computed as follows:
If the datetime's days since epoch value is specified, construct a new datetime with the following information elements:
Calculate a new days since epoch equivalent to dividing the magnitude of y by the number of 100nanosecond ticks in a 24hour period, truncating the decimal portion of the result, and adding this value to the x's days since epoch.
Calculate a new ticks since midnight equivalent to adding the magnitude of y to the x's ticks since midnight, modulo the number of 100nanosecond ticks in a 24hour period. If x does not specify a value for ticks since midnight, a value of 0 is assumed.
Copy x's value for minutes offset from UTC unchanged.
If the datetime's days since epoch value is unspecified, construct a new datetime with the following information elements specified:
Calculate a new ticks since midnight equivalent to adding the magnitude of y to the x's ticks since midnight, modulo the number of 100nanosecond ticks in a 24hour period. If x does not specify a value for ticks since midnight, a value of 0 is assumed.
Copy x's values for days since epoch and minutes offset from UTC unchanged.
The following examples show calculating the absolute temporal sum when the datetime specifies the days since epoch:
#date(2010,05,20) + #duration(0,8,0,0)
//#datetime( 2010, 5, 20, 8, 0, 0 )
//20100520T08:00:00
#date(2010,01,31) + #duration(30,08,0,0)
//#datetime(2010, 3, 2, 8, 0, 0)
//20100302T08:00:00
#datetime(2010,05,20,12,00,00,08) + #duration(0,04,30,00)
//#datetime(2010, 5, 20, 16, 30, 0, 8, 0)
//20100520T16:30:0008:00
#datetime(2010,10,10,0,0,0,0) + #duration(1,0,0,0)
//#datetime(2010, 10, 11, 0, 0, 0, 0, 0)
//20101011T00:00:00+00:00
The following example shows calculating the datetime offset by duration for a given time:
#time(8,0,0) + #duration(30,5,0,0)
//#time(13, 0, 0)
//13:00:00
Subtraction operator
The interpretation of the subtraction operator (x  y
) is dependent on the kind of the value of the evaluated expressions x
and y
, as follows:
x  Y  Result  Interpretation 

type number 
type number 
type number 
Numeric difference 
type number 
null 
null 

null 
type number 
null 

type duration 
type duration 
type duration 
Numeric difference of magnitudes 
type duration 
null 
null 

null 
type duration 
null 

type datetime 
type datetime 
type duration 
Duration between datetimes 
type datetime 
type duration 
type datetime 
Datetime offset by negated duration 
type datetime 
null 
null 

null 
type datetime 
null 
In the table, type
datetime stands for any of type date
, type datetime
, type datetimezone
, or type time
. When subtracting a duration from a value of some type datetime, the resulting value is of that same type.
For other combinations of values than those listed in the table, an error with reason code "Expression.Error"
is raised. Each combination is covered in the following sections.
Errors raised when evaluating either operand are propagated.
Numeric difference
The difference between two numbers is computed using the subtraction operator, producing a number. For example:
1  1 // 0
#nan  #infinity // #nan
The subtraction operator 
over numbers uses Double Precision; the standard library function Value.Subtract
can be used to specify Decimal Precision. The following holds when computing a difference of numbers:
The difference in Double Precision is computed according to the rules of 64bit binary doubleprecision IEEE 754 arithmetic IEEE 7542008. The following table lists the results of all possible combinations of nonzero finite values, zeros, infinities, and NaN's. In the table,
x
andy
are nonzero finite values, andz
is the result ofx  y
. Ifx
andy
are equal,z
is positive zero. Ifx  y
is too large to be represented in the destination type,z
is an infinity with the same sign asx  y
. y +0 0 +∞ ∞ NaN x z x x ∞ +∞ NaN +0 y +0 +0 ∞ +∞ NaN 0 y 0 +0 ∞ +∞ NaN +∞ +∞ +∞ +∞ NaN +∞ NaN ∞ ∞ ∞ ∞ ∞ NaN NaN NaN NaN NaN NaN NaN NaN NaN The difference in Decimal Precision is computed without losing precision. The scale of the result is the larger of the scales of the two operands.
Difference of durations
The difference of two durations is the duration representing the difference between the number of 100nanosecond ticks represented by each duration. For example:
#duration(1,2,30,0)  #duration(0,0,0,30.45)
// #duration(1, 2, 29, 29.55)
Datetime offset by negated duration
A datetime x
and a duration y
may be subtracted using x  y
to compute a new datetime. Here, datetime stands for any of date
, datetime
, datetimezone
, or time
. The resulting datetime has a distance from x
on a linear timeline that is exactly the magnitude of y
, in the direction opposite the sign of y
. Subtracting positive durations yields results that are backwards in time relative to x
, while subtracting negative values yields results that are forwards in time.
#date(2010,05,20)  #duration(00,08,00,00)
//#datetime(2010, 5, 19, 16, 0, 0)
//20100519T16:00:00
#date(2010,01,31)  #duration( 30,08,00,00)
//#datetime(2009, 12, 31, 16, 0, 0)
//20091231T16:00:00
Duration between two datetimes
Two datetimes t
and u
may be subtracted using t  u
to compute the duration between them. Here, datetime stands for any of date
, datetime
, datetimezone
, or time
. The duration produced by subtracting u
from t
must yield t
when added to u
.
#date(2010,01,31)  #date(2010,01,15)
// #duration(16,00,00,00)
// 16.00:00:00
#date(2010,01,15) #date(2010,01,31)
// #duration(16,00,00,00)
// 16.00:00:00
#datetime(2010,05,20,16,06,00,08,00) 
#datetime(2008,12,15,04,19,19,03,00)
// #duration(521,22,46,41)
// 521.22:46:41
Subtracting t  u
when u > t
results in a negative duration:
#time(01,30,00)  #time(08,00,00)
// #duration(0, 6, 30, 0)
The following holds when subtracting two datetimes using t  u
:
 u + (t  u) = t
Multiplication operator
The interpretation of the multiplication operator (x * y
) is dependent on the kind of value of the evaluated expressions x and y, as follows:
X  Y  Result  Interpretation 

type number 
type number 
type number 
Numeric product 
type number 
null 
null 

null 
type number 
null 

type duration 
type number 
type duration 
Multiple of duration 
type number 
type duration 
type duration 
Multiple of duration 
type duration 
null 
null 

null 
type duration 
null 
For other combinations of values than those listed in the table, an error with reason code "Expression.Error"
is raised. Each combination is covered in the following sections.
Errors raised when evaluating either operand are propagated.
Numeric product
The product of two numbers is computed using the multiplication operator, producing a number. For example:
2 * 4 // 8
6 * null // null
#nan * #infinity // #nan
The multiplication operator *
over numbers uses Double Precision; the standard library function Value.Multiply
can be used to specify Decimal Precision. The following holds when computing a product of numbers:
The product in Double Precision is computed according to the rules of 64bit binary doubleprecision IEEE 754 arithmetic IEEE 7542008. The following table lists the results of all possible combinations of nonzero finite values, zeros, infinities, and NaN's. In the table,
x
andy
are positive finite values.z
is the result ofx * y
. If the result is too large for the destination type,z
is infinity. If the result is too small for the destination type,z
is zero.* +y y +0 0 +∞ ∞ NaN +x +z z +0 0 +∞ ∞ NaN x z +z 0 +0 ∞ +∞ NaN +0 +0 0 +0 0 NaN NaN NaN 0 0 +0 0 +0 NaN NaN NaN +∞ +∞ ∞ NaN NaN +∞ ∞ NaN ∞ ∞ +∞ NaN NaN ∞ +∞ NaN NaN NaN NaN NaN NaN NaN NaN NaN The product in Decimal Precision is computed without losing precision. The scale of the result is the larger of the scales of the two operands.
Multiples of durations
The product of a duration and a number is the duration representing the number of 100nanosecond ticks represented by the duration operand times the number operand. For example:
#duration(2,1,0,15.1) * 2
// #duration(4, 2, 0, 30.2)
Division operator
The interpretation of the division operator (x / y
) is dependent on the kind of value of the evaluated expressions x
and y
, as follows:
X  Y  Result  Interpretation 

type number 
type number 
type number 
Numeric quotient 
type number 
null 
null 

null 
type number 
null 

type duration 
type number 
type duration 
Fraction of duration 
type duration 
type duration 
type duration 
Numeric quotient of durations 
type duration 
null 
null 

null 
type duration 
null 
For other combinations of values than those listed in the table, an error with reason code "Expression.Error"
is raised. Each combination is covered in the following sections.
Errors raised when evaluating either operand are propagated.
Numeric quotient
The quotient of two numbers is computed using the division operator, producing a number. For example:
8 / 2 // 4
8 / 0 // #infinity
0 / 0 // #nan
0 / null // null
#nan / #infinity // #nan
The division operator /
over numbers uses Double Precision; the standard library function Value.Divide
can be used to specify Decimal Precision. The following holds when computing a quotient of numbers:
The quotient in Double Precision is computed according to the rules of 64bit binary doubleprecision IEEE 754 arithmetic IEEE 7542008. The following table lists the results of all possible combinations of nonzero finite values, zeros, infinities, and NaN's. In the table,
x
andy
are positive finite values.z
is the result ofx / y
. If the result is too large for the destination type,z
is infinity. If the result is too small for the destination type,z
is zero./ +y y +0 0 +∞ ∞ NaN +x +z z +∞ ∞ +0 0 NaN x z +z ∞ +∞ 0 +0 NaN +0 +0 0 NaN NaN +0 0 NaN 0 0 +0 NaN NaN 0 +0 NaN +∞ +∞ ∞ +∞ ∞ NaN NaN NaN ∞ ∞ +∞ ∞ +∞ NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN The sum in Decimal Precision is computed without losing precision. The scale of the result is the larger of the scales of the two operands.
Quotient of durations
The quotient of two durations is the number representing the quotient of the number of 100nanosecond ticks represented by the durations. For example:
#duration(2,0,0,0) / #duration(0,1,30,0)
// 32
Scaled durations
The quotient of a duration x
and a number y
is the duration representing the quotient of the number of 100nanosecond ticks represented by the duration x
and the number y
. For example:
#duration(2,0,0,0) / 32
// #duration(0,1,30,0)
Structure Combination
The combination operator (x & y
) is defined over the following kinds of values:
X  Y  Result  Interpretation 

type text 
type text 
type text 
Concatenation 
type text 
null 
null 

null 
type text 
null 

type date 
type time 
type datetime 
Merge 
type date 
null 
null 

null 
type time 
null 

type list 
type list 
type list 
Concatenation 
type record 
type record 
type record 
Merge 
type table 
type table 
type table 
Concatenation 
Concatenation
Two text, two list, or two table values can be concatenated using x & y
.
The following example illustrates concatenating text values:
"AB" & "CDE" // "ABCDE"
The following example illustrates concatenating lists:
{1, 2} & {3} // {1, 2, 3}
The following holds when concatenating two values using x & y
:
Errors raised when evaluating the
x
ory
expressions are propagated.No error is propagated if an item of either
x
ory
contains an error.The result of concatenating two text values is a text value that contains the value of x immediately followed by y. If either of the operands is null and the other is a text value, the result is null.
The result of concatenating two lists is a list that contains all the items of
x
followed by all the items ofy
.The result of concatenating two tables is a table that has the union of the two operand table's columns. The column ordering of
x
is preserved, followed by the columns only appearing iny
, preserving their relative ordering. For columns appearing only in one of the operands,null
is used to fill in cell values for the other operand.
Merge
Record merge
Two records can be merged using x & y
, producing a record that includes fields from both x
and y
.
The following examples illustrate merging records:
[ x = 1 ] & [ y = 2 ] // [ x = 1, y = 2 ]
[ x = 1, y = 2 ] & [ x = 3, z = 4 ] // [ x = 3, y = 2, z = 4 ]
The following holds when merging two records using x + y
:
Errors raised when evaluating the
x
ory
expressions are propagated.If a field appears in both
x
andy
, the value fromy
is used.The order of the fields in the resulting record is that of
x
, followed by fields iny
that are not part ofx
, in the same order that they appear iny
.Merging records does not cause evaluation of the values.
No error is raised because a field contains an error.
The result is a record.
Datetime merge
A date x
can be merged with a time y
using x & y
, producing a datetime that combines the parts from both x
and y
.
The following example illustrates merging a date and a time:
#date(2013,02,26) & #time(09,17,00)
// #datetime(2013,02,26,09,17,00)
The following holds when merging two records using x + y
:
Errors raised when evaluating the
x
ory
expressions are propagated.The result is a datetime.
Unary operators
The +
, 
, and not
operators are unary operators.
unaryexpression:
typeexpression
+
unary expression

unary expression
not
unary expression
Unary plus operator
The unary plus operator (+x
) is defined for the following kinds of values:
X  Result  Interpretation 

type number 
type number 
Unary plus 
type duration 
type duration 
Unary plus 
null 
`null 
For other values, an error with reason code "Expression.Error"
is raised.
The unary plus operator allows a +
sign to be applied to a number, datetime, or null value. The result is that same value. For example:
+  1 // 1
+ + 1 // 1
+ #nan // #nan
+ #duration(0,1,30,0) // #duration(0,1,30,0)
The following holds when evaluating the unary plus operator +x
:
Errors raised when evaluating
x
are propagated.If the result of evaluating
x
is not a number value, then an error with reason code"Expression.Error"
is raised.
Unary minus operator
The unary minus operator (x
) is defined for the following kinds of values:
X  Result  Interpretation 

type number 
type number 
Negation 
type duration 
type duration 
Negation 
null 
null 
For other values, an error with reason code "Expression.Error"
is raised.
The unary minus operator is used to change the sign of a number or duration. For example:
 (1 + 1) // 2
  1 // 1
   1 // 1
 #nan // #nan
 #infinity // #infinity
 #duration(1,0,0,0) // #duration(1,0,0,0)
 #duration(0,1,30,0) // #duration(0,1,30,0)
The following holds when evaluating the unary minus operator x
:
Errors raised when evaluating
x
are propagated.If the expression is a number, then the result is the number value from expression
x
with its sign changed. If the value is NaN, then the result is also NaN.
Logical negation operator
The logical negation operator (not
) is defined for the following kinds of values:
X  Result  Interpretation 

type logical 
type logical 
Negation 
null 
null 
This operator computes the logical not
operation on a given logical value. For example:
not true // false
not false // true
not (true and true) // false
The following holds when evaluating the logical negation operator not x
:
Errors raised when evaluating
x
are propagated.The value produced from evaluating expression x must be a logical value, or an error with reason code
"Expression.Error"
must be raised. If the value istrue
, the result isfalse
. If the operand isfalse
, the result istrue
.
The result is a logical value.
Type operators
The operators is
and as
are known as the type operators.
Type compatibility operator
The type compatibility operator x is y
is defined for the following types of values:
X  Y  Result 

type any 
nullableprimitivetype  type logical 
The expression x is y
returns true
if the ascribed type of x
is compatible with y
, and returns false
if the ascribed type of x
is incompatible with y
. y
must be a nullableprimitivetype.
isexpression:
asexpression
isexpression is
nullableprimitivetype
nullableprimitivetype:
nullable
_{opt} primitivetype
Type compatibility, as supported by the is
operator, is a subset of general type compatibility and is defined using the following rules:
If
x
is null then it is compatible ify
is the typeany
, the typenull
, or a nullable type.If
x
is nonnull then if it is a compatible if the the primitive type ofx
is the same asy
.
The following holds when evaluating the expression x is y
:
 An error raised when evaluating expression
x
is propagated.
Type assertion operator
The type assertion operator x as y
is defined for the following types of values:
X  Y  Result 

type any 
nullableprimitivetype  type any 
The expression x as y
asserts that the value x
is compatible with y
as per the is
operator. If it is not compatible, an error is raised. y
must be a nullableprimitivetype.
asexpression:
equalityexpression
asexpression as
nullableprimitivetype
The expression x as y
is evaluated as follows:
A type compatibility check
x is y
is performed and the assertion returnsx
unchanged if that test succeeds.If the compatibility check fails, an error with reason code
"Expression.Error"
is raised.
Examples:
1 as number // 1
"A" as number // error
null as nullable number // null
The following holds when evaluating the expression x as y
:
 An error raised when evaluating expression
x
is propagated.
Coalesce operator
The coalesce operator ??
returns the result of its left operand if it is not null, otherwise it will return the result of its right operand. The right operand is evaluated if and only if the left operand is null.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for