• Home
/
• Working in m3ter - User Guides
/
• Data Explorers

Usage Data Explorer (v2)

You can use the Usage Data Explorer (v2) to configure and perform queries against the metered usage data collected for your Organization in m3ter. It allows you to quickly set up and submit a query that returns the usage data set needed to serve your current analytical purposes:

• Time Period. Define a time period for your data query:

  • Only the usage data collected for your Organization for the time period will be returned.

  • You can select from a set of predefined time period options or define a custom time period.

• Meters. Select the Meters you want the query to return data for.

• Accounts. Select the Accounts you want the query to return data for.

• Dimension Filters. Filter the usage data returned by adding specific values of non-numeric Dimension data fields on included Meters. Only the data collected for the values you've added for the selected Dimension fields will be returned for the query.

• Aggregations. Apply Aggregation functions to the usage data returned for the query.

• Grouped by. For queries that apply Aggregations, you can select to group the data returned for the query by:

  • Account

  • Time

  • Dimension

When you have performed a query, the data is loaded into the Usage Data Explorer (v2) and you can:

• Review the data in a results table and check that it serves your current purposes.

• Download the data in either CSV or JSONL format.

If you intend to use the Usage Data Explorer (v2) API endpoints, for convenience you can view and copy the query JSON.

This topic explains how to work with the Usage Data Explorer (v2) to configure and perform queries against your usage data and review the returned data.

• Building and Performing Simple Queries

• Using Dimension Filters for Queries

• Applying Aggregations for Queries

• Viewing and Copying Queries

• Downloading Query Results

Building and Performing Simple Queries

This section works through an example showing how to build and perform a simple usage data query - a simple query in that it doesn't use any Dimension filters and doesn't apply any Aggregations to the returned data.

To build and perform a simple query:

1. Select Metering>Usage data explorer:

The current version of the Usage Data Explorer opens. You'll see an information text at the top of the page advising that a new and improved version of the explorer is now available for you to preview.

2. Select the Try it out! button. Usage Data Explorer (v2) opens.

3. Select the Time period you want to return usage data for:

• Default is Today.

• Other predefined options:

  • Yesterday.

  • Week, Month, or Year to date.

  • Previous week, month, quarter, or year.

  • Last 7, 30, 35, 90, or 120 days, or Last year.

  • If you select a predefined Time period, then the start and end date/times are clearly shown in brackets. For example, Last 120 days:

4. For the current example, select Custom. The Time period panel adjusts to allow you to enter start and end date/times to define the time period for the query:

• Note that for a Custom period start date/time is inclusive and end date/time is exclusive. For the current example, we want to include all usage data collected for the entire month of January 2025. We've therefore set the exclusive end date/time as midnight on February 1st 2025. This means the query will return data collected up to the end of day January 31st 2025.

5. Use the plus icon on the Meters panel to open a dialog showing a list of Meters in your Organization.

6. On the dialog, check the Meters you want to include data from in your query and select Add. The selected Meters are then shown on the Meters panel.

• For the current example, we've used the Search field on the dialog to filter the list, checked a single Meter, and then added it:

Note that:

• Alternatively, you can enter the ID of a Meter and Add it for a query.

• Default is for All Meters.

6. Use the plus icon on the Accounts panel to open a dialog showing a list of Accounts in your Organization.

7. On the dialog, check the Accounts you want to include data for in your query and select Add. The selected Accounts are then shown on the Accounts panel.

• For the current example, we've used the Search field on the dialog to filter the list, checked a single Account, and then added it:

Note that:

• Alternatively, you can enter the ID of an Account and Add it for a query.

• Default is for All Accounts.

8. For the current example, we'll not use any Dimension filters for the query and we'll omit applying any Aggregations for the query results:

9. Select Perform query. The usage data collected for the defined Time period by the selected Meters and Accounts is loaded into a Result rows table:

In this example, we can see:

• Eight usage data submissions have been returned for the selected time period of the entire month of January 2025.

