# CDQ Insights API - Filtering and Dimensions

## 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`:


```bash
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**

| Operator | Behaviour |
|  --- | --- |
| `IN` | Matches any of the listed values |
| `NOT_IN` | Excludes all listed values |
| `EQUAL` | Matches a single exact value |
| `NOT_EQUAL` | Excludes a single exact value |


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.


```bash
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:


```json
{
  "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%.

A result object will only appear for countries that have data. If a country in your filter has no validated records for the date range, it will be absent from the results, not returned as `null`.

## 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:


```bash
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.

You can find which dimensions are available for a given metric by checking the `dimensions` array in the catalogue. Only dimensions listed there are valid for that metric.

## 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.


```bash
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:


```json
{
  "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" }
      ]
    }
  ]
}
```

When requesting multiple metrics, filters and dimensions apply to **all** of them. Filters must use fields listed in `filtersSupported` for *every* metric in the `ids` array, not just one of them, and dimensions must be valid for every metric too. If a dimension or filter is not supported by one of the requested metrics, the API rejects the entire request with a `400 Bad Request`. Check `filtersSupported` and `dimensions` in the catalogue for each metric before combining them.

## 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!