Understanding alerts
Understanding the pzInsKey property
Every persistent object in the PegaRULES database has an associated class (Rule-Obj-Class rule type). Pega 7 Platform uses a simple algorithm and information in Data-Admin-DB-Table instances to determine which table contains objects of which classes.
When in memory and on the clipboard, objects are known as instances and have an XML-like structure consisting of property names and text property values. These can be reviewed with the Clipboard tool.
When saved into the PegaRULES database, objects become rows of a table, with columns corresponding to scalar properties.
When newly installed, Pega 7 Platform contains over 400 concrete classes, but the initial PegaRULES database contains only 66 tables. When saving or reading an object as a row in the database, the system uses pattern inheritance based on the class name of the object to find a database table.
Pattern inheritance processing is based on dash characters in the class name. For example, for the Rule-Obj-Property-Qualifier class, the four patterns are:
To fetch an instance of the class Rule-Obj-Property-Qualifier, the system looks for database table instances (Data-Admin-DB-Table class) matching these class names in the above sequence. When a matching database table instance is found, information in that instance identifies the PegaRULES database table that contains the object as a row.
If the system does not find a table by this search, it uses pr_other table, as a last, none-of-the-above choice. For example, to locate an instance of the Data-Thorr-PurchaseOrder-Detail class, the system:
Click Test Connectivity on the Basic tab of a Class form for any concrete class to determine which table and database that Pega 7 Platform uses for instances of that class. This test works for both internal classes — mapped to the PegaRULES database — and external classes, those created by the Connector and Metadata accelerator.
Four classes are known as foundation classes:
Instances of these four classes are always stored in the pr4_base table (or another table identified in the database/baseTable entry in the prconfig.xml file or Dynamic System Setting as the base table).
Caution: Never change the database table mappings for these four classes. These classes must stay in the pr4_base table as initially installed, with the Catalog and Schema fields blank.
The primary key column for all PegaRULES tables is named pzInsKey; this corresponds to the pzInsKey property known as the internal key or handle. This permanent key is generated internally by concatenating other properties present in the instance and (for rules) from the date and time the object is first saved.
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. (For classes that are part of a class group, the class group name is used rather than the class name.)
The additional properties that make up the pzInsKey value vary from class to class, as defined in the Basic tab of the Class form for each class. For example, the pzInsKey value for a division named Finance — part of the organization Delta.com — is:
DATA-ADMIN-ORGDIVISION DELTA.COM!FINANCE
Key values contain no lowercase letters. An exclamation point character (!) and number sign character (#) appear in some pzInsKey values as separators.
Note: When you create a new table in the PegaRULES database, include a database constraint that identifies the pzInsKey column as the primary key of the table.
All tables contain these columns:
The table pr_other is the last resort or default destination for saved instances belonging to a class that is not mapped to any other table by the algorithm described above. To access the pr_other table, the system uses the catalog and schema specified for the pr4_base table (as identified the databases/baseTable/catalog and databases/baseTable/schema entries in the prconfig.xml file or Dynamic System Settings).
Each time an object is saved to the pr_other table, the system adds a PEGA0041 alert to the alert log.
Caution: This table provides a convenience during development activities, as changes to the class structure do not require changes to the database schema. However, use this facility with caution. Because the pr_other table has only a few columns, most properties are stored in the Storage Stream column of this table. Accordingly, accesses to this table — reads, updates, or deletes — are often slower than accesses to the same instance when stored as a row in a "purpose built" table.
Use of pr_other to store data for an application under development does not by itself indicate an error in database design or operations. However, use of the pr_other table is undesirable if your application requires frequent searching of rows of this table. In such a case, as a good practice, define a new table in the PegaRULES to hold instances of the class, and add a DB table instance to map instances to the new table. (Or, add a DB Table data instance to map saved instances to one of the existing tables.)
Note: You cannot use the Modify Schema tool to expose a column in the pr_other table, because (normally) no class is mapped to that table. Create a database table for the class, move the instances to that table, create a DB Table instance, then expose columns in the new table.
Most columns in the relational database schema correspond to scalar properties of property mode Single Value. The column name is the same as the property name; these are known as exposed columns.
For example, the pzInsKey column is the primary key of every table. This corresponds to the value of the @baseclass.pzInsKey property, present in every instance of every class.
Similarly, the column named pyStatusWork in the pc_work table corresponds to the property Work-.pyStatusWork, a text value with length of 32 characters or less.
Properties of many Pega 7 Platform property types, including Text, Identifier, Password, and Decimal, corresponding to string (VARCHAR) database data types. Properties of mode Integer, Double, and Number may be stored as NUMBER database data types. Techniques for storing DateTime property values differ by database vendor.
Values of properties with a mode other than Single Value (such as mode Page or Page List) are stored in a special column named pzPVStream. This column is known as the Storage Stream. Typically, this column has a BLOB (Binary Large Object) data type.
The size of the Storage Stream values can have a significant impact on memory demand, network traffic, and overall performance. To help you detect and address issues related to BLOB size, multiple types of alerts (PEGA0004, PEGA0025, PEGA0039, and PEGA0040) monitor database activity and report exceptional conditions involving Storage Stream values.
You can set up data compression for this BLOB column using the DeflateStreams setting in the prconfig.xml file or Dynamic System Settings. When enabled, compression and decompression occur on the Pega 7 Platform server and uses the java.util.ZIP class. The PDN article How to compress BLOB values in the PegaRULES database presents this feature for Version 4; the capability is similar for Version 5 using the prconfig.xml syntax.
Note: In special cases, a table may contain no BLOB column. See the PDN article How to remove an unneeded Blob column.
You can use any software that allows read-only access to the database (such as Oracle SQL Plus) to count the rows in a table. In addition, you can use the System Management application to summarize rows in a table by class.
Every database table you add to the PegaRULES database must contain these five columns:
VARCHAR2(96)DATE (This column has a different name in a few tables)VARCHAR2(64)VARCHAR2 (255) NOT NULLBLOB)Through a constraint, the pzInskey column is identified as the unique key to the table.
To ease debugging, Pega 7 Platform by default displays extensive details about those SQL operations on the PegaRULES database that fail. In a production setting, such details are not needed by users and also may disclose schema details. To reduce the detail that appears, follow the guidance in PDN article How to suppress the Show Details link after a Database Exception.
Working with the PegaRULES database