Catalogs
Overview
Catalogs allows you to automatically connect your business catalogs (products, content, services, clients, etc.) to your behavioral data in Piano Analytics. No more analysis limited to technical IDs: your reports gain full business meaning, with no implementation complexity.
Catalogs is the evolution of a historical Piano Analytics feature: Enrichments. For clients who had already configured enrichments, these were automatically migrated to catalogs.
Why Catalogs?
Every organization has structured business catalogs (products, content, clients, etc.). These catalogs are key to understanding how your users interact with what really matters to you.
With Catalogs:
You only collect identifiers (e.g., product_id)
Piano Analytics automatically enriches each event with all relevant catalog information, securely and server-side.
How it Works
A catalog in Piano Analytics consists of:
A reconciliation key (e.g., product_id): a common identifier between your events and your business catalog.
Enriched properties: business information automatically added to your events (e.g., product name, category).
Workflow Diagram

The Two Contexts: Snapshot and Update
When creating a catalog, you choose a context that determines how catalog data is applied to your events.
1. “Snapshot” Context
Captures the state of the catalog at the exact moment the event occurs.
The information is frozen in time.
Example:
A product costs €100 on January 1st. Even if the price later changes to €120, the event from January 1st will always show €100.
Best for:
Accurate historical reporting
Regulatory compliance
A/B testing
2. “Update” Context
Applies the most recent version of the catalog to all events, even those in the past.
Example:
If a product’s price changes from €100 to €120, all events will now display the current price of €120.
Best for:
Analyses or personalizations based on the current catalog state
Continuously updated analyses
The update context is a paid option.
To activate it, contact your Piano Analytics account manager for pricing and activation details.
Creating and Managing a Catalog
Access
Menu Data Management > Catalogs
Main Steps
Choose the catalog type
Standard: pre-configured template recommended by Piano (fixed key and properties)
Custom: configure your own reconciliation key and enriched properties

Enter main information
Display name: name of the catalog as shown in the interface
Context: snapshot or update (see above)
Reconciliation key: an existing property in your data model, populated in your tagging
Case sensitivity: whether the matching is case-sensitive or not
Data Feed Type: method for importing your business catalog (API, sFTP, or manual CSV import via the interface)
This choice determines how you’ll import your data (see Data Import for details).Alerting: email notification in case of import failure (for CSV imports)

Define the catalog structure
Reconciliation key (e.g., product_id)
Enriched properties (e.g., name, category, price)

