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​/entities​/workspaces​/{workspace-id}/metrics
    View existing metrics in the workspace, or add new metrics to the workspace.
  • ​/api​/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.

The default hostname for the application endpoint is determined by which edition of GoodData.CN you use:

  • GoodData.CN
    For example, https://{organization-hostname}/api/v1/entities​/workspaces​/{workspace-id}/metrics
  • GoodData.CN Community Edition
    For example, http://localhost:{port}/api/v1/entities​/workspaces​/{workspace-id}/metrics

Where:

  • {organization-hostname}
    Specifies the hostname for your organization with GoodData.CN. For example gooddata.com.
  • {port}
    Specifies the port to access your installation of GoodData.CN Community Edition. The default port is 3000.

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​/entities​/workspaces​/{workspace-id}​/metrics​.
  • To view a specific metric in the workspace, submit a GET request to ​/api​/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​/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​/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​/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