> 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/collaboration/prepare-your-environment/share-your-datasets.md).
# Share your datasets
What a dataset is, how to create one in your Bunker, and how to share it into a Clean Room.
## Your goal
Bring a piece of your own data into the platform, and make it available to a partner inside a Clean Room, without handing over the underlying raw records.
## What a dataset is
A **dataset** represents a structured collection of records that can be imported into the platform, shared in a Clean Room, and used as input for dataset matching and analysis. Every dataset is stored in your [Bunker](/collaboration/plan-and-integrate/setup-clean-rooms/bunkers.md).
Each dataset is defined by two characteristics:
* **Type** - the nature of the records it holds.
* **Source** - where the records originate from.
### Dataset types
| Type | Description | Typical use case | Availability |
| ------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- | ------------ |
| **Segment** | A single audience segment that contains unique identifiers such as email addresses | Standard activation and audience matching | Self-service |
| **Segment catalog** | A collection of audience segments | Bulk 1-to-N overlap analysis | Self-service |
| **User profile** | Enriched user-level attributes | Deep-dive analytics on overlapping audiences | Self-service |
| **Campaign log** | Raw advertising exposure events | Attribution and frequency analysis | On request |
| **Transaction log** | Purchase and sales events | ROI and conversion analysis | On request |
### Dataset sources
| Source | Description | Availability |
| ------------------ | -------------------------------------------------------------- | ------------ |
| **Datamart** | Records are imported from your mediarithmics environment (CDP) | Self-service |
| **File** | Records are imported from a file upload | Self-service |
| **Data warehouse** | Records are imported from an external data warehouse | Provisioned |
{% hint style="info" %}
**Self-service** - you create, manage, and use the dataset independently. **Provisioned** - mediarithmics creates it for you; once available, you use it independently. **On request** - not yet natively supported in self-service; mediarithmics can support the use case through a managed implementation. Contact your Account manager.
{% endhint %}
Not every type/source combination is available yet - Segment and Segment catalog are self-service from a datamart, while User profile is self-service from a file only; Campaign log and Transaction log are on request from any source.
## Matching keys
A **matching key** is a user identifier that can be used to match your dataset with your partner's. Supported identifiers today:
* Email (plain text or hashed)
* Mobile Advertising ID (AAID & IDFA)
* Network ID (First-ID, ID5, UTIQ)
* TV Advertising ID (Tizen, IDFA, Roku, AAID, Fire TV)
* Cookie mediarithmics
{% hint style="info" %}
Agree with your partner on the hash method used for Email if you intend to use it as a matching key.
{% endhint %}
How recent an online identifier must be to be matched is set by the **identifier freshness** of each matching - see [Analyze cross-partner behavior](/collaboration/collaborate-with-a-partner/analyze-cross-partner-behavior.md#datasets-matching) - and, for auto-matching, by your [Clean Room Template](/collaboration/prepare-your-environment/manage-your-clean-room-templates.md#what-a-clean-room-template-declares).
## Create a dataset
{% tabs %}
{% tab title="From an existing audience segment" %}
Only available if you use the CDP module.
1. Head to the **Datasets** feature
2. Click **Add Datasets**
3. Hover the dataset type to create and select **From your datamart**
4. Search for one or multiple segments by typing their first letters
5. Click **Validate source(s)**
6. Update the default dataset name and expiration date if needed
7. Click **Create dataset**
{% hint style="info" %}
If the segment was calculated the previous day, the dataset is available within a minute. If the segment was created today, the dataset becomes available after the segment is calculated - usually by the next day.
{% endhint %}
A dataset created this way is automatically refreshed at regular intervals (usually every night).
{% endtab %}
{% tab title="From a file (Navigator)" %}
Best for a one-time or occasional import, or for a partner without access to the Core CDP module.
1. Head to the **Datasets** feature
2. Click **Add Datasets**
3. Hover the dataset type to create and select **From a file**
4. Drag and drop a CSV file to preview its content
5. For each property: select whether it is a matching key, pick its type (used to generate standard dashboards), and update the default dataset name and expiration date if needed
6. Click **Create dataset**
To update, click **Import a new file** with a CSV in the same format (same attributes), choosing **Full update** (replaces all previously imported data) or **Incremental update** (adds to existing data).
{% endtab %}
{% tab title="File hosted on cloud (managed version only)" %}
Automatically imports a file from your preferred cloud storage - useful for datasets with periodic updates. Contact your Account manager to check whether your provider is supported. Once set up, an update runs automatically according to the refresh schedule you configured.
{% endtab %}
{% endtabs %}
### File requirements
| Item | Restriction / limit |
| ------------------------------- | ------------------------- |
| Format | CSV, comma delimiter only |
| Encoding | UTF-8 |
| Minimum number of records | 10 |
| Maximum file size (file import) | 500 MB |
Enclose text values in quotation marks (`"`) so that a value containing a comma is not read as two properties: the comma is the delimiter. Write dates in `YYYY-MM-DD` format.
{% hint style="warning" %}
Header property names may only contain letters, numbers, or underscores; must start with a letter or underscore; and are capped at 50 characters. `_TABLE_`, `_FILE_`, `_PARTITION`, `_ROW_TIMESTAMP`, `__ROOT__`, and `_COLIDENTIFIER` cannot be used. Duplicate property labels are rejected even if the case differs, and no spaces are allowed in a header name.
{% endhint %}
To import a file larger than 500 MB, split it into several files smaller than 500 MB with the same columns and headers, import the first with **Full update**, then import the rest with **Incremental update** in sequence.
## Share a dataset into a Clean Room
{% tabs %}
{% tab title="From the Dataset dashboard" %}
1. Head to the dataset you wish to share
2. Click the hamburger menu (⁝) on the top right and select **Share dataset**
3. Select the Clean Room in which to share it
4. Select the purposes (**Activation** and/or **Insights**) and edit the expiration date if needed
5. Click **Share**
{% endtab %}
{% tab title="From a Clean Room" %}
1. Head to the Clean Room
2. Click **Share datasets**
3. Select the dataset(s) to share
4. Select the purposes (**Activation** and/or **Insights**) and edit the expiration date if needed
5. Click **Share**
{% endtab %}
{% endtabs %}
{% hint style="success" %}
You can also share a Segment directly into a Clean Room - this automatically creates a dataset in your Bunker and shares it.
{% endhint %}
Only dataset metadata (name and size) is shared with your partner at this point; sharing does not expose the underlying records. To edit the sharing purposes or stop sharing, go to the dataset's **Usage** tab, or to the Clean Room, and use the same caret menu to **Edit purposes** or **Stop sharing**.
## Manage and monitor a dataset
Click a dataset's name on the Datasets listing to see:
* **Metadata** - name, creation date, creator, expiration date, number of records or users, number of Clean Rooms it is shared in, and last updated date.
* **Overview** - every property in the dataset, its definition (matching key, type), a sample (except for identifiers), and its fill rate.
* **Usage** - where it is shared, for what purposes, and whether it is being matched with a partner's dataset.
* **Update history** - visibility into updates that occurred on the dataset.
### Dataset and update status
| Dataset status | Meaning |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Synchronization pending | Available within an hour of creation if the underlying segment was already calculated; otherwise typically by 9:00 AM CET the day after the segment is computed |
| Update in progress | An update is running and will be active shortly |
| Active | The last update completed successfully; the dataset can be shared |
| Active (last update in error) | The dataset can still be shared and used for matching, using the last successful update |
| Error | No active update exists; the dataset cannot be used |
| Update status | Meaning |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| In progress | An update is running |
| Completed | The update finished - records with a malformed attribute or a missing matching key may not have been preserved |
| Error | The update failed; check the information tooltip for the cause |
## Troubleshooting
**Why is my dataset not created?** A formatting error can get your file misread or rejected. Check that:
* every column has a header in the first row, following the header rules in [File requirements](#file-requirements);
* commas are used consistently as the delimiter;
* every row has the same number of columns;
* commas and quotes inside text values are handled, for example by enclosing the value in quotation marks;
* values have no leading or trailing spaces;
* critical columns have no empty values;
* each column keeps a single data type;
* dates use the `YYYY-MM-DD` format.
Here is an example of a correctly formatted CSV file:
```csv
Email_hash,Gender,Birth_date,Birth_year,Postcode,State,City,Country
dc3456efdfe497dfse4564,Female,1971-05-27,1971,78840,TEXAS,Del Rio,USA
aeff45adfef9878gdeae5,Male,1972-01-23,1972,H2H 1V3,QUEBEC,Montreal,CANADA
```
## Boundaries
* A dataset's definition (its properties) cannot be changed once created. Update its content by importing a new file, or create a new dataset if the definition itself changed.
* When a dataset reaches its expiration date, it is automatically archived: you can no longer share it into a Clean Room, but existing matching reports that used it remain accessible.
* By default, only users from your own organisation can access a dataset. Users from other organisations can only view a dataset's metadata, once it is shared into a Clean Room that links your organisation with theirs.
* No individual record can be queried or viewed directly by anyone outside your organisation - see [Security and privacy](/collaboration/plan-and-integrate/setup-clean-rooms/security-and-privacy.md).
## Related pages
---
# 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/collaboration/prepare-your-environment/share-your-datasets.md?ask=&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.