Tip: For Snapshot context, enriched properties must already exist in your data model. For Update, you can create them during configuration.
For advanced details (property management, limits, validations), see the appendix at the end of the doc.
Data Import
Three import modes are available:
Import Mode | Format | Size Limit | Details |
---|---|---|---|
API | JSON, ndJSON | 100KB/line, 1GB body | Programmatic import, endpoints provided |
sFTP | CSV | 5GB (1GB recommended) | Dedicated server, request setup from support |
Manual Import (UI) | CSV | 10MB | Drag & drop or select file via interface |
The interface guides you on the expected format and provides an example matching your structure.
Automatic verification of imported files (column presence, format errors, etc.).
For exact formats, example files, error handling, see the appendix.
Monitoring and Alerts
Processing report: view the latest import errors (by import mode).
Preview data: see the last 10 imported rows and filter by a specific key.
Use Cases
Snapshot context
1. Sales analysis by collection (e-commerce)
Problem: You want to measure the performance of each collection at a specific point in time, even when prices or ranges change.
Solution:
Collect only the
product_id
during purchases.Use a Snapshot catalog with properties like
Product Name
,Collection
,Price
.Historical reports will always reflect the values (e.g., price) at the time of purchase.
2. Engagement tracking for a limited-time offer (media)
Problem: You launch a special offer on certain content and want to keep track of the offer’s status at each interaction.
Solution:
Collect the
content_id
for each view.Use a Snapshot catalog with properties like
Content Name
,Offer Type
.Analyze the impact of the offer, even after modifications or expiration.
Update context
1. Dynamic user experience personalization (e-commerce)
Problem: You want all analyses to reflect the latest version of your catalog (e.g., availability, price, category).
Solution:
Collect
product_id
at every interaction.Use an Update catalog with properties like
Price
,Availability
.All analyses and segments use the current catalog state, even for past events.
2. Continuous editorial category updates (media)
Problem: Your content sections change regularly and you want your analyses to always be up to date.
Solution:
Collect
content_id
for each consultation.Use an Update catalog with the
Section
property.Dashboards always reflect the current section, even for older articles.
Other use cases
For E-commerce/Retail: Product names, categories, brands, colors, sizes, prices, margin information, stock levels.
For Media/Publishing: Article titles, author names, publication dates, content categories, subscription types, paywall status.
For Financial Services: Account types, investment product names, risk profiles, service tiers.
For Travel/Hospitality: Property names, room types, destinations, amenity lists.
FAQ
Q: I want to use a standard catalog, but it’s grayed out. Why?
A: The template is already in use for the organization, or the reconciliation key is not validated. Check the property list in Data Management.
Q: Why doesn’t a property appear when creating a Snapshot catalog?
A: Only “processed” properties that are not of type array object are available.
Q: What happens if an enriched property is also present in my tagging?
A:
Snapshot: If the reconciliation key doesn’t exist, the tagging value is kept. If it exists, the catalog value overwrites the tagging value.
Update: The tagging property is never taken into account.
Q: Who can use the Update context?
A: The Update context is a paid option. Contact your account manager for more information.
Glossary
Term | Definition |
---|---|
Reconciliation key | Common identifier between your events and your business catalog (e.g., product_id) |
Enriched property | Business information automatically added to your events (e.g., name, category, price) |
Snapshot context | Mode where the catalog state is frozen at the event time |
Update context | Mode where the latest catalog state is applied to all events |
Data Feed Type | Method for importing your catalog (API, sFTP, manual CSV) |
Standard catalog | Catalog template offered by Piano Analytics, ready to use |
Custom catalog | Catalog configured to your needs, with your own properties and reconciliation key |
Advanced Details (Appendix)
Creation and Management – Details
Standard vs. Custom
Standard: templates provided by Piano with fixed key and properties, fixed context.
Custom: freely choose the reconciliation key (beware of the 2 million unique values/day limit), customizable enriched properties.
Display name
Customizable for custom catalogs, fixed for standard ones.
Reconciliation key
Must exist in your data model and be populated in the tagging.
Case sensitivity: defines if matching is case-sensitive (cannot be changed after creation).
Enriched properties
Snapshot: must be pre-declared in the data model, simple type (not array object), and “processed.”
Update: can be created during catalog configuration, available later in the “Properties” tab of Data Management.
Data Feed Type
API: programmatic import via Piano endpoints.
sFTP: automated import by depositing CSV files on a dedicated server.
Manual import (UI): drag and drop or file selection directly in the interface.
Alerting
Email notification system configurable for CSV imports (drag & drop or sFTP).
Import – Details
API
Possible to import line by line (JSON) or grouped (ndJSON).
Limits: 100KB/line, 1GB total for ndJSON.
Token authentication, endpoint and payload example provided in the interface.
Developer documentation is available here.
sFTP
Dedicated server created on request via Piano Analytics support.
CSV files, max 5GB (1GB recommended for performance).
Must follow the schema defined at catalog creation.
Manual import (UI)
CSV file, max 10MB.
Downloadable or copyable schema from the interface.
Automatic verification: presence of reconciliation key, property consistency, preview of the first 10 rows.
Notifications in case of error or missing columns.
Error handling
Processing report available for each import, differentiated by import mode.
Email alert in case of failure (if configured).
Limitations and Tips
Limit of 2 million unique values per day on the reconciliation key: beyond this, the catalog may be paused.
Enriched properties: a property can only be enriched in one catalog at a time.
Modification: the reconciliation key and context cannot be changed after catalog creation.
Availability:
Snapshot context: included at no extra cost.
Update context: paid option, contact your account manager.
For any questions, refer to the FAQ or contact your Piano Analytics support if needed.