m3ter Calculation Engine - m3ter Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

You can exploit the m3ter platform’s powerful Calculation Engine as you create calculations for Meter Derived Fields, Compound Aggregations, or Notification Rules. This topic gives details of the supported operators, variables, functions, and type casts available in the m3ter Calculation Engine. Links out to other topics giving specific details and examples of the various calculation contexts are also given:

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

Supported Operators, Variables, Functions, and Type Casts

Standard mathematical syntax and operators are supported:

• 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

For the Math.ceil(), Math.floor(), and Math.round() functions, you can use a second optional parameter to control scale:

• 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 startTimeof 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

Two date time format functions are available:

• 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

You can use the platform’s Calculation Engine when you create calculations in various 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.