> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contextualization Quality Dashboard reference

> Measure, monitor, and visualize contextualization quality in CDF across asset hierarchy, equipment, time series, maintenance, file annotation, and 3D — with a metrics function and a Streamlit dashboard.

The **Contextualization Quality Dashboard** (`dp:dashboards:context_quality`) measures, monitors, and visualizes how well your data is contextualized in Cognite Data Fusion. It deploys as a Cognite Toolkit module with two parts: a CDF Function (`context_quality_handler`) that computes 40+ quality metrics and saves them as a file in CDF, and a Streamlit app (`context_quality_dashboard`) that visualizes the pre-computed metrics with gauges, charts, and tables.

The module scores quality across six dimensions — asset hierarchy, equipment-to-asset relationships, time series contextualization, maintenance workflow, file annotation (P\&ID), and 3D model contextualization — and includes AI-generated insights per dimension.

<Note>
  The Contextualization Quality Dashboard is a cherry-pickable module (`dp:dashboards:context_quality`) inside the **Dashboards** deployment pack (`dp:dashboards`). You can add it on its own or alongside the other dashboard modules.
</Note>

## Who it's for

**Target personas:**

* **Data engineers** — deploy the dashboard and run the metrics function.
* **Business/data owners** — understand data quality and formulate use cases for the built data foundation.
* **Subject matter experts** — operations and reliability teams who interpret the quality metrics and prioritize fixes.

**Use this pack when:**

* You want a quantitative, repeatable measure of how well assets, equipment, time series, files, and 3D objects are contextualized.
* You need a baseline and trend to track contextualization improvements over time.
* You want to spot gaps — orphaned time series, unlinked equipment, missing failure documentation, un-annotated P\&IDs, or orphaned 3D objects.

**When not to use this pack:**

* If you need to create relationships rather than measure them — use the [CDF Entity Matching](/cdf/deploy/cdf_toolkit/references/packages/entity_matching) or [P\&ID Annotation](/cdf/deploy/cdf_toolkit/references/packages/pid_annotation) packs to build contextualization first.

## What's included

| Component                                         | Description                                                                                                                                              | Optional? |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| Metrics function (`context_quality_handler`)      | CDF Function that queries the configured views, computes all quality metrics, and saves the result as a file in CDF. Runs in batches for large datasets. | No        |
| Streamlit dashboard (`context_quality_dashboard`) | App titled **Contextualization Quality** that reads the pre-computed metrics and renders gauges, charts, tables, and AI insights across six tabs.        | No        |
| Dataset (`context_quality_apps`)                  | CDF dataset for the function code bundle and app files.                                                                                                  | No        |

<Note>
  The module reads from your data model views — it does not create or modify them. Configuration is done in the dashboard's **Configure & Run** tab (or, for scheduled/local runs, in the module code). There is no `default.config.yaml`.
</Note>

## Prerequisites

Verify all of the following before you start:

* Cognite Toolkit version **0.8 or later** is installed. See [Setting up](/cdf/deploy/cdf_toolkit/guides/setup).
* A `cdf.toml` file exists in your project root. If it is missing, run `cdf modules init` and select **Create toml file (required)**.
* Authentication is configured and verified — run `cdf auth init` and `cdf auth verify` using a local `.env` file. See [Authentication and authorization](/cdf/deploy/cdf_toolkit/guides/auth).
* Your project has data in the views you want to score. The defaults target the Cognite Core Data Model (`CogniteAsset`, `CogniteEquipment`, `CogniteTimeSeries`, `CogniteDiagramAnnotation`, `Cognite3DObject`). The maintenance dimension additionally requires **RMDM** (`Notification`, `MaintenanceOrder`, `FailureNotification`).
* **Optional:** Cognite Atlas AI enabled, for the AI Insights feature in the dashboard.

## Install and deploy

You can add the module to an existing Toolkit project or start a new project from scratch.

