5. Create Metrics

Metrics are custom calculations that draw on various data points (facts) and categories (attributes) to provide deeper insights into your data. Acting like specialized queries, metrics allow you to explore and analyze information in more sophisticated ways. Once created, a metric is stored in your workspace, ensuring consistency and reusability across multiple visualizations. You can also build new metrics based on existing ones, making it easier to perform complex or nested calculations as your analytical needs evolve.

Create Simple Metric

You will define a straightforward metric that sums the total order amount in your dataset.

UI
API

Steps:

  1. In your workspace, switch to the Metrics tab and select Create metric.

    The Metrics tab with the Create Metric button highlighted.

    This opens the metric editor:

    The metric creation screen with the metric definition field.

  2. Name the metric Order Amount and give it a description Total value of all ordered products, then write the metric definition by typing out:

    SELECT SUM({fact/order_unit_quantity}*{fact/order_unit_price})

    Notice that as you type the metric definition, the metric editor gives you suggestions on what might come next, based on your connected database.

  3. Click Save.

    A metric calculation summing order unit quantity and price.

    You have created your first metric.

To create a metric, submit a POST request to /api/v1/entities/workspaces/<WORKSPACE_ID>/metrics:

curl $HOST_URL/api/v1/entities/workspaces/<WORKSPACE_ID>/metrics \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -X POST \
  -d '{
  "data": {
    "id": "order_amount",
    "type": "metric",
    "attributes": {
      "title": "Order Amount",
      "description": "Total value of all ordered products",
      "createdAt": "2025-01-30 14:42",
      "content": {
        "format": "#,##0.00",
        "maql": "SELECT SUM({fact/order_unit_quantity}*{fact/order_unit_price})"
      }
    }
  }
}' | jq .

Use Metric In Visualization

Now that you have created a metric, you can use it inside a visualization.

UI
API

  1. Switch to the Analyze tab and set the type of visualization to Column chart.

    The Analyze tab with available visualization types, with a bar chart highlighted.

  2. Drag and drop your metric Order Amount from the data catalog into the Metrics panel.

    The Order Amount metric being dragged into the Metrics bucket of the bar chart.

    You can now see your metric as in the column chart.

    A bar chart displaying the total order amount in a single bar.

    A single metric does not make for a very interesting visualization. Let’s slice it by some attributes.

  3. Drag and drop the Product category attribute into the View by panel to slice the metric Order Amount by category.

    The Product category attribute being dragged into the View by bucket of the bar chart.

    Your metric is now sliced into product categories.

    A bar chart showing order amount by product category. It consists of multiple bars, one for each product category.

  4. Give your visualization a title Order Amount by Category and click Save.

    You have used your first metric in a visualization.

To use the metric in a visualization, submit a POST request to /api/v1/entities/workspaces/<WORKSPACE_ID>/visualizationObjects:

curl $HOST_URL/api/v1/entities/workspaces/<WORKSPACE_ID>/visualizationObjects \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -X POST \
  -d '{
  "data": {
    "id": "orderAmountUsingMetric",
    "type": "visualizationObject",
    "attributes": {
      "title": "Order Amount by Category",
      "description": "",
      "content": {
        "buckets": [
          {
            "items": [
              {
                "measure": {
                  "localIdentifier": "c3437bdeb28c4a94bc7ff5dc0a2f7e18",
                  "definition": {
                    "measureDefinition": {
                      "item": {
                        "identifier": {
                          "id": "order_amount",
                          "type": "metric"
                        }
                      },
                      "computeRatio": false,
                      "filters": []
                    }
                  },
                  "title": "Order Amount"
                }
              }
            ],
            "localIdentifier": "measures"
          },
          {
            "items": [
              {
                "attribute": {
                  "localIdentifier": "391ffb80804845d6bb4b2864148fd5db",
                  "displayForm": {
                    "identifier": {
                      "id": "product_category",
                      "type": "label"
                    }
                  }
                }
              }
            ],
            "localIdentifier": "view"
          }
        ],
        "filters": [],
        "sorts": [],
        "properties": {},
        "visualizationUrl": "local:column",
        "version": "2"
      }
    }
  }
}' | jq .

Create a Nested Metric

You can use an existing metric to create new metrics. Use your previously created metric, Order Amount, to create a new metric, Revenue, that will filter out any undelivered orders. Note that you can create a new metric on the go, without having to leave the Analyze tab.

UI
API

Steps:

  1. Create a new metric; You can do this without having to leave the Analyze tab by

    The Analyze tab with the Create metric button in the bottom left corner.

    this opens the metric editor:

    The Analyze tab with the newly opened metric editor.

  2. Give the metric a title Revenue and a description Revenue from delivered products.

  3. Copy and paste in the following MAQL query:

    SELECT {metric/order_amount} WHERE {label/order_status} = "Processed"
    The metric editor dialog with the MAQL query filled in.

  4. Click Save.

  5. Switch to a Line chart and drop your newly created Revenue metric into the Metrics bucket:

    The Revenue metric being dragged into the Metrics bucket of the line chart.

  6. Complete the visualization by adding a Date metric into the Trend by bucket, and Customer country attribute into the Segment by bucket:

    A final line chart displaying revenue trends segmented by country.

  7. Save the visualizaiton.

To create a nested metric, submit a POST request to /api/v1/entities/workspaces/<WORKSPACE_ID>/metrics:

curl $HOST_URL/api/v1/entities/workspaces/<WORKSPACE_ID>/metrics \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -X POST \
  -d '{
  "id": "revenue",
  "type": "metric",
  "attributes": {
    "title": "Revenue",
    "description": "Revenue from delivered products",
    "createdAt": "2025-02-05 17:35",
    "content": {
      "format": "#,##0.00",
      "maql": "SELECT {metric/order_amount} WHERE {label/order_status} = \"Processed\""
    }
  }
}' | jq .

To use the metric in a visualization, submit a POST request to /api/v1/entities/workspaces/<WORKSPACE_ID>/visualizationObjects:

curl $HOST_URL/api/v1/entities/workspaces/<WORKSPACE_ID>/visualizationObjects \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -X POST \
  -d '{
  "data": {
    "id": "22246615-c6bf-4979-a123-8a09fca3e901",
    "type": "visualizationObject",
    "attributes": {
      "title": "Revenue by Country",
      "description": "",
      "content": {
        "buckets": [
          {
            "items": [
              {
                "measure": {
                  "localIdentifier": "8b66ef08b0e34c36884dff4144d6ee6c",
                  "definition": {
                    "measureDefinition": {
                      "item": {
                        "identifier": {
                          "id": "revenue",
                          "type": "metric"
                        }
                      },
                      "filters": []
                    }
                  },
                  "title": "Revenue"
                }
              }
            ],
            "localIdentifier": "measures"
          },
          {
            "items": [
              {
                "attribute": {
                  "localIdentifier": "8993f23fd77f492ab4bd7b517383e102",
                  "displayForm": {
                    "identifier": {
                      "id": "customer_created_date.year",
                      "type": "label"
                    }
                  }
                }
              }
            ],
            "localIdentifier": "trend"
          },
          {
            "items": [
              {
                "attribute": {
                  "localIdentifier": "5578881c15ff4017b756fdb421e90d12",
                  "displayForm": {
                    "identifier": {
                      "id": "customer_country",
                      "type": "label"
                    }
                  }
                }
              }
            ],
            "localIdentifier": "segment"
          }
        ],
        "filters": [],
        "sorts": [],
        "properties": {},
        "visualizationUrl": "local:line",
        "version": "2"
      }
    }
  }
}' | jq .
4. Create Visualization
6. Create Dashboard