Security, Privacy, AI and CSR information for all Piano products now lives in one place. Explore our Compliance Center.
Analytics
English French
English French

Catalogs

Overview

Catalogs lets you connect your business catalogs (products, content, services, clients, and more) to your behavioral data in Piano Analytics, so your reports show business names and categories instead of technical IDs. For example, you collect only a product_id, and your reports show the product name, collection, and price.

  • Lighter tagging: you only collect identifiers (for example, product_id).

  • Automatic enrichment: Piano Analytics adds the relevant catalog information to each event, securely and on the server side.

Note: Catalogs is the evolution of a historical Piano Analytics feature: Enrichments. Enrichments that were already configured were migrated to catalogs automatically.

Before you start

Check the following before you create a catalog:

  • Reconciliation key: the property that links your events to your catalog must exist in your data model and be populated in your tagging.

  • Update context: it requires a paid option. See Update context.

  • sFTP import: Piano support must set up a dedicated server for you. See Import with sFTP.

How catalogs work

A catalog in Piano Analytics has two parts:

  • Reconciliation key: a common identifier between your events and your business catalog (for example, product_id).

  • Enriched properties: business information added automatically to your events (for example, product name or category).

When an event contains the reconciliation key, Piano Analytics adds the matching catalog values to it.

Screenshot 2025-05-14 at 17.01.05.png

Choose a context

The context determines how catalog data is applied to your events. You choose it when you create the catalog, and you can't change it afterward.

Snapshot context

The Snapshot context captures the state of the catalog at the exact moment an event occurs. The information stays frozen in time. It's included at no extra cost.

Example: a product costs €100 on January 1. Even if the price later changes to €120, the event from January 1 still shows €100.

Best for:

  • Accurate historical reporting

  • Regulatory compliance

  • A/B testing

Update context

The Update context applies the most recent version of the catalog to all events, even past ones.

Example: if a product's price changes from €100 to €120, all events now display the current price of €120.

Best for:

  • Analyses or personalizations based on the current state of the catalog

  • Continuously updated analyses

Note: the Update context is a paid option. Contact your Piano Analytics account manager for pricing and activation details.

Create a catalog

To open your catalogs, go to Data Management > Catalogs.

  1. Choose the catalog type:

    • Standard: a template recommended by Piano, with a fixed key, fixed properties, and a fixed context.

    • Custom: you configure your own reconciliation key and enriched properties.

Screenshot 2025-05-14 at 16.14.09.png
  1. Enter the main information. See Catalog settings.

Screenshot 2025-05-14 at 16.14.53.png
  1. Define the catalog structure: select the reconciliation key (for example, product_id) and the enriched properties (for example, name, category, price). See Enriched properties.

Screenshot 2025-05-14 at 16.15.14.png
  1. Import your catalog data with the method you selected in Data feed type. See Import data.

Catalog settings

You set these options when you create a catalog. You can't change the context, the reconciliation key, or its case sensitivity afterward.

  • Display name: the name of the catalog in the interface. You can customize it for a custom catalog. It's fixed for a standard catalog.

  • Context: Snapshot or Update. See Choose a context.

  • Reconciliation key: an existing property in your data model, populated in your tagging. It must be a string or an integer. For a custom catalog, you choose it freely, but keep the limit of 2 million unique values per day in mind (see Limits).

  • Case sensitive: whether the matching between your tagging and your catalog is case-sensitive.

  • Data feed type: the method you use to import your catalog: API, sFTP, or manual CSV import from the interface. This choice determines how you import your data. See Import data.

  • Alerting: an email notification when an import fails. It works for CSV imports only (manual upload or sFTP).

Enriched properties

Enriched properties are the business information that Piano Analytics adds to your events, such as a name, a category, or a price. The rules depend on the context:

  • Snapshot: properties must already exist in your data model. They must be of a simple type (not array or object) and "processed".

  • Update: you can create properties while you configure the catalog. They're then available in the Properties tab of Data Management.

In both contexts, enriched properties must share the same scope as the reconciliation key.

Properties that are also in your tagging

  • Snapshot: if the reconciliation key doesn't exist in the catalog, the tagging value is kept. If it exists, the catalog value overwrites the tagging value.

  • Update: the tagging property is never taken into account.

Import data

Three import methods are available. The method you use is the one you selected in Data feed type.

Import mode

Format

Size limit

Details

API

JSON, ndJSON

100 KB per line, 1 GB body

Programmatic import, endpoints provided

sFTP

CSV

5 GB (1 GB recommended)

Dedicated server set up by support. See Import with sFTP

Manual import

CSV

10 MB

Drag and drop or select a file in the interface

To switch an existing catalog from sFTP to API, or the other way around, contact Piano support.

