Skip to main content
Verify the version tags to ensure you are consuming the intended content or, complete the latest version.

Data relationships

Relationships between data objects

A data object is a template for describing an entity through fields, such as name and address. A data relationship is a container in which you associate a set of related fields. You can use data relationships to create relationships between data objects and also between cases. A data relationship does not store data itself but instead relates data.

For example, when customers sign up for a video streaming account, they provide basic information such as first name, last name, and email. The value provided in the email field must be associated with the customer's first and last name because that email belongs to the customer. The system can capture the three associated values in a Customer data relationship.

In the Customer data relationship example, the data relationship establishes a common context for the first name, last name, and email fields. These fields all contain data that describe a customer, as shown in the following image.


Data relationships with multiple records

You can configure data relationships to reference a single record or multiple records. The difference is that a multiple record data relationship references a list of grouped values. A single record data relationship references only a single set of values. The Customer data relationship example in the previous section demonstrates a single record data relationship.

Consider a video streaming company that runs marketing campaigns by using customer information collected when users sign up for an account. The Campaign case type uses a Current Customers multiple record data relationship. The Current Customers data relationship includes records for each customer.

In the center of the following image, slide the vertical line to view the customer data with multiple records on the left and the system configuration on the right.

Check your knowledge with the following interaction:

Data in data relationships

 A case type or data object defines the data model for the data relationship. You can create a data relationship either by creating a new data object or by using an existing data object or case type. In the following Resident submissions multiple record data relationship example, the Person data object defines the data model for the data relationship.


Each data relationship does not have to use all the defined fields, but they are all available. For example, you can use a Customer data relationship to capture customer information for users, including first name, last name, email, user name, and password. You can use the same Customer data relationship to display information on the Confirmation page. Because the user needs to confirm only the full name and email, the user name and password are not displayed. The fields remain part of the Customer data object and are referenceable in another view.

A data relationship with multiple records serves as a template for each grouped field instance. In a multiple record data relationship, each value follows the field type configuration settings. For example, you want to collect a job applicant's references in a multiple record data relationship that includes the reference's full name, company, contact number, and email. You can configure the Full Name and Contact Number fields as required values, so each new field under the Full Name and Contact Number columns has the same settings. In the following image, the applicant receives an error message when they do not enter a contact number for Shaun Mills.


You can also configure a multiple record data relationship to allow end users to add, delete, or update items as needed. For example, the References data relationship is displayed as a table with three groups or rows of related values. An applicant can add a fourth reference to the list by clicking Add item.

A data object can contain other data objects. Similarly, a data relationship can contain other data relationships. For example, in an online shopping application, customers can have multiple credit cards associated with an account. The Customer entity is a single record data relationship in the application, and the Credit Cards entity is a multiple record data relationship. Each entity has a relationship with a respective data object.

In the following image, the Customer entity captures and associates the customer's full name, username, password, and credit cards to the referenced data object. Within the Customer entity, the Credit Cards entity captures and associates the card number, expiration date, and verification code to the referenced data object. Each customer can store multiple credit cards on the account, adding, deleting, and updating card information as needed.


Field types and data object location

Because there are many different use cases for data relationships, there are several field types to support different configurations. Consider where the data object is sourced when determining what field type to use. If the data object does not need to be sourced from outside of the case, such as a shipping address, use an Embedded data field type. If the data object needs to be sourced outside of the case, there are specialized field types to account for several use cases, including Query and Reference. The table below describes each data relationship field type and its associated data source. 

Data relationship field type Data source Use case
Embedded data User-supplied data such as a name and address sourced from inside a case type.  A company needs to capture shipping addresses.
Query  A data page or view that is not sourced from inside the case type. The data page defines parameters that the Query data relationship is configured to use. An application needs to update the current weather.
Case reference Single or multiple records from a selected case type. A user selects from a list of service cases from the Service Case type.
Data reference

Single or multiple records from a selected data page.

A user selects from a list of products to order.

The following sections outline each of the field types and their use cases.

Sourcing user-supplied data

Use an Embedded data field when data is sourced from a user interaction that is made inside a case type, such as entering a name or address. The information is embedded in the case and is not referenced independently of the case. For example, Pega Platform™ provides an out-of-the-box data object for postal addresses (Data-Address-Postal). Instead of defining all of the address fields that make up an address in a case type to capture address information, a user can build an embedded field of the data object type Postal address, allowing the user to reuse an already defined data structure.

Use cases for Embedded data include any circumstance in which a user provides data during the case, like a name or address. Consider a service request case where a customer would provide a brief description of an issue so that a service provider can be dispatched. The issue description is not sourced from a data page but is instead provided by the customer. 

Sourcing data users do not supply

Case processing often requires access to data sourced from other applications or systems. In Pega Platform™ applications, a data page retrieves data from a specified data source and caches that data in memory. A Query field type is used to define a field that the system can use to consistently access data sourced outside of the case. A Query field references a data page that defines the source of your data. This is true for either multiple or single record configurations. 


Reference field types

Consider the Case reference and Data reference field types as specialized versions of the Query field type, used to define a selectable item or list of explicitly referenced items by their identifier or key. The user selects parameters for reference field types through the UI. 

Reference field types are used to show a user a list of options they can choose from. Users can choose from one option in a single record type (choose a primary account holder) or many options in a multiple record type (choose products to order). Most use cases for savable data pages use a Reference field type but could also use the Query field type. 

Check your knowledge with the following interaction:

This Topic is available in the following Module:

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

19% found this content useful

Want to help us improve this content?

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

Pega Academy 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