Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Database table primary key (handle)

Updated on May 11, 2022

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:

  • Using handles

    The Archive tools use handles as file names for extracted rule instances as XML documents. The number sign (#) replaces the exclamation point (!) in XML file names. Certain queries display rule instances keys as handles.

  • Determining if a handle exists

    You can determine whether a handle value exists on the database by using a standard function rule or an activity.

  • Finding the handle of an object

    To find the handle of any Rule- or Data- object that has a corresponding form, open the instance using the form and select Actions > View XML and search for pzInsKey.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us