m3ter Calculation Engine

• Supported Operators, Variables, Functions, and Type Casts
• Calculation Contexts

​

Supported Operators, Variables, Functions, and Type Casts

• Operators
• Variables
• Functions
• Date Time Functions
• Type Casts
• String Functions

​

Operators

• Arithmetic Operators: + - * / ^
• Unary Operators: + -
• Precedence: ( )
• Equality: == != < > <= >=
• Modulo: %
• Ternary: ? :
• Logical AND: AND
• Logical OR: OR

​

Variables

• null
• true
• false
• Math.PI
• DateTime.TS_FMT - Has the value of "yyyy-MM-dd'T'HH:mm:ss.SSSX".

​

Functions

• Math.max() Supports 2 to many arguments.
• Math.min() Supports 2 to many arguments.
• Math.floor() Supports 2 arguments - returns the greatest integer less than or equal to the argument.
  • Second parameter is optional to control scale - see below for explanation and examples.
• Math.ceil() Supports 2 arguments - returns the least integer greater than or equal to the argument.
  • Second parameter is optional to control scale - see below for explanation and examples.
• Math.round() Supports 2 arguments - returns the nearest integer to the argument. Note that half-number values are rounded up.
  • For example, Math.round(2.5) returns 3.
  • Second parameter is optional to control scale - see below for explanation and examples.
• Math.pow() Exactly two arguments - returns the value of the first raised to the power of the second.
• Math.abs() Supports 1 argument - returns the absolute value of a number.
  • For example, Math.abs(-2) returns 2.
• isnull() Exactly two arguments - returns 1st argument if it’s not null; 2nd argument if it is null - same as in SQL.
• IN() Takes multiple arguments. Can be used with the ternary operator to return TRUE if any of the arguments are satisfied, otherwise return FALSE:
  • For example, IN("completed", "succeeded") ? "true" : "false"

​

Scale Parameter for Math Functions

• Positive scales define the number of decimal points, while negative scales define the magnitude of the result in powers of ten:
  • A scale of 2 would round to 2 decimal places.
  • A scale of -2 would round to the nearest 100.
  • A scale of 0 means round to the nearest whole number or, in other words, 0 decimal places, which is the existing behavior when scale is not specified.
• Examples:
  • Math.round(123.456, 2) would result in 123.45
  • Math.round(123.456, 0) would result in 123
  • Math.round(123.456, -2) would result in 100

​

Date Time Functions

• Core Date Time Functions
• Date Time Format Functions

​

Core Date Time Functions

• DateTime.dateAdd(datetime, interval, unit) Adds a period of time to a date time.
  • datetime: ISO date time.
  • interval: amount of unit to add.
  • unit: time unit, such as YEARS, MONTHS, WEEKS, DAYS, HOURS, MINUTES, SECONDS, or MILLIS.
    • Returns a date time in ISO. For example: DateTime.dateAdd("2025-04-01T14:00:00.000Z", 2, "HOURS") will return "2025-04-01T16:00:00.000Z".
• DateTime.dateSub(datetime, interval, unit) Subtracts a period of time from a date time.
  • datetime: ISO date time.
  • interval: amount of unit to subtract
  • unit: time unit, such as YEARS, MONTHS, WEEKS, DAYS, HOURS, MINUTES, SECONDS, or MILLIS.
    • Returns a date time in ISO. For example: DateTime.dateSub("2025-04-01T16:00:00.000Z", 2, "HOURS") will return "2025-04-01T14:00:00.000Z".
• DateTime.dateDiff(start, end, unit) Calculates the differences in time between start and end in the defined time unit.
  • start: ISO start date time.
  • end: ISO end date time.
  • unit: time unit, such as YEARS, MONTHS, WEEKS, DAYS, HOURS, MINUTES, SECONDS, or MILLIS.
    • Returns a date time in ISO. For example: DateTime.dateDiff("2025-04-01T14:00:00.000Z", "2025-04-01T16:00:00.000Z", "HOURS") will return 2.
• DateTime.convertTz(datetime, fromZone, toZone)
  • datetime: ISO date time.
  • fromZone and toZone: Timezone ids.
    • Use this function to convert a date time from one time zone to another. For example: DateTime.convertTz("2025-04-01T14:00:00.000Z", "UTC", "America/New_York") will return 2025-04-01T10:00:00.000-04:00.
• DateTime.eoMonth(datetime, offset)
  • datetime: ISO date time.
  • offset: Specifies the number of months to offset the calculation by. (Optional)
    • Use this function to get the date time at the start of the day of the end of the month the datetime is in. For example: DateTime.eoMonth("2025-04-01T14:00:00.000Z", 2) will return "2025-06-30T00:00:00.000Z".
• DateTime.dayOfWeek(datetime)
  • datetime: ISO date time.
    • Use this function to get the indexed day of the week for the datetime. By default, weeks run Monday to Monday. For example: DateTime.dayOfWeek("2025-05-28T14:00:00.000Z") will return 3, because May 28th, 2025 is a Wednesday.
• DateTime.isoWeekOfYear(datetime)
  • datetime: ISO date time.
    • Use this function to return the ISO week date the datetime is in. Uses the ISO 8601 week date definition for ordinal weeks of a year. See ISO week date for more details. For example: DateTime.isoWeekOfYear("2025-05-28T14:00:00.000Z") will return 22, because May 28th, 2025 falls in the 22nd week of 2025 according to the ISO week date standard.
