# Экспорт сырых данных CSV

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

Отчеты из raw data

/data_import/reproduce_reports_from_raw_data/

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

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

https://s3.gravityfield.ai/

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

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

MinIO Client: min.io/download
MinIO API и SDK: MinIO SDK documentation

Время подготовки

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

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

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

/<section_id>/batch_data/

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

/<section_id>/daily_data/

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

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

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

Разовые выгрузки

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

# Формат CSV

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

Импорт 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.

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

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

Что не экспортируется

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