• The selected Meter has four Data Fields configured:

  • File Submits. A numeric Measure field of type MEASURE.

  • GBStore. A numeric Measure field of type MEASURE.

  • Customer Name. A non-numeric Dimensions field of type WHO.

  • Status. A non-numeric Dimension field of type METADATA.

Because no Dimension filters were defined and no Aggregations were applied, the query has returned all usage data submissions made using the single Meter for the single Account.

In the next section, we'll use Dimension filters to refine this example query to control the usage data returned.

Using Dimension Filters for Queries

To control the range of usage data a query returns, you can set up Dimension filters for any non-numeric Dimension Data Fields configured for the Meters selected for the query. This section explains how to use Dimension filters and extends the example of a simple query given in the previous section:

• The example used a simple query to return usage data collected by a single Meter and single Account.

• We saw that the example Meter was configured with two numeric or Measure Data Fields and two non-numeric or Dimension Data Fields.

We'll now use the Customer Name Dimension field to filter the range of data that's returned by the query.

To use dimension filters for queries:

1. Build and perform the simple query example given in the previous section.

2. Before you perform the query, under Dimension filters select Add dimension filter. A menu appears and lists any Dimension fields for Meters selected for the query:

• In the current example, a single Meter has two Dimension fields configured.

3. Select the Meter Dimension field you want to use to filter the data returned for the query. For the current example, we'll select RevGraph Meter 1 > Customer Name. A dialog replaces the menu, which lists values used for this field when usage submissions were made for the Meter within the selected Time period.

4. Check the values used for the selected Meter Dimension field you want to use to filter the data returned for the query and then select Add filter:

The dialog closes and the select Dimension field values are added under Dimension filters:

5. Select Perform query. The filtered query executes and returns the data into the Result rows panel:

• For the current example, we can see that the data returned for the filtered query now includes only those usage submissions made for Customer Pay1 values for the Customer Name Dimension field on the Meter.

Applying Aggregations for Queries

When building a query in the Usage Data Explorer (v2), you can choose to apply Aggregations to the usage data collected by any Data Fields on the Meters selected for the query.

This section explains the options you have when using Aggregations for queries and the consequences of using Aggregations. It then explains how to create and perform aggregated queries with some typical examples:

• Aggregations for Queries - Understanding Options and Consequences

• Applying Aggregations to Queries and Grouping Results

Aggregations for Queries - Understanding Options and Consequences

Before you attempt to use Aggregations for your queries in the Usage Data Explorer (v2), it's important to understand the options you have and the consequences that aggregating the data returned by the query will have.

There are two types of Meter Data Fields:

• Measures. Numeric fields of category MEASURE, INCOME, or COST.

• Dimensions. Non-numeric fields of category WHO, WHAT, WHERE, METADATA, or OTHER.

When building queries in Usage Data Explorer (v2), the available Aggregation methods for the various Meter Data Field categories are as follows:

If you apply Aggregations for a query:

• This restricts the range of usage data returned by the query to only the data collected by the aggregated fields on Meters. Nothing is returned for any non-aggregated fields on Meters.

• The usage data for Meter fields is returned as the values resulting from applying the selected aggregation method.

• You can then select to group the results of the aggregated data returned by:

  • Account

  • Time

  • Dimension

Applying Aggregations to Queries and Grouping Results

This section provides some examples of aggregated queries with grouped results:

• Example 1. Results grouped by Dimension

• Example 2. Results grouped by Time

• Example 3. Results grouped by Account

Aggregated Queries with Grouped Results - Example 1

This example extends the simple unfiltered query example from the earlier section to show how to apply aggregations to usage data returned for the query. It then goes on to show how to group the query results by a Dimension.

To apply aggregations for queries and group the results:

1. Build and perform the simple unfiltered query example given in the earlier section.

2. Under Aggregations, select Add aggregation. A menu listing available aggregation methods appears:

