Naming standards¶
Establishing a naming standard for CDF resource types and configurations is key to successfully deploy and administer CDF projects with the Cognite Toolkit.
Separation tokens¶
In the naming standard, use separation tokens for "namespacing":
- For external IDs, use "_" (underscore).
External IDs are often used in code and configuration files and must be easily processed by code.
- For names, use ":" (colon) or "_" (underscore).
Names often appear in reports or user interfaces and should be easy to read.
Example naming standard¶
The example below sets up a project based on the Open Industry Data (OID), and uses oid as the location.
-
The location_name = oid
-
Source systems:
-
Workmate (asset and workorder data)
- Fileshare (files and 3D)
- PI (time series and data points)
CDF project
│
├── Data sets:
│ ├── extId: ds_asset_oid ── name: asset:oid
│ │ ├── Extraction pipelines:
│ │ │ └── extId: ep_src_asset_oid_workmate ── name: src:asset:oid:workmate
│ │ │
│ │ ├── RAW DB tables:
│ │ │ └── DB: asset_oid_workmate ── table: assets
│ │ │
│ │ ├── Transformations:
│ │ │ └── extId: tr_asset_oid_workmate_asset_hierarchy ── name: asset:oid:workmate:asset_hierarchy
│ │ │
│ │ └── Authorization groups:
│ │ ├── id: asset:oid:extractor
│ │ ├── id: asset:oid:prosessing
│ │ └── id: asset:oid:read
│ │
│ ├── extId: ds_files_oid ── name: files:oid
│ │ ├── Extraction pipelines:
│ │ │ ├── extId: ep_src_files_oid_fileshare ── name: src:files:oid:fileshare
│ │ │ └── extId: ep_ctx_files_oid_fileshare:annotation ── name: ctx:files:oid:fileshare:annotation
│ │ │
│ │ ├── RAW DB tables:
│ │ │ └── DB: files_oid_fileshare ── table: file_metadata
│ │ │
│ │ ├── Transformations:
│ │ │ └── extId: tr_file_oid_fileshare_file_metadata ── name: file:oid:metadata:fileshare:file_metadata
│ │ │
│ │ ├── Functions:
│ │ │ └── extId: fn_files_oid_fileshare_annotation ── name: files:oid:fileshare:annotation
│ │ │
│ │ └── Authorisation groups:
│ │ ├── id: gp_files_oid_extractor
│ │ ├── id: gp_files_oid_prosessing
│ │ └── id: gp_files_oid_read
│ │
│ ├── extId: ds_workorder_oid ── name: workorder:oid
│ │ ├── ...
│ │ ...
│ │
│ ├── extId: ds_timeseries_oid ── name: timeseries:oid
│ │ ├── ...
│ │ ...
│ │
│ ├── extId: ds_3d_oid ── name: 3d:oid
│ │ ├── ...
│ │ ...
│
└── Spaces:
└── extId: sp_apm_oid ── name: oid
Naming elements¶
- Data type: Asset, timeseries, workorder, files, 3d,... (use what is relevant for the project)
- Source: Source system (SAP, Workmate, Aveva, PI, Fileshare, SharePoint,..)
- Location: Location for asset, system, plant, installation, ...
- Pipeline type: src = source data, ctx = contextualization, uc = use case, ...
- Operation type: Type of operation/action/functionality in transformation or CDF function.
- Access type: Type of access used in authorization groups (extractor, processing, read, ...)
Data sets¶
External ID: ds_<data type>_<location>
Name: <data type>:<location>
Example: ds_asset_oid / asset:oid
Extraction pipelines¶
External ID: ep_<pipeline type>_<data type>_<location>_<source>
Name: <pipeline type>:<data type>:<location>:<source>:
Example: ep_src_asset_oid_workmate / src:asset:oid:workmate
RAW DB tables¶
DB: <data type>_<location>_<source>
Table: use name from source, or other descriptive name.
Example: asset_oid_workmate
Transformations¶
External ID: tr_<data type>_<location>_<source>_<operation type>
Name: <data type>:<location>:<source>:<operation type>
Example: tr_asset_oid_workmate_asset_hierarchy / asset:oid:workmate:asset_hierarchy
Functions¶
External ID: fn_<data type>_<location>_<source>_<operation type>
Name: <data type>:<location>:<source>:<operation type>
Example: fn_files_oid_fileshare_annotation / files:oid:fileshare:annotation
Authorization groups¶
Groups don't have external IDs. We still recommend using the same naming convention as for external IDs.
Name: gp_<data type>_<location>_<access type>
Example: gp_asset_oid_extractor / gp_asset_oid_processing / gp_asset_oid_read
Authorization security categories¶
Security categories don't have external IDs. We still recommend using the same naming convention as for external IDs.
Name: sc_<data type>_<location>_<access type>
Example: sc_asset_oid_extractor / sc_asset_oid_processing / sc_asset_oid_read
Data model spaces¶
For data model spaces, it's important to distinguish between data spaces and schema spaces.
Schema spaces store the schema for the data model, containers, views, node_types, data_models,
but not data itself. Data spaces stores data, nodes and edges.