Defining composite primary keys for object-centric data models
In an object-centric data model (OCDM), object and event types are uniquely identified by a primary key (PK) to establish relationships and joins across objects and events.
For source systems where uniqueness depends on multiple attributes, composite primary keys allow you to define a primary key using more than one column directly within the data model. This configuration eliminates custom SQL concatenation loops in transformation logic, simplifies pipeline maintenance, and optimizes Prime Query Engine performance.
The Celonis Platform decouples the primary key configuration from the underlying unique ID attribute. While a unique ID attribute must always exist for every object and event type, the primary key itself can consist of multiple attributes.
Configure the primary key using one of two methods:
Single ID attribute (Legacy): A single string column acts directly as the primary key.
Composite primary key: Multiple attributes combine to form the primary key, eliminating the need for manual SQL string concatenations in your transformations.
When configuring a composite primary key, manage the mandatory unique ID attribute through one of the following approaches:
Platform auto-generation (Recommended): The Celonis Platform automatically generates and maintains the unique ID column based on the composite attributes after the data load.
Custom ID mapping: Supply a user-defined unique ID attribute directly through your transformation logic.
Verify that your environment meets the following requirements before configuring composite primary keys:
Custom data type: The target object or event must be a custom type. You cannot apply a composite primary key to a standard Celonis type.
Relationship isolation: Confirm the custom type does not require relationships with any standard Celonis types that reference its primary key. Applying a composite key prevents these relationships from forming.
Augmented attribute review: Identify any existing Augmented Attributes associated with the object. You must recreate these attributes after modifying the key structure to align them with the new composite primary key.
Review the source system table metadata for the target object or event.
Identify the unique column combination that forms the logical key (for example:
Client_ID+Company_Code).Verify that all identified key elements are stable, completely non-null, and do not use floating-point data types.
Match the data type of each corresponding foreign key attribute in your source tables exactly to these primary key attributes.
Click Data Integration → Objects and Events and select your target OCPM data pool.
Click your custom object or event type, or click Create New.
Navigate to the primary key configuration section, select Composite Primary Key, and check the boxes for your specific source attributes.
Select Auto-generate ID to allow the platform to maintain unique ID records automatically after loading data.
Open your relationship configuration screen and map variables based on relationship parameters:
Object-to-Object (1:N / M:N): Map source object PK attributes to target object FK attributes. Do not reference the unique ID attribute unless it serves explicitly as your primary key.
Event-to-Object (E2O): Map event FK attributes directly to object PK attributes. For "involves many" relationship definitions, update your extraction parameters to point to your exact source PK attributes.
Open the data transformation script for the modified object or event.
Delete legacy ID concatenation, matching, or explicit casting strings from the SQL logic to allow the engine to process raw attributes directly.
Save and validate the transformation engine parameters.
Locate any active PQL statements or KPIs referencing old metadata properties (such as
RelationshipName_ID).Replace those references with the actual foreign key columns used in your consolidated relationship structure, then validate your views and dashboards.
Tip
Removing manual SQL concatenation strings is required to trigger Prime Query Engine acceleration benefits.
Trigger a data load for the modified data pool environment.
If you modified an existing object or event primary key, re-verify and adjust any affected secondary components manually:
Recreate 1:N O2O relationships with correct PK–FK mappings.
Update active M:N O2O relationship transformation tasks.
Recreate "involves one" and update "involves many" E2O transformations to realign pipeline execution paths.
Run sample PQL queries within the Prime Query Engine environment to check join behaviors, validate cardinally balances, and ensure no duplicate records populate the target model.
Note
The platform auto-generates composite ID strings sequentially after the data pipeline load completes; do not reference these backend values inside data transformations.