Semi-structured dimensions

This is for:

Business Analyst System Administrator

dimensions are an essential feature in Coveo Usage Analytics (Coveo UA) for building comprehensive reports and for inspecting user visits in the Coveo Administration Console.

Semi-structured dimensions are similar to regular custom dimensions, except they offer further precision by allowing you to select any data element in the JSON configuration.

Example
{
    "a": "author",
    "b": {
        "book": true,
        "binder": "yes"
    },
    "c": {
        "d": {
            "e": 1001
        }
    }
}

With regular custom dimensions, the only choices available are a, b or c. The contents of b or c would be a JSON map, which isn’t ideal for reporting.

However, with semi-structured dimensions, you can select any element in the JSON map. For example, you can create a dimension that targets c;d;e, the output of which is 1001.

Important

Custom data can only be leveraged when using the UA Protocol. If you’re using the Event Protocol, keep in mind that custom fields have been replaced by predefined events and dimensions. To learn more about the available protocols, see Track usage analytics.

Retrieve custom data

Before adding semi-structured dimensions, you must first retrieve the path that’s required to access the data. You can achieve this by performing an export in the Visit Browser, or through the Snowflake reader account.

Retrieve custom data through the Visit Browser

  1. On the Visit Browser (platform-ca | platform-eu | platform-au) page, add a custom event filter.

  2. Modify the date interval as needed, and then click Export.

  3. In the Data Exports tab of the Raw Data (platform-ca | platform-eu | platform-au) page, export the visit data that meet your criteria.

  4. Open the data export CSV file in a spreadsheet application.

  5. In the spreadsheet, locate the customData column and select a cell to access the event data for a specific visit.

  6. Copy the event data into an integrated development environment (IDE) or a trusted JSON formatter to format it.

    Once you’ve formatted the JSON data, the path levels are visible as they’re always indented under the selected event. You can now retrieve the path level that’s required to add to the Step field in the Add a dimension panel.

For a detailed example of using semi-structured dimensions wherein the path is extracted through the Visit Browser export, see Generate Case Assist reports.

Retrieve custom data through the reader account

  1. In the Snowflake Reader Account tab of the Raw Data (platform-ca | platform-eu | platform-au) page, access your Snowflake reader account.

  2. Sign in to Snowflake.

  3. At the upper-right corner, click the dropdown menu and select the coveo database and the ua schema.

  4. In the query input section, enter a query (for example, select "custom_datas" from "all_events_shared" where "event_type" = 'caseCreation' limit 10), and then click Run.

  5. In the custom_datas column, click the applicable row, and the JSON output is displayed in the Details panel.

    The path levels are visible as they’re always indented under the selected event. You can now retrieve the path level that’s required to add to the Step field in the Add a dimension panel.

Add semi-structured dimensions

You can add semi-structured dimensions on the Add a dimension panel by selecting the Semi-structured dimension checkbox and then adding the desired path (see Add Dimensions on Custom Metadata for further information).

Notes

  • The dimension name and the path element must be distinct, since the API name can only contain alphanumeric characters and underscores.

  • There must not be another dimension with that API name.

Limitations

Path elements in a semi-structured dimension:

  • Must be between 1 and 5 elements long.

  • Must be less than 255 characters (including periods between the elements, and a c_ prefix that Coveo UA adds to the first element).

  • Can’t be null.

  • Can’t consist solely of whitespace.

  • Can’t contain array-index notations (for example, a[10]).

  • Can’t be edited after it’s created.

  • Are case-sensitive from the second level onward.

You can’t create a dimension with a path that’s already covered by another dimension.

Examples

  • If you have a dimension with the path equal to [a, b], you can’t create another dimension with the same path. Instead, you must create a dimension with the path [a, b, c] as it’s a different path.

  • There’s an existing dimension with the API name c_jsuiversion. That dimension has an implicit path equal to [c_jsuiversion]. Therefore, you can’t create a new dimension with a different API name but with the same path ([c_jsuiversion]), as this path is already covered by another dimension.

    This limitation is applied on a per-event basis. If there’s a dimension with a certain path on only the search events, you can create a dimension with the same path on the click events. However, you can’t create a dimension with the same path on all three event types, because the path is already covered on the search events.