---
title: Semi-structured dimensions
slug: l8vd0068
canonical_url: https://docs.coveo.com/en/l8vd0068/
collection: coveo-analytics
source_format: adoc
---
# Semi-structured dimensions
[dimensions](https://docs.coveo.com/en/258/) are an essential feature in [Coveo Analytics](https://docs.coveo.com/en/182/) for building comprehensive [reports](https://docs.coveo.com/en/266/) and for inspecting user [visits](https://docs.coveo.com/en/271/) in the [Coveo Administration Console](https://docs.coveo.com/en/183/).

Semi-structured dimensions are similar to [regular custom dimensions](https://docs.coveo.com/en/1904#user-defined-dimensions), except they offer further precision by allowing you to select any data element in the JSON configuration.

**Example**

```json
{
    "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](https://docs.coveo.com/en/o3r90189/), 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](https://docs.coveo.com/en/ncd90215/).

## 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

. On the [**Visit Browser**](https://platform.cloud.coveo.com/admin/#/orgid/usage/visit/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/usage/visit/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/usage/visit/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/usage/visit/)) page, [add a custom event filter](https://docs.coveo.com/en/1964#add-visit-filters).

. [Modify the date interval](https://docs.coveo.com/en/1964#review-search-usage-data-by-date-interval) as needed, and then click ![Export icon | Coveo](coveo-analytics/export.png).

. On the **Data Exports** tab of the [**Raw Data**](https://platform.cloud.coveo.com/admin/#/orgid/usage/raw-data/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/usage/raw-data/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/usage/raw-data/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/usage/raw-data/)) page, [export the visit data that meet your criteria](https://docs.coveo.com/en/1964#export-visit-data-that-meet-your-criteria).

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

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

. 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](https://docs.coveo.com/en/1522#add-dimensions-on-custom-metadata).

For a detailed example of using semi-structured dimensions wherein the path is extracted through the **Visit Browser** export, see [Generate Case Assist reports](https://docs.coveo.com/en/l45l0380/).

### Retrieve custom data through the reader account

. On the **Snowflake Reader Account** tab of the [**Raw Data**](https://platform.cloud.coveo.com/admin/#/orgid/usage/raw-data/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/usage/raw-data/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/usage/raw-data/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/usage/raw-data/)) page, [access your Snowflake reader account](https://docs.coveo.com/en/l4gb2122#access-the-reader-account).

. Sign in to Snowflake.

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

. 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**.

. 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](https://docs.coveo.com/en/1522#add-dimensions-on-custom-metadata).

## Add semi-structured dimensions

You can add semi-structured dimensions in the **Add a dimension** panel by selecting the **Semi-structured dimension** checkbox and then adding the desired path (see [Add Dimensions on Custom Metadata](https://docs.coveo.com/en/1522#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 Analytics 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](https://docs.coveo.com/en/260/), 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.