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

# Oil and Gas Data Model reference

> Deploy a CFIHOS 2.0 and ISO 14224-based data model for oil and gas operations with denormalized, AI-ready views for AVEVA, SAP, OPC UA, and PI source systems.

The **Oil and Gas Data Model deployment pack** (`dp:models:cfihos_oil_and_gas_extension`) provides a tag-centric data model for oil and gas operations that merges data from AVEVA, SAP, OPC UA, and PI into a single queryable structure. Built on the CFIHOS 2.0 standard and ISO 14224, it deploys as Cognite Toolkit modules that extend the Cognite Core Data Model (CDM) and Industry Data Model (IDM).

The model favors **simplicity and denormalization** over strict normalization: related properties are flattened into fewer, wider views so a single query returns everything needed about an entity without complex joins.

<Note>
  The Oil and Gas model is delivered as cherry-pickable modules (`dp:models:cfihos_oil_and_gas_extension` and its search module) inside the single **Data models** deployment pack (`dp:models`). "Data models" is one pack — selecting it in the Toolkit lets you choose the model(s) you need without deploying the others.
</Note>

## Who it's for

**Target personas:**

* **Data engineers** — deploy and configure the model with the Cognite Toolkit.
* **Data modelers** — extend the CFIHOS 2.0 / ISO 14224 model for your project.
* **Subject matter experts** — reliability and maintenance engineers who validate equipment and failure data.

**Use this pack when:**

* You are setting up a new CDF project for oil and gas or energy operations and need a CFIHOS-compliant data model without building it from scratch.
* You need to integrate data from AVEVA, SAP, OPC UA, and PI (or similar sources) into a unified, queryable structure.
* You want AI-readable views, denormalized search models, and CDM/IDM compliance out of the box.
* You are extending an existing CDF project with a standardized equipment and maintenance data model.
* You want a reference model to compare against an existing data model.

**When not to use this pack:**

* If your project does not use data sources similar to AVEVA, SAP, OPC UA, or PI and requires a fundamentally different source schema — this model will need significant adaptation.
* If your project is manufacturing-focused, use the [ISA Data Model](/cdf/deploy/cdf_toolkit/references/packages/isa_data_model) deployment pack instead.

## What's included

| Component                                      | Description                                                                                                                                                                            | Optional? |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `cfihos_oil_and_gas_extension`                 | Enterprise module — owns containers, indexes, and canonical CDM/IDM-implementing views. Treated as the durable contract.                                                               | No        |
| `cfihos_oil_and_gas_extension_search`          | Solution module — search-optimized views mapped to enterprise containers, including reverse relations (`Tag.workOrders`, `Tag.timeSeries`, `Tag.notifications`, and others).           | Yes       |
| 17 CFIHOS equipment class views                | Class-specific containers and views per CFIHOS 2.0 taxonomy (Compressor, Valve, Pump, HeatExchanger, and 13 more), linked to Tag via polymorphic direct relations.                     | No        |
| Work management views                          | WorkOrder, WorkOrderOperation, and Notification extending IDM types (`CogniteMaintenanceOrder`, `CogniteOperation`, `CogniteNotification`).                                            | No        |
| Connection transformations                     | Populate key direct relations: Tag → FunctionalLocationProperties, Tag → CommonLCIProperties, Tag → classSpecific, Notification → FailureMode.                                         | Yes       |
| Workflow (`wf_cfihos_oil_and_gas`)             | Dependency-aware orchestration of all transformations; reads from RAW tables and populates data model instances in the correct order. Only relevant for the provided test data in RAW. | Yes       |
| RAW seed data (CSV)                            | Sample data for testing and validating the model end-to-end without production source data.                                                                                            | Yes       |
| CFIHOS code generator (`cfihos_model_config/`) | Python tool to scaffold new CFIHOS equipment class containers and views from the standard (supports CFIHOS 1.5.1 and 2.0).                                                             | Yes       |

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

* The data plugin is enabled in `cdf.toml` — required for the `cdf data upload` step that loads the seed data after deployment:

  ```toml theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  [plugins]
  data = true
  ```

* You can enable feature flags for your CDF project in Cognite Unleash, or can request it from your CDF administrator.

## Install and deploy

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