3. For the current example, select Sum. A dialog replaces the menu and shows the fields on the Meters selected for the query which can have this aggregation method applied:

In the current example, the two Meter fields of category MEASURE - File Submits and GB Store are listed.

4. Select to Sum the RevGraph Meter 1 > GB Store numeric data field. The dialog closes and the aggregation is added.

5. Repeat steps 2 to 4 to apply a Sum aggregation to the File Submits Meter field:

6. Select Perform Query. The query with aggregations applied executes and returns the data into the Result rows panel:

Suppose now we want to see how many different customers were responsible for these totals of file submissions and Gigabytes stored.

7. Repeat steps 2 to 4 to apply a Unique aggregation to the Customer Name Meter field:

8. Select Perform Query. The query executes and returns the data into the Result rows panel:

We can see that only two distinct customers were responsible for the totals of usage data.

Suppose now that we want to check how the totals were distributed between the two customers. We can use the grouped by option to do this.

9. First, remove the Unique aggregation of the Customer Name Dimension field from the query.

10. Under Aggregations, select the grouped by plus icon. A menu appears:

11. Select Dimension. The menu is replaced with a Dimension dialog:

12. Select the Dimension you want to group the aggregated usage by. For the current example, RevGraph Meter 1 > Customer Name.

13. Select Perform Query. The query executes and returns the data into the Result rows panel:

Aggregated Queries with Grouped Results - Example 2

This example uses a query that aggregates measures data by a SUM method over a month and then groups the results by day.

To apply aggregations for queries and group the results:

1. Build and perform an unfiltered query with Sum aggregations applied to MEASURE Data Fields on selected Meters:

• The query returns the data for the month of February 2025 collected for a single Meter and Account, and aggregates for a Sum of the data for each of the MEASURE fields on the Meter.

• The data is returned into the Result rows table as a single row.

Suppose we want to review the sum of usage data over the month by day. We can do this using the grouped by option by Time.

2. Under Aggregations, select the grouped by plus icon. A menu appears:

3. Select Time. The menu is replaced with a Time dialog:

4. Select Daily.

5. Select Perform Query. The query executes and returns the data into the Result rows panel:

Aggregated Queries with Grouped Results - Example 3

This example uses a query that aggregates measures data by a SUM method over a month and then groups the results by Account.

To apply aggregations for queries and group the results:

1. Build and perform an unfiltered query with Sum aggregations applied to MEASURE Data Fields on selected Meters:

• The query returns the data for the month of January 2025 collected for a single Meter and all Accounts, and aggregates for a Sum of the data for each of the MEASURE fields on the Meter.

• The data is returned into the Result rows table as a single row.

Suppose we want to review the sum of usage data over the month by Account. We can do this using the grouped by option by Account.

2. Under Aggregations, select the grouped by plus icon. A menu appears:

3. Select Account.

4. Select Perform Query. The query executes and returns the data into the Result rows panel:

Viewing and Copying Queries

As you are building a query, you might want to review the query's JSON structure. This can be helpful if you intend to use the Usage Data Explorer (v2) API query endpoint. For convenience, you can quickly view a query's JSON and copy it from the explorer page in the Console.

To view and copy queries:

1. Build and perform the query that returns the usage data results required for your analytical purposes.

2. In the Usage Data Explorer (v2), select View query. A modal appears containing the query JSON as currently configured:

• Note: This is the finalized aggregated query with a grouping by Dimension example from the earlier section.

3. You can Copy the query JSON to your clipboard, if required.

Downloading Query Results

When you have built a usage data query in Usage Data Explorer (v2), you can export the results returned for the query as a CSV or JSONL formatted file.

To download query results:

1. Build and perform the query that returns the usage data results required for your analytical purposes and which you want to download for use elsewhere.

2. On the Result rows panel, select Download CSV or Download JSONL. The returned data set that was loaded into the Result rows panel from the query is compiled in a .csv or .jsonl formatted file, downloaded, and saved locally.

Next: Billing Data Explorer

Additional Support