<Tabs>
  <Tab title="Add to an existing project">
    Run `cdf modules add` and select **Dashboards > Contextualization Quality Dashboard**.
  </Tab>

  <Tab title="Start a new project">
    1. In an empty directory, initialize a project:

       ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
       cdf modules init .
       ```

    2. In the interactive menu, choose **Dashboards**, use **Space** to select **Contextualization Quality Dashboard**, then press **Enter** to confirm.
  </Tab>
</Tabs>

The Toolkit creates the module under `modules/dashboards/context_quality/` and updates your `config.<env>.yaml` files. Then build and deploy:

<Steps>
  <Step title="Build deployment artifacts">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf build
    ```

    The Toolkit substitutes template variables and writes artifacts to the `build/` directory. If you need to change the project name or any variables marked `<change_me>`, edit `config.<env>.yaml` first — see [Configure, build, and deploy modules](/cdf/deploy/cdf_toolkit/guides/usage).
  </Step>

  <Step title="Dry-run the deployment">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy --dry-run
    ```

    Inspect the output and confirm that configurations look correct before deploying.
  </Step>

  <Step title="Deploy to CDF">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy
    ```

    The Toolkit deploys only configurations that have changed since the last run.
  </Step>

  <Step title="Set up CI/CD (optional)">
    For governed production deployments, automate build, dry-run, and deploy in a pipeline. See [Set up CI/CD pipelines](/cdf/deploy/cdf_toolkit/guides/cicd/index).
  </Step>
</Steps>

<Note>
  After `cdf deploy`, the `context_quality_handler` function may take **2–5 minutes** to reach **Ready**. The Streamlit dashboard is available immediately, but running metrics requires the function to finish deploying.
</Note>

## Verify the deployment

After deploying, confirm success with these checks:

1. The `cdf deploy` command finishes without errors and reports the function, Streamlit app, and dataset.
2. In CDF, navigate to **Build Solutions > Functions** and confirm `context_quality_handler` shows a **Ready** status (allow 2–5 minutes).
3. Open **Industrial Tools > Custom Apps** and confirm the **Contextualization Quality** app is listed and opens.
4. In the app's **Configure & Run** tab, run the batches and then **Run Aggregation**; wait for each step to show complete.
5. Open a dimension tab (for example, **Asset Hierarchy** or **Time Series**) and confirm the gauges and statistics are populated.

The deployment is successful when the function is ready, the dashboard opens, a metrics run aggregates without errors, and the dimension tabs show values.

## Running the dashboard

Open **Industrial Tools > Custom Apps > Contextualization Quality**. The **Configure & Run** tab is the entry point:

1. **Configure views** — expand each dimension and set its space, view external ID, and version. Defaults match the CDM/RMDM views. Disable dimensions you don't have data for (maintenance, file annotation, 3D).
2. **Run batches** — batch processing is the primary method. Set a batch size (default 200,000) and number of batches (default 3), then run each batch in turn. Failed batches can be retried individually.
3. **Aggregate** — after all batches complete, run **Aggregation** to merge results into the final metrics file.
4. **View metrics** — open the dimension tabs for gauges, statistics, rule-based insights, and optional AI insights.

<Note>
  For continuous monitoring, schedule `context_quality_handler` (for example, a daily cron). Scheduled and local runs use the defaults in the module code, not the dashboard's Configure & Run settings.
</Note>

## Configuration reference

Views are configured per dimension in the dashboard's **Configure & Run** tab. The defaults are:

| Dimension            | Views                                                     | Default space |
| -------------------- | --------------------------------------------------------- | ------------- |
| Asset hierarchy      | `CogniteAsset`                                            | `cdf_cdm`     |
| Equipment-asset      | `CogniteEquipment`                                        | `cdf_cdm`     |
| Time series          | `CogniteTimeSeries`                                       | `cdf_cdm`     |
| Maintenance workflow | `Notification`, `MaintenanceOrder`, `FailureNotification` | `rmdm`        |
| File annotation      | `CogniteDiagramAnnotation`                                | `cdf_cdm`     |
| 3D model             | `CogniteAsset`, `Cognite3DObject`                         | `cdf_cdm`     |

Feature flags (`enable_maintenance_metrics`, `enable_file_annotation_metrics`, `enable_3d_metrics`) turn dimensions on or off, and per-item processing limits (default 150,000; 200,000 for annotations) cap how much is scanned per run.

<Note>
  The **Configure & Run** tab only affects interactive runs. For **scheduled** or **local** runs to use custom views, update the defaults in **both** `dashboards/configuration.py` and `functions/context_quality_handler/metrics/common.py`. You can also override views per call by passing them in the function `data` payload. If your model uses different property names, edit the relevant `metrics/*.py` file.
</Note>

## Architecture

The module separates computation from visualization: the function computes metrics and writes a metrics file to CDF; the Streamlit app reads that file and renders it. State for batch processing is held in CDF between batch runs and merged during aggregation.