<Tabs>
  <Tab title="Add to an existing project">
    Add the modules from your project directory:

    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf modules add -d cfihos_oil_and_gas_extension cfihos_oil_and_gas_extension_search
    ```
  </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 **Data models**, use **Space** to select **CFIHOS Oil And Gas Data Model template** and **CFIHOS Oil And Gas Search Solution Model**, then press **Enter** to confirm.
  </Tab>
</Tabs>

The Toolkit creates the modules under `modules/datamodels/` 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>

After deployment, your project should include:

```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
modules/
└── datamodels/
    ├── cfihos_oil_and_gas_extension/
    └── cfihos_oil_and_gas_extension_search/
```

To test and validate the model end-to-end, upload the included seed data (RAW tables and files) that the `wf_cfihos_oil_and_gas` workflow reads from:

```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf data upload dir modules/datamodels/cfihos_oil_and_gas_extension/upload_data/raw
cdf data upload dir modules/datamodels/cfihos_oil_and_gas_extension/upload_data/Files
```

<Note>
  The data plugin must be enabled in `cdf.toml` (see [Prerequisites](#prerequisites)) before running `cdf data upload`. Skip this step if you are populating the model from your own source systems instead of the seed data.
</Note>

After deploying, enable the `FDX_VIEW_SWITCHER` feature flag in Cognite Unleash for your CDF project. This enables view navigation, relationship visualization, and enhanced data model exploration in the CDF UI.

<Note>
  Feature flags are project-specific — make sure you enable `FDX_VIEW_SWITCHER` for the correct CDF project. Contact your CDF administrator if you do not have Unleash access.
</Note>

## Verify the deployment

After deploying, confirm success with these checks:

1. The `cdf deploy` command finishes without errors and reports successful deployment of spaces, containers, views, data models, transformations, and the workflow.
2. In CDF, navigate to **Data Modeling > Spaces** and verify that the enterprise and search spaces (`dm_dom_oil_and_gas` and `dm_sol_oil_and_gas_search` by default, or your configured names) both exist.
3. Navigate to **Data Modeling > Data Models** and verify that both the CFIHOS Oil and Gas enterprise model and the search solution model are listed and can be opened.
4. Open the CFIHOS enterprise data model and verify that key views are present: `Tag`, `Equipment`, `WorkOrder`, `WorkOrderOperation`, `Notification`, `Files`, `TimeSeriesData`, `FailureMode`, and `FunctionalLocationProperties`.
5. Navigate to **Data Modeling > Containers** and verify that the expected CFIHOS containers have been deployed in the enterprise space.
6. If you uploaded the seed data, navigate to **Integrate > Staging (RAW)** and confirm the seed tables are present.
7. Navigate to **Workflows > wf\_cfihos\_oil\_and\_gas**, trigger the workflow, and confirm it completes without errors. All transformations should show a successful execution status.

The deployment is successful when both spaces exist, all views are accessible in CDF, and the workflow has completed without errors.

## Configuration reference

Parameters are set in `config.dev.yaml` at the project root. Default values work for an initial test deployment.

Each parameter takes its default unless you override it. Where the default is `—`, you must provide your own value before deploying.

**Enterprise module (`cfihos_oil_and_gas_extension`)** — set in its `default.config.yaml`:

| Parameter                | Description                                                                     | Default                       |
| ------------------------ | ------------------------------------------------------------------------------- | ----------------------------- |
| `project`                | CDF project external ID to deploy to.                                           | —                             |
| `space`                  | Primary space for the enterprise containers, views, and data model.             | `dm_dom_oil_and_gas`          |
| `instance_space`         | Space where node and edge instances are stored (shared with the search module). | `inst_location`               |
| `search_space`           | Space shared with the search solution module.                                   | `dm_sol_oil_and_gas_search`   |
| `dm_version`             | Version identifier for the enterprise data model.                               | `v1`                          |
| `data_model_external_id` | External ID of the enterprise data model.                                       | `dm_oil_and_gas_domain_model` |
| `dataset_external_id`    | CDF dataset used for all resources in the module.                               | `ds_oil_and_gas_domain_model` |
| `workflow_version`       | Version of the data workflow definition.                                        | `v1`                          |

**Search module (`cfihos_oil_and_gas_extension_search`)** — set in its `default.config.yaml`:

| Parameter                       | Description                                                                        | Default                              |
| ------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------ |
| `enterprise_space`              | Space owning the enterprise containers (must match the enterprise module `space`). | `dm_dom_oil_and_gas`                 |
| `enterprise_dm_version`         | Enterprise view version used for direct-relation source views.                     | `v1`                                 |
| `search_space`                  | Space for the search solution model and its `Search*` views.                       | `dm_sol_oil_and_gas_search`          |
| `instance_space`                | Shared instance space (must match the enterprise module `instance_space`).         | `inst_location`                      |
| `search_dm_version`             | Version of the search solution model.                                              | `v1`                                 |
| `search_data_model_external_id` | External ID of the search solution model.                                          | `dm_oil_and_gas_domain_model_search` |

<Note>
  The enterprise module and the search module version independently. Bumping `search_dm_version` does not require a change to `dm_version`, and vice versa. Deploy the enterprise module before the search module — the search views map to the enterprise containers.
</Note>

## Architecture

The model splits into two independently versioned modules. The enterprise module owns the containers (the durable contract) and CDM/IDM-implementing views. The search module maps to those enterprise containers and hosts solution-shaped views with reverse relations. Both modules expose views named `Tag`, `Equipment`, `WorkOrder`, and others — they live in different spaces so there is no collision, and consumers get consistent view names whether they read the enterprise or the search model.

### How the views connect

`Tag` is the central asset node and the single `CogniteAsset` implementer. In the enterprise model, the equipment, work-management, time series, file, and context views all hold the direct relation **to** `Tag`, while `Tag` itself carries only its hierarchy (`parent`) and a few context relations. The matching reverse relations (`Tag.workOrders`, `Tag.timeSeries`, and others) live on the search module's `Tag` view. The diagram below shows the enterprise direct relations, labeled with the property that defines each relation.

```mermaid theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
flowchart TD
    Tag["Tag · CogniteAsset"]
    Equipment["Equipment · CogniteEquipment"]
    WorkOrder["WorkOrder · CogniteMaintenanceOrder"]
    WorkOrderOperation["WorkOrderOperation · CogniteOperation"]
    Notification["Notification · CogniteNotification"]
    TimeSeriesData["TimeSeriesData · CogniteTimeSeries"]
    Files["Files · CogniteFile"]
    FailureMode["FailureMode · CogniteDescribable"]
    FunctionalLocationProperties["FunctionalLocationProperties"]
    CommonLCIProperties["CommonLCIProperties"]
    FunctionalLocation["FunctionalLocation"]
    EquipmentClasses["CFIHOS equipment class views (17)"]

    Tag -->|parent| Tag
    Tag -->|FunctionalLocationProperties| FunctionalLocationProperties
    Tag -->|CommonLCIProperties| CommonLCIProperties
    Tag -.->|classSpecific, polymorphic| EquipmentClasses
    Equipment -->|asset| Tag
    Equipment -->|files| Files
    WorkOrder -->|mainAsset| Tag
    WorkOrder -->|equipment| Equipment
    WorkOrder -->|timeSeries| TimeSeriesData
    WorkOrderOperation -->|maintenanceOrder| WorkOrder
    WorkOrderOperation -->|mainAsset| Tag
    WorkOrderOperation -->|equipment| Equipment
    WorkOrderOperation -->|functionalLocation| FunctionalLocation
    Notification -->|maintenanceOrder| WorkOrder
    Notification -->|asset| Tag
    Notification -->|failureMode| FailureMode
    TimeSeriesData -->|assets| Tag
    TimeSeriesData -->|equipment| Equipment
    Files -->|assets| Tag
    FailureMode -->|assets| Tag
