Lookup Catalog

Lookup Catalog enables RT 2.0 Personalization to reference external business data — such as product catalogs, coupon definitions, and sale schedules — at the moment a personalization request is made. Unlike profile attributes that store per-user values, Lookup Catalog data is keyed by a non-user dimension such as product_id and is queried in real time from RT 2.0's internal storage.

Use Lookup Catalog when the personalization response must include data that varies by product, SKU, coupon, or another non-user dimension:

• Return a sale banner that contains the specific discount rate and end date for the product currently being viewed.
• Return a coupon reminder only when the user has a coupon applicable to the product they just added to the cart.
• Return product recommendation metadata keyed by the user's most recently viewed item.

If your use case requires only per-user attributes (name, tier, purchase history), use Real-time Attributes instead.

1. A data engineer prepares lookup tables in the cdp_lookup_catalog database in Data Workbench and runs a Treasure Workflow sync workflow to push the data to RT 2.0's internal storage.
2. In Audience Studio, a Lookup Catalog Attribute is created for the parent segment, linking the catalog table to a runtime lookup key (an RT attribute value).
3. When a personalization request arrives, RT 2.0 queries the matching row using the runtime key value and returns the column values as part of the offer payload.
4. The client renders the returned values — for example, the TD Web SDK renders Liquid-resolved HTML into a DOM zone or popup.

A data engineer creates and maintains lookup tables in the cdp_lookup_catalog database in Data Workbench.

• The database is typically named cdp_lookup_catalog. Any Plazma database can be used, but this name is the standard convention.
• The primary key is the first non-time column in the table — if the table's first column happens to be named time, the second column is used as the primary key instead. The primary key column must be unique, non-null, and of type string.
• Additional columns can contain string, number, boolean, or array values (array<string>, array<int>, etc.). Arrays of arrays (nested arrays) are not supported — see Limitations.
• Column names in Lookup Catalog Attribute configuration use the Plazma column name (not queryAs alias).
• Data must be deduplicated and normalized before upload — the workflow does not deduplicate.

A table limited_time_sale keyed by product_id:

A table user_product_coupon with a composite key (user_id + product_id concatenated) for cart-level coupon lookups:

Columns with array types (array<string>, array<bigint>, etc.) are fully supported. A row can have a mix of scalar and array columns.

The sync workflow reads from the cdp_lookup_catalog database and pushes changes to RT 2.0's internal storage via the Bulk Load API. Only records that have changed since the last run are uploaded (hash-based change detection).

The workflow automatically discovers all eligible tables in cdp_lookup_catalog and syncs them on each run; set the optional p_table_name parameter to restrict a run to a single table (useful for testing). For setup instructions, parameter reference, and troubleshooting, see Lookup Catalog Sync Workflow.

In Audience Studio, add a Lookup Catalog attribute to the parent segment.

1. Open the parent segment in Audience Studio.
2. Under RT Attributes, click Add Attribute and select Lookup Catalog.

3. Configure the attribute fields:

Lookup Catalog Attributes can be used in Entry Criteria in Audience Studio to gate whether a personalization section is returned at all. This is server-side decision logic — the section and its entire payload are excluded from the API response when the condition is not met, so the client does not need to implement any conditional rendering logic.

1. In Audience Studio, open the Personalization and navigate to the target section.

2. In the Entry Criteria canvas, drag and drop the Lookup Catalog Attribute you created into a condition slot.

3. Select the operator and value. For example, to return a section only when a coupon exists for the user–product combination:

   • Attribute: product_coupon → column: has_coupon
   • Operator: ==
   • Value: "true"

When this condition is not satisfied at request time, the section is omitted entirely from the personalization response.

When a Lookup Catalog column is array-typed and the lookup key is a Single-Value attribute (single-key lookup), the following operators apply:

array_matching is required when using Contain or In on an array column. The not: true flag inverts either operator.

To include Lookup Catalog Attribute values in the API response, add the attribute to the Attribute Payload section of the Personalization configuration in Audience Studio.

1. In Audience Studio, open the Personalization section configuration.
2. Under Attribute Payload, add the Lookup Catalog Attribute columns you want returned.
3. Save the configuration.

In M2, Lookup Catalog Attributes are treated as first-class attributes — they appear in the attributes sub-section of the response alongside Single, Counter, and List attributes.

When a request matches the Entry Criteria, the response includes the Lookup Catalog Attribute values under offers.<section_name>.attributes:

{
  "offers": {
    "Coupon Reminder": {
      "attributes": {
        "product_coupon - has_coupon": "true",
        "product_coupon - coupon_ids": "CPN008"
      },
      "batch_segments": null,
      "td_app": null
    }
  }
}

When the Entry Criteria condition is not satisfied (for example, no coupon exists for that user–product combination), the section is omitted entirely:

{
  "offers": {}
}

Show an inline sale banner on a product detail page only while a sale is active for that specific product.

1. Create a limited_time_sale table keyed by product_id with discount_rate and sale_end columns.
2. Create a Lookup Catalog Attribute (sale_info) using a Single-Value RT attribute that stores the current product_id as the lookup key.
3. Set Entry Criteria: sale_info.discount_rate IS NOT NULL — the section is only returned when a sale row exists for this product.

Show a coupon reminder when the user has a coupon applicable to the product they just added to the cart.

1. Create a user_product_coupon table with a composite key (user_id + product_id) and has_coupon, coupon_code columns.
2. Create a Lookup Catalog Attribute (coupon) with two lookup keys: user_id first, then product_id (RT attribute storing the most recently added product).
3. Set Entry Criteria: coupon.has_coupon == "true".

Display personalized tags based on a product's associated keywords stored as an array column.

1. Create a product_tags table with a product_id key and a keywords column of type array<string>.
2. Create a Lookup Catalog Attribute (interest_tags) using the current product_id as the lookup key.
3. Optionally set Entry Criteria: interest_tags.keywords Contain "sale" with array_matching: any.