Configure the data model
A data model configuration maps the tables and columns of a dataset to the building blocks Data Exploration works with:
- Basic data: attributes that belong to the person, such as gender or year of birth.
- Interactions: events in a person's history, such as a condition, a drug exposure or a visit.
- Attributes: the values of basic data and interactions that researchers filter on and chart, such as a concept, a date or a measurement value.
To open the editor, go to the Admin Portal, select Setup and open CDM configuration.
Versions
A data model configuration has numbered versions. Each version has one of the following statuses:
| Status | Meaning |
|---|---|
| Draft | Saved, but not activated. |
| Active | The version Data Exploration configurations should use. Only one version is active at a time. |
| Inactive | A previous version that was replaced by a newer active version. |
Data Exploration configurations point to a specific version. Activating a new version does not change existing Data Exploration configurations: they keep using their version until you switch them to the new one.
Manage configurations
The overview lists all data model configurations. Select Show Versions on a configuration to see its versions.
| Action | What it does |
|---|---|
| Create Configuration | Creates an empty configuration. Enter a title and select Create. |
| Import Configuration | Creates a configuration from a JSON file, for example one exported from another system. |
| Edit | Opens a version in the editor. |
| Activate | Activates a version. On the configuration itself, activates its most recent version. |
| Duplicate | Copies a version into a new configuration. |
| Export | Downloads a version as a JSON file. |
| Delete | Deletes a single version, or the configuration with all its versions. |
Edit a configuration
The editor toolbar provides the following actions:
| Action | What it does |
|---|---|
| Generate Suggested Configuration | Suggests basic data and interactions. Useful as a starting point for a new data model. |
| Validate | Checks the configuration for errors. |
| Preview | Shows the configuration as JSON. |
| Save | Saves the configuration as a draft. |
| Save & Activate | Saves the configuration and activates it. |
The editor has three pages:
- Data Model Settings: basic data, interactions and their attributes.
- Placeholder Settings: the tables and columns the configuration reads from.
- Other Settings: languages and query settings.
Interactions
Select Add Interaction to add an interaction. For each interaction, set:
- Name: the label researchers see, per language.
- Interaction ID to Use in Configuration: a unique technical ID.
- Custom Tables: additional tables the interaction joins, if any.
- Parent Interaction: optional. Links the interaction to a parent interaction, for example a procedure that belongs to a visit.
Attributes
Select Add Attribute on basic data or an interaction to add an attribute. Suggested Attributes lists attributes you can add.
The main settings of an attribute are:
| Setting | Description |
|---|---|
| Name | The label researchers see, per language. |
| Attribute ID to use in Configuration | A unique technical ID within the interaction. |
| Attribute Type | Normal Attribute reads a value per person or event. Aggregate Attribute calculates a value over several rows, using a Measure Expression. Aggregate attributes can only be used on the y-axis of charts. |
| Data Source (Expression) | The SQL expression that returns the attribute value. |
| Filter Expression | Optional SQL condition that limits the rows the attribute reads. |
| Data Type | The type of the value, for example text, number or date. |
| Include Descendants | Includes the descendants of a concept from the vocabulary hierarchy when researchers filter on it. |
| Specify Attribute as a Catalog Attribute | Looks up descriptions for codes with a Reference Expression and Reference Filter. Required for the Show Descriptions and Show All Codes options in the filter cards. |
Select Test Attribute to check an attribute against the data. The test shows errors, the minimum and maximum value, the number of distinct values and sample values.
Expressions run against the database of the dataset, for example PostgreSQL or DuckDB. Use SQL that this database understands.
Placeholder Settings
Placeholders connect the configuration to the actual tables and columns:
- Base Entity Table: the table with one row per person, with the columns for the person ID, date of birth and date of death.
- Attribute Tables: tables that hold person attributes.
- Join Entity Tables: tables that hold interactions, with the columns for the ID, start, end and type. Select which features a table supports: Hierarchy Support, Time-Based Filtering Support, Multiple-Entity Support and Condition-Type Support.
- Join Entity Attribute Tables: tables that hold attributes of interactions.
- Terminology Services View Used for Catalog Attributes: the view that provides codes and their descriptions.
Placeholder settings are stored with each data model configuration.
Other Settings
- Language: the languages for which you maintain names. Select Add Language to add one.
- Query Settings: Fuzziness Threshold for text search and Max Results Set Size for value suggestions.