CDQ Insights API - Filtering and Dimensions

Copy

Overview

This tutorial shows you how to narrow your metric results using filters, break them down into groups using dimensions, and combine both in a single request. You will also learn how to request multiple metrics at once.

This tutorial builds directly on Fetching a Metric with Postman. You should have the CDQ Insights API collection in Postman with the data_quality_ratio request saved.

Learning Goals

In this tutorial, you will learn how to:

• Narrow metric results with filters before calculation
• Break results into groups with dimensions
• Combine filters and dimensions in a single request
• Request multiple metrics in one call and respect the cross-metric rules

The difference between filters and dimensions

Before writing any requests it is worth understanding what these two things do, because they are easy to confuse:

• A filter narrows the data before the metric is calculated. If you filter by country = DE, only German records are included in the calculation. Records from other countries are excluded entirely.
• A dimension groups the results. If you add country as a dimension, the API returns a separate value for each country rather than one combined total. All records are still included; they are just split into groups.

You can use both together: filter to a subset of countries, then get a separate ratio for each one within that subset.

Step 1: Adding a filter

Starting from the basic request in the previous tutorial, let's narrow the result to a specific country. Paste this curl into Postman, replacing YOUR_API_KEY_HERE:

curl -i -X POST \
  https://api.cdq.com/analytics/rest/insights \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ids": ["data_quality_ratio"],
    "dateFrom": "2026-05-01",
    "dateTo": "2026-05-31",
    "filters": [
      {
        "field": "country",
        "operator": "IN",
        "values": ["DE", "PL", "FR"]
      }
    ]
  }'

The filters array accepts one or more filter objects. Each filter has three fields:

• field: the attribute to filter on. Must be one of the values listed in filtersSupported for the metric you are requesting.
• operator: how to match. See the supported operators below.
• values: the values to match against. Always an array.

Supported filter operators

The response will be a single data_quality_ratio value calculated only from records belonging to DE, PL, or FR. All other countries are excluded from the calculation.

Step 2: Adding a dimension

Now instead of one combined ratio for DE, PL, and FR, let's get a separate ratio for each country.

curl -i -X POST \
  https://api.cdq.com/analytics/rest/insights \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ids": ["data_quality_ratio"],
    "dateFrom": "2026-05-01",
    "dateTo": "2026-05-31",
    "filters": [
      {
        "field": "country",
        "operator": "IN",
        "values": ["DE", "PL", "FR"]
      }
    ],
    "dimensions": ["country"]
  }'

The response now contains one result object per country:

{
  "items": [
    {
      "id": "data_quality_ratio",
      "results": [
        { "date": "2026-05-31", "value": 0.9621, "country": "DE" },
        { "date": "2026-05-31", "value": 0.8803, "country": "PL" },
        { "date": "2026-05-31", "value": 0.9410, "country": "FR" }
      ]
    }
  ]
}

Each result object now has the country field alongside date and value. Dimension values are always flat fields on the result object; there is no nesting.

This is where the metric becomes genuinely useful: the combined ratio might look healthy at 94%, but breaking it down by country reveals that Poland is significantly below the others at 88%.

Step 3: Breaking down by data source

Dimensions are not limited to country. For data_quality_ratio, you can also dimension by dataSourceId to see quality ratios per data source:

curl -i -X POST \
  https://api.cdq.com/analytics/rest/insights \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ids": ["data_quality_ratio"],
    "dateFrom": "2026-05-01",
    "dateTo": "2026-05-31",
    "dimensions": ["country", "dataSourceId"]
  }'

Adding multiple dimensions returns one result per unique combination. A workspace with 3 countries and 2 data sources would return up to 6 result objects, one for each country/data source pair.

Step 4: Requesting multiple metrics at once

The ids array accepts multiple metric IDs in a single request. This is more efficient than making separate calls.

curl -i -X POST \
  https://api.cdq.com/analytics/rest/insights \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ids": ["data_quality_ratio", "defective_records_ratio", "erroneous_records_ratio"],
    "dateFrom": "2026-05-01",
    "dateTo": "2026-05-31",
    "dimensions": ["country"]
  }'

The response contains one item per metric, each with its own results array:

{
  "items": [
    {
      "id": "data_quality_ratio",
      "results": [
        { "date": "2026-05-31", "value": 0.9621, "country": "DE" },
        { "date": "2026-05-31", "value": 0.8803, "country": "PL" }
      ]
    },
    {
      "id": "defective_records_ratio",
      "results": [
        { "date": "2026-05-31", "value": 0.0634, "country": "DE" },
        { "date": "2026-05-31", "value": 0.1431, "country": "PL" }
      ]
    },
    {
      "id": "erroneous_records_ratio",
      "results": [
        { "date": "2026-05-31", "value": 0.0211, "country": "DE" },
        { "date": "2026-05-31", "value": 0.0874, "country": "PL" }
      ]
    }
  ]
}

Saving your requests in Postman

Save each variation as a separate request in your CDQ Insights API collection:

• data quality ratio (filtered by country)
• data quality ratio (by country dimension)
• data quality ratio (by country and data source)
• data quality metrics (multi-metric)

Next steps

The Time Granularity: Trend Analysis tutorial introduces time granularity, that is how to get a value per day, week, or month instead of a single latest value, so you can track how your data quality ratio is trending over time.

Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!