Skip to main content

Table of Contents

Database table primary key (handle)


Only available versions of this content are shown in the dropdown

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.

Did you find this content helpful?

Have a question? Get answers now.

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

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us