```

The diagram shows direct relations only; their reverse relations live on the search module. The 17 CFIHOS equipment class views (Compressor, Valve, Pump, HeatExchanger, and others) attach through the polymorphic `Tag.classSpecific` relation, which omits a fixed `source` so it can point to any class view. `MaintenanceAndIntegrity` shares the `Tag` container key rather than defining a view relation, so it is omitted here.

### CDM extensions (`cdf_cdm`)

| View                | Extends            | Purpose                                                                                                                                       |
| ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Tag                 | CogniteAsset       | Central asset node — the single `CogniteAsset` implementation. Connects equipment, work orders, time series, files, and functional locations. |
| Equipment           | CogniteEquipment   | Physical equipment with class, type, model, and standard references. EquipmentType properties are denormalized directly onto this view.       |
| Files               | CogniteFile        | Document, revision, and file metadata combined into one flat view for one-shot document retrieval.                                            |
| TimeSeriesData      | CogniteTimeSeries  | PI and OPC UA properties merged into one view with `pi_*` and `opcua_*` prefixes.                                                             |
| FailureMode         | CogniteDescribable | ISO 14224 failure modes linked to equipment and notifications.                                                                                |
| CommonLCIProperties | CogniteDescribable | Common lifecycle information shared across tags.                                                                                              |

### IDM extensions (`cdf_idm`)

| View               | Extends                 | Purpose                                                             |
| ------------------ | ----------------------- | ------------------------------------------------------------------- |
| WorkOrder          | CogniteMaintenanceOrder | SAP work orders with scheduling, status, and planner group details. |
| WorkOrderOperation | CogniteOperation        | Individual operations within work orders.                           |
| Notification       | CogniteNotification     | Maintenance notifications with failure analysis properties.         |

### Domain-specific views (no CDM/IDM base)

| View                            | Purpose                                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
| FunctionalLocationProperties    | SAP functional location hierarchy with criticality and discipline.                                       |
| MaintenanceAndIntegrity         | Maintenance and integrity properties linked to tags.                                                     |
| 17 CFIHOS equipment class views | Class-specific properties per CFIHOS 2.0 taxonomy (Compressor, Valve, Pump, HeatExchanger, and 13 more). |

### Record containers (no view)

| Container   | Purpose                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| AlarmRecord | OPC UA alarm events stored using Records and Stream service (`usedFor: record`); queried directly against the container. |

### Key design decisions

**Denormalization over joins.** PI and OPC UA properties are merged into `TimeSeriesData` with `pi_` and `opcua_` prefixes. A single query returns source tag, point type, data type, and engineering units without additional lookups. The same principle applies to `Files` (document, revision, and file flattened) and `Equipment` (equipment and equipment type denormalized together).

**Single `CogniteAsset`.** Only `Tag` implements `CogniteAsset`. This avoids UI navigation conflicts in CDF applications (Industrial Canvas, Asset Explorer) that expect one asset hierarchy. Equipment, functional locations, and other entities link to tags via direct relations.

**Polymorphic equipment classes.** The `classSpecificProperties` direct relation on `Tag` omits a `source` view — it can point to any of the 17 CFIHOS equipment class views. A dedicated connection transformation populates this relation by matching `Tag.externalId` to class-specific node IDs.

<Warning>
  **Naming note — `labels` vs `tags`:** Because the `CogniteAsset` view is named `Tag` in this model, the inherited `tags` property from `CogniteDescribable` creates a naming conflict. The view exposes this property as `labels`. In transformations, queries, and API access, always use `labels` — never `tags` — when referring to the text-based label list. Using `tags` may be interpreted as a reference to the `Tag` view itself, leading to errors or unexpected results.
</Warning>

## Troubleshooting

| Symptom                                            | Likely cause                                                                    | Resolution                                                                                                                                                    |
| -------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cdf auth verify` fails with 401 Unauthorized      | Missing or incorrect credentials in `.env` file.                                | Run `cdf auth init`, re-enter credentials, then re-run `cdf auth verify`.                                                                                     |
| Module files unexpectedly overwritten              | Ran `cdf modules init . --clean` without committing changes first.              | Commit or stash local changes before running the command. Use `cdf modules add` for existing projects to avoid this risk.                                     |
| `cdf build` fails with "data plugin not enabled"   | `[plugins] data = true` is missing from `cdf.toml`.                             | Add `data = true` under `[plugins]` in `cdf.toml` and retry.                                                                                                  |
| `cdf deploy` fails with "Insufficient permissions" | Toolkit service account is missing required CDF capabilities.                   | Add `spaces:write`, `datamodels:write`, `transformations:write`, `workflows:write`, `datasets:write`, and `rawdb:write` to the CDF group used by the Toolkit. |
| Workflow `wf_cfihos_oil_and_gas` fails             | RAW source tables are missing or incorrectly named.                             | Verify that the RAW database and tables exist with the expected names, or populate them with the included seed CSV data and re-trigger the workflow.          |
| Views show no instances after deployment           | Transformations have not been executed yet.                                     | Trigger `wf_cfihos_oil_and_gas` from the CDF Workflows UI and wait for it to complete.                                                                        |
| `Tag.tags` returns unexpected results              | Using `tags` instead of `labels` for the text-based label list on the Tag view. | Use `labels` in transformations, queries, and API access. See the naming note in Architecture.                                                                |

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                                                                        |