> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema.md).

# Design your data model & schema

Decide what the platform indexes and makes queryable, and declare it in your datamart's schema.

## Your goal

Decide which of your data must be queryable, and declare it - because in mediarithmics, what you can segment on is determined by your schema, not by what you happen to send.

## Expected outcome

A published schema that indexes exactly the properties your use cases need, and a data model your teams can read: identifiers on one side, describing content on the other.

## The one thing to understand first

{% hint style="warning" %}
**All data you collect is stored, whether or not it appears in the schema.** But if the schema is not set up properly, your data is not correctly indexed and you will not be able to query it the way you want. Indexed fields can be used in queries and to build segments; non-indexed fields cannot.
{% endhint %}

This is why data-model design comes before collection: sending data is cheap and reversible, deciding what is queryable is neither.

## The shape of a mediarithmics data model

Everything hangs off the [UserPoint](/setup-and-monitor/understand-mediarithmics/how-mediarithmics-works.md#how-your-data-is-modelled-the-userpoint), and divides into two families of nodes.

```mermaid
flowchart LR
    UP(("UserPoint"))
    subgraph ident["Identifies the user"]
        ACC["UserAccount"]
        EM["UserEmail"]
        DEV["UserDevicePoint<br/>UserDeviceTechnicalId"]
    end
    subgraph content["Describes the user"]
        ACT["UserActivity<br/>UserEvent"]
        PROF["UserProfile"]
        SEG["UserSegment"]
        CHO["UserChoice"]
        COMP["Computed fields<br/>UserScore"]
    end
    ACC --- UP
    EM --- UP
    DEV --- UP
    UP --- ACT
    UP --- PROF
    UP --- SEG
    UP --- CHO
    UP --- COMP
```

* **Identifiers** decide *who* the data belongs to, and therefore when two UserPoints become one. See [User identity](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity.md).
* **Describing content** is what you query and segment on. Its structure is what the schema declares.

## Work through it in this order

{% stepper %}
{% step %}

### List the questions your use cases ask

"Users who bought category X in the last 30 days", "users who abandoned a basket over €100", "users reachable by email in region Y". Each question tells you which property has to be indexed, and on which object.
{% endstep %}

{% step %}

### Decide your identity model

Which identifiers you will collect, and which of them are strong enough to merge two UserPoints. This is the decision with the longest-lasting consequences.

[User identity](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity.md)
{% endstep %}

{% step %}

### Write the schema

Declare the objects and properties, and index only what you will query on.

[Schema definition](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/schema-definition.md)
{% endstep %}

{% step %}

### Map your warehouse tables, if that is where your data lives

Where the datamart reads from a cloud data warehouse, each object of the model names a table there. Choosing which tables to expose is the same decision as choosing what to index.

[Map your warehouse tables to a schema](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/map-your-warehouse-tables-to-a-schema.md)
{% endstep %}

{% step %}

### Use the standard events where you can

Predefined event names and properties unlock built-in analytics, dashboards, and funnels. Custom events do not.

[Standard events](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/standard-events.md)
{% endstep %}

{% step %}

### Add computed data where a query cannot do the job

Aggregates and scores that would be expensive or impossible to express as a query.

[Computed fields](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/computed-fields.md)
{% endstep %}

{% step %}

### Write it down as a plan, and keep it honest

A tracking and data plan is what keeps the schema, the collection, and the use cases aligned over time.

[Data planning and quality](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/data-planning-and-quality.md)
{% endstep %}
{% endstepper %}

## In this section

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Schema definition</strong></td><td>The language, the directives, and the publication workflow.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/schema-definition.md">Schema definition</a></td></tr><tr><td><strong>Map your warehouse tables to a schema</strong></td><td>Exposing warehouse tables as objects of your model.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/map-your-warehouse-tables-to-a-schema.md">Map your warehouse tables to a schema</a></td></tr><tr><td><strong>Standard events</strong></td><td>The predefined events that power built-in analytics.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/standard-events.md">Standard events</a></td></tr><tr><td><strong>Computed fields</strong></td><td>Fields calculated on a schedule rather than collected.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/computed-fields.md">Computed fields</a></td></tr><tr><td><strong>Data planning and quality</strong></td><td>Keeping the model and the reality in step.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/data-planning-and-quality.md">Data planning and quality</a></td></tr><tr><td><strong>User identity</strong></td><td>Identifiers, the identity graph, and resolution.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity.md">User identity</a></td></tr></tbody></table>

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Set up the environment</strong></td><td>Channels, compartments, and registries the model references.</td><td><a href="/setup-and-monitor/plan-and-integrate/set-up-the-environment.md">Set up the environment</a></td></tr><tr><td><strong>Collect data in real time</strong></td><td>Send the data the model describes.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md">Collect data in real time</a></td></tr><tr><td><strong>Query your datamart</strong></td><td>Test that what you declared is actually queryable.</td><td><a href="/setup-and-monitor/operate-and-monitor/query-your-datamart.md">Query your datamart</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.