• DateTime.isoStartOfWeek(datetime, startOfWeek)
  • datetime: ISO date time.
  • startOfWeek: Index of the day you want the week to start on. By default, weeks run Monday to Monday. Using 7 for startOfWeek would define Sunday as the start of the week. (Optional)
    • Use this function to return the date time at the start of the week the datetime parameter falls in. For example: DateTime.isoStartOfWeek("2025-05-28T14:00:00.000Z", 7) will return "2025-05-25T00:00:00.000Z", because startOfWeek = 7 means weeks start on a Sunday.
• DateTime.daysInMonth(datetime)
  • datetime: ISO date time.
    • Use this function to return the number of days in the month the datetime falls in. For example: DateTime.daysInMonths("2025-06-28T14:00:00.000Z") will return 30 because the month of June has 30 days.
• DateTime.secondsOverlap
  • startDateTime: ISO date time.
  • endDateTime: ISO date time.
  • startTime: ISO date time.
  • endTime: ISO date time.
  • Use this function to calculate the total number of seconds of overlap between a given date time range - startDateTime to endDateTime - and a time period - startTime to endTime. For example, suppose you offer a discount rate for service consumption during “off-peak” hours, that is any consumption on any given day that is outside the peak hours of 06:00:00 until 22:00:00:
    • If the overall period of consumption is from a startDateTime of 2025-03-23 23:00:00 until an endDateTime of 2025-03-25 09:12:34, then with a startTime of 06:00:00 and an endTime of 22:00:00 the function will return the calculated overlap as:
      • March 23rd: Overlap from 23:00:00 to 00:00:00 = 1 hour
      • March 24th: Overlap from 00:00:00 to 06:00:00 = 6 hours and from 22:00:00 to 00:00:00 = 2 hours, giving a total of 8 hours.
      • March 25th: Overlap from 00:00:00 to 06:00:00 = 6 hours.
    • The total overlap is therefore 1 + 8 + 6 = 15 hours, which = 54000 seconds.

​

Date Time Format Functions

• DateTime.dateStringFormat(datetime, oldFormat, newFormat)
  • datetime: Parsed as a string so doesn’t have to be ISO but has to match the format of oldFormat.
  • oldFormat: date time format string.
  • newFormat: date time format string.
    • You can use this function to obtain a single field from a date time, such as getting the day or month. For example: DateTime.dateFormat("2025-04-01", "YYYY-MM-DD", "MM") will return  "04".
    • You can also use this function to change a date time format, such as changing the month format. For example: DateTime.dateFormat("2025-04-01", "YYYY/MM/DD", "YYYY-MM-DD")
    • IMPORTANT! However, you cannot change a date time format to one where a string not present in oldFormat is added into newFormat. For example: DateTime.dateFormat("2025-04-01", "YYYY/MM/DD", "YYYY-MM-DDTHH:mm:ss") will not work since HH, mm, or ss are not present in the oldFormat.
• DateTime.dateFormat(datetime, newFormat)
  • datetime: ISO date time.
  • newFormat: date time format string.
    • Use this function to obtain a single field from a date time, such as getting the day or month. For example: DateTime.dateFormat(ts, "MM") for a usage measurement ingested into m3ter during April would return "04".
  • Formatting for the DateTime.dateFormat function:
    • In m3ter, the format of date times used - for example for the Timestamp ts field in usage data measurements - is "yyyy-MM-dd'T'HH:mm:ss.SSSX". The following table gives some examples of these format strings:

​

Type Casts

• String() Supports 1 argument.
• Number() Supports 1 argument.
• Boolean() Supports 1 argument.

​

String Functions

• String.left() Supports 2 arguments - 1 string and 1 numeric. Returns a string containing a specified number of characters from the left side of a string.
  • For example: String.left("Test", 2) will return "Te"
• String.right() Supports 2 arguments - 1 string and 1 numeric. Returns a string containing a specified number of characters from the right side of a string.
  • For example: String.right("Test", 2) will return "st"
• String.upper() Supports 1 string argument. Returns a string of all uppercase characters.
  • For example: String.upper("Test") will return "TEST"
• String.lower() Supports 1 string argument. Returns a string of all lowercase characters.
  • For example: String.lower("Test") will return "test"
• String.replace() Supports 3 string arguments. Returns a new string in which all occurrences of a specified character or string in the current string are replaced with another specified character or string.
  • For example: String.replace("Test replace", "replace", "worked") will return "Test worked"
• String.length() Supports 1 string argument. Returns a numeric count of all characters in a string.
  • For example: String.length("Test") will return 4
• String.substring() Supports 2 or 3 arguments.
  • If 2 arguments, the substring starts at a specified character position and continues to the end of the string.
    • For example: String.substring("Test", 1) will return ”est"
  • If 3 arguments, the substring starts at a specified start index and continues to the specified end index.
    • For example: String.substring("Test", 1, 3) will return ”es"
• String.contains() Supports 2 string arguments. Returns a boolean result if the first string contains the second string.
  • For example: String.contains("Test", "es") will return true
• String.indexOf() Supports 2 or 3 arguments.
  • If 2 arguments, returns the zero-based index of the first occurrence of a specified character or string within the first string. The method returns -1 if the character or string is not found in this instance.
    • For Example: String.indexOf("Test", "e") will return 1
  • If 3 arguments, returns the zero-based index of the first occurrence of a specified character or string within the first string, starting from the specified index. The method returns -1 if the character or string is not found in this instance.
    • For example: String.indexOf("test", "t", 1) will return 3
• String.trim() Supports 1 string argument. Returns a new string in which all leading and trailing spaces from the current string are removed.
  • For example: String.trim(" Test ") will return "Test"

​

Calculation Contexts

• Meter Derived Fields. See Working with Meter Derived Fields and Examples.
• Compound Aggregations. See Working with Compound Aggregation Calculations and Compound Aggregations - Examples.
• Notification Rules. See Creating Calculations in the Utilizing Events and Notifications section.