# Экспорт сырых данных [!badge variant="primary" text="CSV"]

Эта статья описывает CSV-файлы с сырыми событиями Gravity Field: где они лежат, какие поля есть в выгрузке и какие технические ограничения важно учитывать перед импортом в BI.

[!ref](./reproduce_reports_from_raw_data.md)

## Как получить выгрузку

Сырые данные доступны в S3-совместимом хранилище:

`https://s3.gravityfield.ai/`

Данные для авторизации можно получить у команды, сопровождающей ваш проект, или через поддержку Gravity Field.

Для доступа можно использовать:

- MinIO Client: [min.io/download](https://min.io/download)
- MinIO API и SDK: [MinIO SDK documentation](https://min.io/docs/minio/linux/developers/minio-drivers.html)

!!!info Время подготовки
Пакетная выгрузка может занимать до нескольких часов, если период содержит большой объем событий.
!!!

## Структура папок

Разовые выгрузки по запросу попадают в:

`/<section_id>/batch_data/`

Ежедневные выгрузки по расписанию попадают в:

`/<section_id>/daily_data/`

`section_id` — идентификатор секции/проекта Gravity Field. В каждой папке создается отдельный CSV-файл на дату, например `2026-05-07.csv`.

### Срок хранения

По текущему генератору ежедневных выгрузок файлы в `daily_data` удаляются, когда они старше 14 дней.

!!!warning Разовые выгрузки
Для `batch_data` срок хранения может зависеть от операционной настройки выгрузки. Если вам нужна гарантия хранения разовой выгрузки дольше стандартного окна, скачайте файл после готовности или уточните срок у поддержки.
!!!

## Формат CSV

Каждая строка файла — одно событие. Файл формируется из событийного хранилища Gravity Field и содержит заголовок с фиксированным порядком колонок.

!!!warning Импорт CSV
CSV использует запятую `,` как разделитель и стандартное CSV-экранирование. Не импортируйте файл простым split по запятой: поля `eventProperties`, `eventCart`, `audiences`, `sku` могут содержать вложенные структуры, массивы и запятые внутри значения.
!!!

## Типы событий

| `type` | Тип события | Что означает |
|---:|---|---|
| `0` | Page View | Просмотр страницы |
| `1` | Event Hit | Клиентское или серверное событие, включая `purchase-v1` |
| `2` | Variation Impression | Показ вариации A/B-теста |
| `3` | Variation Click | Клик по вариации |
| `4` | Widget Impression | Рендер/показ рекомендательного виджета |
| `5` | Product Impression | Показ товара в рекомендательном блоке |
| `6` | Product Click | Клик по товару в рекомендательном блоке |
| `7` | Visible Impression | Видимый показ: элемент попал во viewport пользователя |

## Колонки CSV

| Колонка | Тип/формат | Описание |
|---|---|---|
| `type` | number или название типа | Тип события. См. таблицу выше. В некоторых импортах значение может прийти как строка (`Event Hit`), в других — как числовой ID. |
| `contextType` | string | Тип контекста страницы или запроса, если передается интеграцией. |
| `contextData` | string / JSON | Данные контекста страницы или запроса. |
| `uid` | lowercase hex string | Анонимный пользовательский идентификатор Gravity Field. |
| `sec` | lowercase hex string | ID секции Gravity Field. |
| `moscowTime` | datetime | Время события в зоне `Europe/Moscow`. |
| `sessionId` | string | Идентификатор сессии пользователя. |
| `url` | string | URL, на котором произошло событие. |
| `audiences` | array of lowercase hex strings | Сегменты/аудитории пользователя, если были определены. |
| `browser` | string | Браузер пользователя. |
| `device` | string | Тип устройства, например `mobile` или `desktop`. |
| `os` | string | Операционная система. |
| `cuid` | string | Клиентский пользовательский ID, если передается интеграцией. |
| `hashedEmail` | string | Хеш email, если передается интеграцией. |
| `eventId` | string | ID события. Не используйте его для дедупликации заказов. |
| `eventType` | string | Тип события, например `purchase-v1`. |
| `eventName` | string | Имя события. Для покупок обычно совпадает с `purchase-v1`. |
| `eventProperties` | JSON string | Дополнительные свойства события. |
| `eventValue` | integer minor units | Денежное значение события в minor units. Для рублей это копейки; для отчета делите на `100`. |
| `eventCurrency` | string | Валюта события, например `RUB`. |
| `eventProductId` | string | ID товара для событий, где передается один товар. |
| `uniqueTransactionId` | string | ID заказа/транзакции. Используется для дедупликации покупок. |
| `eventCart` | array of tuples | Корзина покупки. Каждый элемент: `(productId, quantity, itemPriceMinor)`. |
| `campaignId` | lowercase hex string | ID кампании, если событие связано с кампанией. |
| `experienceId` | lowercase hex string | ID сценария/experience. |
| `versionId` | lowercase hex string | ID версии A/B-теста. |
| `variationId` | lowercase hex string | Первый ID вариации из события. Если внутри события было несколько вариаций, экспорт содержит только первый элемент. |
| `campaignName` | string | Название кампании из словаря платформы на момент экспорта. |
| `experienceName` | string | Название experience из словаря платформы на момент экспорта. |
| `versionName` | string | Название версии теста из словаря платформы на момент экспорта. |
| `variationName` | string | Название вариации из словаря платформы на момент экспорта. |
| `control` | boolean | `true`, если вариация является контрольной. |
| `sku` | array | SKU, связанные с событием. Для `Product Click` это кликнутые товары. |
| `strategyId` | lowercase hex string | Первый ID стратегии из события. Если событие содержит несколько стратегий, экспорт содержит только первый элемент. |
| `strategyName` | string | Название стратегии из словаря платформы на момент экспорта. |

## Денежные значения и корзина

`eventValue` и `itemPrice` внутри `eventCart` хранятся в minor units. Например:

- `eventValue = 78900` означает `789.00` в валюте `eventCurrency`
- `eventCart = [('sku-1', 2, 19900)]` означает 2 единицы товара `sku-1` по `199.00`
- сумма строки корзины для отчетов: `quantity * itemPriceMinor / 100`

Для события `purchase-v1`:

- `eventValue` — сумма заказа, которую передала интеграция
- `eventCart` — товары заказа
- `uniqueTransactionId` — ключ для дедупликации повторно отправленных покупок

Gravity Field не пересчитывает gross/net, НДС, скидки или возвраты из каталога. В отчетах используется значение, которое было отправлено в событии покупки.

## Как связывать события

Для пользовательского пути используйте:

- `uid` — основной ключ пользователя
- `sessionId` — ключ сессии
- `moscowTime` — порядок событий в raw export
- `uniqueTransactionId` — дедупликация заказов

Для A/B-тестов обычно связывают `Variation Impression` с последующими `Event Hit` по `uid` или `sessionId` в зависимости от настроек теста.

Для рекомендаций обычно связывают `Product Click` с последующим `purchase-v1` по `uid`, времени, окну атрибуции и совпадению кликнутого `sku` с товаром в `eventCart`.

Подробные рецепты и ограничения описаны в статье [Как воспроизвести отчеты из raw data](./reproduce_reports_from_raw_data.md).

## Ограничения текущего raw export

Некоторые внутренние поля платформы не попадают в CSV. Поэтому часть метрик можно воспроизвести только приблизительно или нельзя воспроизвести из raw export без дополнительной выгрузки.

!!!warning Что не экспортируется
В CSV нет:

- `exps` — внутренний массив привязки purchase-события к A/B-эксперименту
- `groupId` и `eventCartGroupId` — нужны для точного `Direct Revenue (All Variants)`
- `slots`, `fallback`, `empty slots` — нужны для точного расчета fallback/empty response метрик
- UTC `timestamp` — экспортируется только `moscowTime`
- `sourceId`, referrer и UTM-поля
!!!

Также важно учитывать:

- `variationId` и `strategyId` в raw export содержат только первый элемент массива из события
- пустые значения и `000000000000000000000000` означают, что поле не применимо к событию
- события могут приходить с задержкой, поэтому выгрузки, сделанные в разное время, могут немного отличаться на границах периода

## Рекомендации по импорту

- Используйте CSV-парсер с поддержкой кавычек и вложенных значений.
- Не меняйте разделитель вручную перед импортом, если BI умеет читать стандартный CSV.
- Приводите `moscowTime` к типу datetime сразу на staging-слое.
- Нормализуйте `eventCart` в отдельную таблицу строк заказа: `eventId`, `uniqueTransactionId`, `productId`, `quantity`, `itemPriceMinor`.
- Для денежных метрик создайте отдельные поля `eventValue = eventValueMinor / 100` и `lineRevenue = quantity * itemPriceMinor / 100`.
- Для заказов используйте дедупликацию по `uniqueTransactionId`, а не по `eventId`.