### Data flow

```mermaid theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
flowchart TD
    subgraph Views["CDF data model views"]
        v1["CogniteAsset · CogniteEquipment · CogniteTimeSeries"]
        v2["CogniteDiagramAnnotation · Cognite3DObject"]
        v3["RMDM · Notification · MaintenanceOrder · FailureNotification"]
    end

    Run["Configure & Run (dashboard)<br/>or scheduled function call"] --> Fn["context_quality_handler"]
    Views --> Fn
    Fn --> Batch["Batch runs → intermediate results"]
    Batch --> Agg["Aggregation"]
    Agg --> File[("Metrics file in CDF<br/>contextualization_quality_metrics")]
    File --> App["context_quality_dashboard (Streamlit)"]
    App --> Tabs["6 dimension tabs · gauges · AI insights"]
```

## Metrics reference

The function computes 40+ metrics across six dimensions. Each dimension is scored with rule-based thresholds (green/amber/red) and, optionally, an AI summary.

| Dimension                   | Measures                                                          | Headline metrics                                                                                                                                           |
| --------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Asset hierarchy             | Structural integrity of the asset tree.                           | Hierarchy completion rate, orphan count/rate, depth and breadth statistics.                                                                                |
| Equipment-asset             | Quality of equipment-to-asset mappings.                           | Equipment association rate, asset equipment coverage, serial number and manufacturer completeness, type consistency, critical equipment contextualization. |
| Time series                 | How well time series link to assets, plus metadata quality.       | TS-to-asset contextualization rate, asset monitoring coverage, critical asset coverage, unit completeness, data freshness, historical completeness.        |
| Maintenance workflow (RMDM) | Quality of notifications, work orders, and failure documentation. | Work order → notification / asset / equipment rates, work order completion, failure mode/mechanism/cause documentation rates.                              |
| File annotation             | Quality of P\&ID diagram annotations.                             | Total annotations, files with annotations, average confidence, confidence and status distribution, annotation types.                                       |
| 3D model                    | Quality of 3D object linking to assets.                           | 3D contextualization rate, asset 3D coverage, critical asset 3D rate, bounding box completeness, model type distribution.                                  |

<Note>
  Maintenance, file annotation, and 3D metrics require their respective data (RMDM v1, `CogniteDiagramAnnotation`, and `Cognite3DObject`). If the data is missing, the corresponding tab shows a warning — disable the dimension or configure custom views.
</Note>

## Troubleshooting

| Symptom                                                             | Likely cause                                                | Resolution                                                                                                       |
| ------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| "Function not available" when running a batch                       | The function is still deploying after `cdf deploy`.         | Wait 2–5 minutes and confirm `context_quality_handler` shows **Ready** in **Build Solutions > Functions**.       |
| Deploy error: function must have a space set (`DATA_MODELING_ONLY`) | The project stores function code in a space, not a dataset. | The module already sets `space: context_quality`; if you override the Function YAML, add a `space` field.        |
| Dashboard shows "No metrics data available"                         | The function has not run, or aggregation was not completed. | Run all batches in **Configure & Run**, then **Run Aggregation**, and retry any failed batch.                    |
| Metrics show all zeros                                              | The configured views are empty or misconfigured.            | Verify data exists and that the space, external ID, and version match your model in the **Configure & Run** tab. |
| Function or batch times out                                         | Too much data for the \~10-minute per-batch limit.          | Reduce batch size, add more batches, lower processing limits, or disable unused dimensions.                      |
| Maintenance tab shows a warning                                     | RMDM is not deployed or has no data.                        | Deploy RMDM v1, disable maintenance metrics, or configure custom view names.                                     |
| Scheduled/local runs ignore dashboard config                        | Scheduled and local runs read the module code defaults.     | Update views in both `dashboards/configuration.py` and `functions/context_quality_handler/metrics/common.py`.    |

For issues not covered here, contact Cognite support.

## Support

| Field                  | Details                                                                     |
| ---------------------- | --------------------------------------------------------------------------- |
| Team                   | Cognite Value Delivery Team                                                 |
| Documentation          | [Cognite product documentation](/)                                          |
| Questions and feedback | [Deployment Packs group on Cognite Hub](https://hub.cognite.com/groups/578) |
| Version                | 1.0.0                                                                       |
| Last updated           | 2026                                                                        |