The interface shows the expected format and an example that matches your catalog structure. Piano Analytics verifies imported files automatically (column presence, format errors, and so on).

CSV file requirements (sFTP and manual import)

  • Format: UTF-8, with a comma as the field separator and a period as the decimal separator.

  • Header: the first row must match your catalog structure, with the reconciliation key first. Click Download CSV Header in the Import data tab to get a ready-to-use header.

  • Dates: CSV imports don't support time zones. Send dates in UTC with a Z suffix (YYYY-MM-DDTHH:mm:ssZ). For example, send 2026-10-09T06:11:00Z for 2026-10-09T15:11:00+09:00.

Import with the API

Use the API to import your catalog programmatically, for example to push updates from your own systems. You can import line by line (JSON) or in groups (ndJSON).

  • Limits: 100 KB per line, and 1 GB in total for ndJSON.

  • Authentication: with a token. The interface shows the endpoint and an example payload for your catalog.

For endpoints and payloads, see Catalogs data in the developer documentation.

Import with sFTP

With sFTP import, you deposit CSV files on a dedicated Piano server and your catalog updates automatically. For example, your product database can export a file every night, so your enriched properties stay current without a manual upload.

Note: sFTP import is available in the EU environment only. Piano support creates the server connection: you can't configure it from the interface.

  1. Create your catalog and select sFTP as the Data feed type. See Create a catalog.

  2. Generate an SSH key pair, or ask your technical team to generate it. Keep the private key on your side and never share it.

  3. Send the public key (ssh-rsa format) and the name of your catalog to Piano support.

  4. Wait for Piano support to confirm that the connection is ready.

  5. In your catalog, go to Import data > Details to find the parameters to use (server, port, login, and folder).

  6. Upload your CSV file to the folder shown there, authenticating with your private key.

  7. Open the Processing report to check for import errors.

Deposit files directly in the folder shown in Details, not in a subfolder. Files must follow the schema defined when you created the catalog and the CSV file requirements above.

Import a CSV file manually

Use manual import to upload a CSV file of up to 10 MB directly from the interface. You can also upload a file manually whichever data feed type you selected.

  1. Open your catalog and go to the Import data tab.

  2. Download or copy the schema from the interface. Click Download CSV Header to get the expected header.

  3. Drag and drop your CSV file, or select it from your computer.

  4. Check the preview of the first 10 rows. The interface warns you about errors and missing columns, and checks that the reconciliation key and the properties are consistent.

Monitor imports

  • Processing report: shows the latest import errors for each import mode.

Screenshot 2025-05-14 at 15.19.49.png
  • Preview: shows the last 10 imported rows. Enter a value in the search bar below the table to retrieve the complete row for that key.

  • Email alert: if you turned on Alerting, you receive an email when a CSV import fails (manual upload or sFTP).

Limits

  • Unique values: the reconciliation key is limited to 2 million unique values per day. Beyond this limit, data import may be paused.

  • One catalog per property: a property can only be enriched in one catalog at a time.

  • Changes after creation: you can't change the reconciliation key, its case sensitivity, or the context after you create the catalog.

Use cases

These examples show which context fits which need.

Sales analysis by collection

Context: Snapshot. Industry: 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, and Price.

  • Historical reports always reflect the values (for example, the price) at the time of purchase.

Engagement tracking for a limited-time offer

Context: Snapshot. Industry: 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 and Offer Type.

  • Analyze the impact of the offer, even after modifications or expiration.

Dynamic user experience personalization

Context: Update. Industry: e-commerce.

Problem: you want all analyses to reflect the latest version of your catalog (for example, availability, price, or category).

Solution:

  • Collect product_id at every interaction.

  • Use an Update catalog with properties like Price and Availability.

  • All analyses and segments use the current catalog state, even for past events.

Continuous editorial category updates

Context: Update. Industry: 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

  • E-commerce and retail: product names, categories, brands, colors, sizes, prices, margin information, stock levels.

  • Media and publishing: article titles, author names, publication dates, content categories, subscription types, paywall status.

  • Financial services: account types, investment product names, risk profiles, service tiers.

  • Travel and hospitality: property names, room types, destinations, amenity lists.

Troubleshooting

  • A standard catalog is grayed out: the template is already in use for your organization, or the reconciliation key isn't validated. Check the property list in Data Management.

  • A property doesn't appear when you create a Snapshot catalog: only "processed" properties that aren't of type array or object are available.

  • A property is also in your tagging: see Enriched properties to know which value is kept.

If your question isn't answered here, contact Piano Analytics support.

Glossary

Term

Definition

Reconciliation key

Common identifier between your events and your business catalog (for example, product_id)

Enriched property

Business information added automatically to your events (for example, name, category, price)

Snapshot context

Mode where the catalog state is frozen at the time of the event

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

Last updated: