GoodData.CN: Metrics Management 101

Hello and welcome to Metrics Management 101 on the GoodData.CN Platform where we will describe considerations and best practices for building metrics! In this article, we will dive into metric attributes and core functions to build out your metric catalog for analysis.

In GoodData.CN metrics are managed via APIs. A definition of a metric looks like:

"data": {
  "id": "revenue_lost",
  "type": "metric",
  "attributes": {
    "title": "Revenue Lost",
    "description": "",
    "content": {
      "format": "$#,##0",
      "maql": "SELECT {metric/order_amount} WHERE {label/order_lines.order_status} in (\"Canceled\",\"Returned\")"
    }
  }
}

Let’s first start with the different metric parameters you will need to create a metric via API:

1. Metric ID: All measures need a unique identifier (this ID is not visible in the UI). In GoodData.CN, this ID can be any value, but we recommend making this value as semantically identifiable as possible for easy recognition. This will also help in the long run when referenced from other metrics. For example, if you are creating a new metric called “Profit Margin” your ID could be “profit_margin”.
2. Metric Title: Name your measure universally so all of your customers can understand it in the same way. Similar to the Metric ID, this name should be semantically recognizable and meaningful. This title will be visible in the UI and will appear in the data catalog in Analytical Designer.
   • If the measure you are trying to describe is specific to an attribute value, try adding it to the name, like “Profit Margin (Home Goods)” rather than “Profit Margin.” Another example is “Profit Margin by Week” instead of “Profit Margin”.
   • TIP: If you are aggregating a fact in several different ways for your base metrics (a.k.a. metrics you will use as building blocks for other metrics), try naming them with the Fact first and then the aggregation in brackets. For example, say you want two metrics for fact Amount. You can name them “Amount [Sum]” and “Amount [Avg]”. All metrics in the data catalog in Analytical Designer display these measures in alphabetical order.
   • Need help with naming your metric? Check out our article on Metric Naming Best Practices.
3. Metric Definition: This is an optional field that can be added to describe the measure in more detail. The definitions are available in Analytical Designer when the user hovers over the measure in the business catalog.
4. Metric Format: You can specify how the metric values should be formatted in your insights. For the available formatting options, see this link.
   • For example, if you would like to add a dollar sign to your metric values, you can set your format as “$#,##0.00.” The same can be applied to setting decimals and rounding to the nearest thousands.
   • TIP: Alternatively, metric formats can be overwritten directly in the insight, so there is no need to duplicate your metrics for different formats.
5. Metric MAQL: In this metric attribute, you will define the MAQL definition for your metric. MAQL (Multi-dimensional Analytical Query Language) is very similar in syntax to SQL but does not include any table joins as the logical data model does the joins for you. MAQL statements always start with ‘SELECT’ and include an aggregation of a fact. All references to pieces of the logical data model (like attributes, facts, and existing measures) are all identified by {type/name}.
   • For example, the MAQL statement for Revenue by Category could look like this: SELECT {metric/revenue} BY {attribute/products.category}
   • Alternatively, if you are writing a MAQL definition to filter an attribute, use the label type identifier like this example for Profit Margin (Home Goods): SELECT {metric/profit-margin} BY {label/products.category} = "Home"
   • TIP: Because all metric parameters are enclosed in double quotes, don’t forget to escape your quotes with ‘\’. Here’s an example: "SELECT {metric/profit-margin} BY {label/products.category} = \\\"Home\\\""

Now that we understand the different metric parameters, let’s take a look at some best practices for building out your metric catalog:

1. Build out your base metrics first. A base metric is a metric that will be referenced by other metrics. These usually include a basic aggregation of a fact like SUM({fact/order.amount}) or COUNT({attribute/customers.customer_id},{attribute/order.orderid}). Building out these base metrics first will allow you to reference them for later metrics.
2. As a rule of thumb, try not to repeat MAQL across metrics - repeat as much as possible in the form of referenced metrics. More references means easier control over changes to existing metrics. You can make your change in one place, rather than across multiple metrics for the same logical change. For example, say you have a metric called # Active Users This Month, that references a metric # Active Users, that references a metric # Users. If the definition for # Users were to change, you could make the update directly in this measure rather than all three metrics.

If you are interested in GoodData.CN, please contact us.

Alternatively, test a trial version of GoodData Cloud: Start Your GoodData Analytics Trial — Commitment-Free