Ga verder naar hoofdinhoud

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.

Data model spaces for data​

space: sp_<data type>_<source>
Name: <data type>:<source>
Example: sp_apm_oid / apm:oid

Data model spaces for schema​

space: sp_<model_type>_<model_identifier>
Name: <model_type>:<model_identifier>
Example: sp_enterprise_model_cognite / enterprise_model:cognite
Example: sp_solution_model_finance_predictonis / solution_model:finance_prediction
Laatst bijgewerkt