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.