• Home
/
• Setting Up Usage Data: Meters and Aggregations

Derived Fields for Meters - Examples and Syntax

The values of a Derived Field are not raw usage data values but always the result of a calculation or function performed on Meter Data Fields, Custom Fields, or Timestamp Fields as source fields. Derived Fields add a very powerful extra dimension of flexibility for setting up the data on which your usage-based pricing plans will be based.

This topic offers some examples of Derived Field calculations. Please run through the first example as a starter, which shows both the Console setup for the field and the JSON body schema to create the field using a Create Meter API call. Other examples simply give the calculation for the Derived Field.

In addition to concrete examples, the final section in this topic:

• Links you out to a topic on supported syntax and functions for your Derived Field calculations.

• Explains how to reference Custom Fields and system timestamp fields in your Derived Field calculations.

Derived Field - Examples Using Data Fields

• Example 1 - Gigabytes/second measure

• Example 2 - Convert GB to MB measure

• Example 3 - Convert GB and KB to MB measure

• Example 4 - MB-mins measure

• Example 5 - String Derived Field operations

• Example 6 - Derived Fields for Product Add-Ons

Example 1 - Gigabytes/second measure

Description and Console Setup

Suppose you run a cloud service which offers your end customers computing capabilities. To implement this service, you want to charge for Products that your end customers consume on the basis of a usage measure in Gigabyte-seconds of processing. To set this up, you can first create two Data Fields of type Measure on a Product Meter that ingest raw data measures:

• A Memory MB field, which represents the amount of memory in megabytes allocated to the compute function.

• A Duration field, which represents the length of time the compute function ran for in milliseconds.

You can then create a Derived Field of type Measure on your Product Meter that:

• Converts the input to Memory MB, which is in Megabytes (unit: MiBy), to Gigabytes simply by dividing by 1024.

• Converts the input to Duration, which is in milliseconds (unit: ms), to seconds simply by dividing by 1000.

• Multiplies the memory allocation in GiBy by the duration value in secs to give a measure in Gigabyte-seconds (unit: GiBy.s):

You can now use this Meter's GB Second Derived Field as the basis for setting up an Aggregation for pricing your Product Plans.

Setup using API Call

If you want to create this Meter with the same Data and Derived Fields using an API call, please see our API Reference Create Meter page. Here's the JSON using this call for the example:

1
{
2
   "data": [
3
       {
4
           "id": "3ddfea4b-XXXX-467d-XXXX-b6YYYYYYYYYf",
5
           "version": 1,
6
           "productId": "1b364e59-e32b-4fbf-bc1e-91b5fc4872e5",
7
           "name": "Compute Execution",
8
           "code": "compute_execution",
9
           "dataFields": [
10
               {
11
                   "category": "MEASURE",
12
                   "code": "memory_mb",
13
                   "name": "Memory MB",
14
                   "unit": "MiBy"
15
               },
16
               {
17
                   "category": "MEASURE",
18
                   "code": "duration_ms",
19
                   "name": "Duration",
20
                   "unit": "ms"
21
               }
22
           ],
23
           "derivedFields": [
24
               {
25
                   "category": "MEASURE",
26
                   "code": "gb_second",
27
                   "name": "GB second",
28
                   "unit": "GiBy.s",
29
                   "calculation": "(memory_mb/1024)*(duration_ms/1000)"
30
               }
31
           ]
32
       }
33
   ]
34
}

Example 2 - Convert GB to MB measure

If you have a Data Field on your Meter that measures gigabytes stored - field code is gigabytes_stored - and you require a megabytes stored measure, then you can create a Measure Derived Field and use:

Calculation: gigabytes_stored*1024

Example 3 - Convert GB and KB to MB measure

Suppose you have a Meter with two Measure Data Fields for:

• Gigabytes stored: gigabytes_stored

• Kilobytes stored: kilobytes_stored

If you require a megabytes stored measure that combines these two, then you can create a Measure Derived Field and use:

Calculation: (gigabytes_stored*1024) + (kilobytes_stored/1024)

Example 4 - MB-mins measure

Suppose you have a Meter with two Measure Data Fields for:

• Stored volume of data in megabytes at point of last backup: lastbackup_size

• Duration since last backup was made in minutes: lastbackup_duration

If you require a MB-mins measure, you can create a Measure Derived Field and use:

Calculation: lastbackup_size * lastbackup_duration

Example 5 - String Derived Field operations

You can create string Derived Fields which reference Data Fields. Here's some examples.

Concatenation

Suppose you have two string Data Fields on a Meter:

• Location, which is a Where field used to identify the country of residence of your customers.

• Type, which is a What field used to identify the type of data check you are performing on your customers.

However, you want a field that combines both these string data types - Location Type. To do this, you can use the + operator in a Derived Field calculation to concatenate the two string fields:

Cast Numeric to String

If you need to cast a numeric Data Field as a string to give a string Derived field, you can do this:

Example 6 - Derived Fields for Product Add-Ons

Suppose you offer a service to manage and process orders and deliveries for online retailers. Your basic pricing model uses a tiered structure on number of orders/deliveries you handle per billing period. You also want to include some product add-ons, which customers can select for on an order-by-order basis. Pricing for an add-on will use a simple unit price model - each billing period customers are charged a fixed price per add-on consumed.

To meet this pricing use case, you can create a Derived Field that uses the 3-argument ? : ternary operator. This operator evaluates a boolean statement as first argument and yields one value if the statement is TRUE, another value if the statement is FALSE.

In this example:

• We have a string Data Field on a Meter of type What called packaging_design.

• We then create a Derived Field called package_addon of type Measure, which uses a calculation that references this Data Field:

Calculation: packaging_design=="yes"?1:0

• When an order is placed for processing that takes the add-on, yes is entered in the packaging_design field.

The calculation evaluates the first argument to return TRUE or FALSE:

• If the value of packaging_design is yes, then the statement is TRUE and the value of package_addon is 1.

• If the value of packaging_design is not yes, then the statement is FALSE and the value of the package_addon is 0.

For pricing, we can now set up an Aggregation that uses the package_addon Derived Field as its target field, and then select SUM for the Aggregation method.

We can extend this example to show how Derived Fields can be used for use cases where you want to price for a combination of product add-ons. Suppose you want to price when an order you process has opted for an express package delivery and gift packaging as a combined product add-on. You can set up two string Data Fields on a Meter of type What:

• packaging_express

• packaging_gift

You can then use a calculation for a Derived Field of type Measure called package_addon2 that references these two Data Fields and employs a nested ternary operator:

Calculation: packaging_express=="yes"?(packaging_gift=="yes"?1:0):0

How does this work?

• The nested expression in brackets is evaluated, which will result in 1 only if packaging_gift has a value of yes.

• The main expression is then evaluated and results in 1 only if packaging_express has a value of yes and the nested expression has returned a value of 1. If the nested expression has returned 0, then the main expression will return 0, regardless of whether packaging_express has a value of yes or any other value - that is, is either TRUE or FALSE.

We can therefore see how this form of calculation is useful when we want to price for multiple product addons as a bundled addon - only if all referenced Data Fields have a value of yes does the Derived Field have a value of 1 returned.

Derived Field Calculations - Supported Syntax and Referencing Fields

You are not restricted to referencing Meter Data Fields in your Derived Field calculations. You can also reference Custom Fields and Timestamp Fields, which greatly extends the scope of measures available as the basis for Aggregations used for pricing your Product Plans.

For details of the syntax and supported functions and operators in calculations, see Calculations Syntax and Supported Functions/Operators.

Referencing Custom Fields

Any Custom Fields you have defined at either the Organizational Level or at the level of an individual item can be referenced in a Derived Field calculation. The default value defined at the Organization level will be used if there is not a specific value defined on the relevant item. For example, the Custom Field value defined on the specific meter referenced by the measurement will be used if it exists, otherwise the default value defined for a Meter at the Organizational level will be used:

• organization.<fieldName>

• meter.<fieldName>

• product.<fieldName>

• account.<fieldName>

• accountPlan.<fieldName>

• plan.<fieldName>

• planTemplate.<fieldName>

Referencing Timestamp Fields

You can reference system variable Timestamp Fields in your Derived Field calculations. All timestamps are numeric values representing the appropriate date/times in Epoch milliseconds:

• ts

• ts.startOfMonth

• ts.endOfMonth

• ts.startOfMonthUTC

• ts.endOfMonthUTC

If the “ets” field - End Timestamp - is specified in the measurement, the following are also available:

• ets

• ets.startOfMonth

• ets.endOfMonth

• ets.startOfMonthUTC

• ets.endOfMonthUTC

Next: Reviewing Aggregation Options