Create Metrics using API

You can create and manage metrics through the workspace entity API interface. The entity API interface for metrics uses the following endpoints:

/api/v1/entities/workspaces/{workspace-id}/metrics
View existing metrics in the workspace, or add new metrics to the workspace.
/api/v1/entities/workspaces/{workspace-id}/metrics/{metric-id}
View a specific metric, edit a metric, or delete a metric in the workspace.

Where:

{workspace-id}
Specifies the ID of the workspace to access.
{metric-id}
Specifies the ID of the metric to access.

View Metrics with the Entity API Interface

Metrics can be viewed by submitting the appropriate GET request:

To view all of the metrics in a workspace, submit a GET request to /api/v1/entities/workspaces/{workspace-id}/metrics.
To view a specific metric in the workspace, submit a GET request to /api/v1/entities/workspaces/{workspace-id}/metrics/{metric-id}.

Create a Metric with the Entity API Interface

To create a new metric, submit a POST request to /api/v1/entities/workspaces/{workspace-id}/metrics with the metric as the body payload.

Body Syntax for Metrics in the Entity API Interface

The payload for creating a new metric has the following syntax:

{
      "data": {
          "attributes": {
              "title": "<metric_title>",
              "description":"<metric_description>",
              "content": {
                  "format": "<number_format>",
                  "maql": "<maql_expression>"
              }
          },
          "id": "<metric_id>",
          "type": "metric"
      }
  }

Where:

<metric_title>
Specifies the name of the metric. For example, Order Amount.
<metric_description>
Specifies the description of the metric. For example, Sum of order prices.
<number_format>
Specifies the display format for the numbers in visualizations that use this metric. For example, $#,##0. For more information number formats, see Format Numbers.
<maql_expression>
Specifies the MAQL expression that comprises the metric. For example, SELECT SUM({fact/order_lines.price}*{fact/order_lines.quantity}).
<metric_id>
Specifies the unique ID that represents the metric. This value is used when making API calls to the metric endpoint. For example, order_amount.

Example: Create the Order Amount Metric

The following example creates a metric that is the sum price of all the orders that the metric is applied against.

{
      "data": {
          "attributes": {
              "title": "Order Amount",
              "description":"Sum of order prices",
              "content": {
                  "format": "$#,##0",
                  "maql": "SELECT SUM({fact/order_lines.price}*{fact/order_lines.quantity})"
              }
          },
          "id": "order_amount",
          "type": "metric"
      }
  }

Update a Metric with the Entity API Interface

To edit a metric, submit a PUT request with the modified metric body data in the payload to /api/v1/entities/workspaces/{workspace-id}/metrics/{metric-id} where {metric-id} is the ID of the metric to update.

Consider the following points before updating a metric:

It is not possible to update the metric ID through the entity API interface. To update the ID for a metric, use the Metric Editor or the declarative API interface.
If you update the MAQL expression or format for a metric, other metrics, dashboards, and visualizations that use the metric will also use the updated expression or format.

Delete a Metric with the Entity API Interface

To delete a metric, submit a DELETE request to /api/v1/entities/workspaces/{workspace-id}/metrics/{metric-id} where {metric-id} is the ID of the metric to delete.

Consider the following point before deleting a metric:

If you delete a metric, other metrics, dashboards, and visualizations that use the metric will become inaccessible.

Format Numbers

Learn more: