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.
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.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.
- 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.
- If you need to create relationships rather than measure them — use the CDF Entity Matching or P&ID 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 |
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.Prerequisites
Verify all of the following before you start:- Cognite Toolkit version 0.8 or later is installed. See Setting up.
- A
cdf.tomlfile exists in your project root. If it is missing, runcdf modules initand select Create toml file (required). - Authentication is configured and verified — run
cdf auth initandcdf auth verifyusing a local.envfile. See Authentication and authorization. - 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.- Add to an existing project
- Start a new project
Run
cdf modules add and select Dashboards > Contextualization Quality Dashboard.modules/dashboards/context_quality/ and updates your config.<env>.yaml files. Then build and deploy:
Build deployment artifacts
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.Dry-run the deployment
Set up CI/CD (optional)
For governed production deployments, automate build, dry-run, and deploy in a pipeline. See Set up CI/CD pipelines.
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.Verify the deployment
After deploying, confirm success with these checks:- The
cdf deploycommand finishes without errors and reports the function, Streamlit app, and dataset. - In CDF, navigate to Build Solutions > Functions and confirm
context_quality_handlershows a Ready status (allow 2–5 minutes). - Open Industrial Tools > Custom Apps and confirm the Contextualization Quality app is listed and opens.
- In the app’s Configure & Run tab, run the batches and then Run Aggregation; wait for each step to show complete.
- Open a dimension tab (for example, Asset Hierarchy or Time Series) and confirm the gauges and statistics are populated.
Running the dashboard
Open Industrial Tools > Custom Apps > Contextualization Quality. The Configure & Run tab is the entry point:- 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).
- 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.
- Aggregate — after all batches complete, run Aggregation to merge results into the final metrics file.
- View metrics — open the dimension tabs for gauges, statistics, rule-based insights, and optional AI insights.
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.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 |
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.
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.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
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. |
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.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. |
Support
| Field | Details |
|---|---|
| Team | Cognite Value Delivery Team |
| Documentation | Cognite product documentation |
| Questions and feedback | Deployment Packs group on Cognite Hub |
| Version | 1.0.0 |
| Last updated | 2026 |