Database table primary key (handle)

The primary key column for almost all Pega Platform database tables is named pzInsKey, which corresponds to the pzInsKey property known as the internal key or handle. This permanent key is generated internally by concatenating other properties in the instance and, for rules, from the date and time the object is first saved. The key uniquely defines an instance.

Because the initial portion of the pzInsKey value contains the object class (the value of property pxObjClass ), objects of different classes can be stored together in one table with no chance of key collisions.

  • Because the pzInsKey property often contains a date and time, the system computes a handle value only when the Obj-Save method runs. Before the object is saved, the pzInsKey property is undefined.
  • The key parts defined in the class rule (the Rule-Obj-Class instance) are collectively known as the visible key.
  • When you review a handle for a rule, the creation date and time might differ from the creation date in the History tab of the rule form. The date and time on the History tab are converted to display in the time zone of the server, not GMT.
  • A handle for a rule does not explicitly identify a ruleset name or version value. The most recently created instance might not be the highest version. A relationship between versions and creation dates is not required. For example, an application developer can place a new rule in a lower version.


For example, the following handle identifies an activity named ProcessAssignment that is associated with the Assign- base class. This rule instance was created on April 10, 2016 at 23:02:19 Greenwich Mean Time: