Контракты выгрузок Google и Яндекса
Сохранённая таблица не объясняет сама себя. Число 180 может означать показы свойства, сумму показов страниц или результат ручной панели. В этом уроке создадим договоры источников, которые сохранят различие Google, Яндекса и наших наблюдений после передачи файлов другому редактору.
Все выгрузки ProfessorWeb Lab вымышлены. Они имитируют отдельные понятия отчётов, но не копируют закрытую статистику ProfessorWeb.ru. Договор нужен даже для таких учебных файлов: иначе демонстрационный пример начнут читать как реальный отчёт.
Структура договора источника
Откройте source-contracts.json. У каждого набора есть устойчивый dataset_id, тип источника, способ подготовки, период, размерность, единица, область охвата и ограничения полноты. Поле provenance сообщает fictional_manual_fixture. Это центральное свойство наших данных. По форме CSV может напоминать экспорт сервиса, но происхождение остаётся авторским.
Для Google создадим отдельные наборы google_ai_property и google_ai_pages. Первый содержит агрегированные показы свойства, второй — строки по страницам. Не следует складывать второй набор и считать результат тождественным первому: одинаковый сайт может иметь несколько ссылок в одном поисковом результате. Договор заранее фиксирует различие агрегации, чтобы его не пришлось восстанавливать после построения диаграммы.
Генеративный отчёт Google имеет страницы, страны, даты и устройства. Не добавляем в вымышленный экспорт колонку запросов только потому, что она удобна для нашей панели. Панель вопросов находится в другом наборе с собственной методикой. Это важная граница: общий query_id не появляется автоматически у каждой строки чужого агрегированного отчёта.
Для Яндекса разделим учебный ряд SoV и примеры запросов. Ряд описывает показатель, а пример показывает отдельный случай. В справке примеры представлены в случайном порядке и не образуют полный список всех ответов. Поэтому договор запрещает вычислять официальный SoV по числу видимых примеров. Для нашего отдельного арифметического упражнения есть вымышленные счётчики знаменателя, которые прямо так и названы.
В договоре даты Google связаны с Pacific Time, если речь идёт о соответствующем отчёте. Не заменяем их автоматически календарными датами нашего офиса. Для агрегированной строки без времени невозможно восстановить точный UTC-интервал каждого события. При сопоставлении со своей аналитикой придётся либо сохранить разные зоны, либо подготовить совместимую агрегацию из исходных событий.
Ноль, неизвестное и неполная выборка
Экспорт может превратить недоступное значение интерфейса в ноль. В таком случае сам CSV уже не сохраняет достаточный смысл. Наш договор добавляет availability и ссылку на заметку о состоянии интерфейса. Если дополнительного свидетельства нет, строка помечается как ambiguous_export_zero, а не используется как доказанный ноль.
Представим, что таблица ограничена тысячей строк. У каждой видимой строки может быть корректное число, но отсутствие URL не доказывает отсутствие показов этой страницы. Сохраняем row_limit и coverage_statement. Для полного итога используем соответствующий итог источника, а список страниц анализируем как доступную часть. Нельзя чинить неполноту созданием нулей для всех отсутствующих URL.
Теперь добавим второй период. Договор сравнения должен совпадать по источнику, размерности, фильтрам и единице. Отличие окна допустимо, если оно объяснено; иначе динамика может оказаться последствием разных стран или типов поиска. В учебном наборе оба окна содержат двадцать восемь дней и явно записанные фильтры. Это не устраняет сезонность, но устраняет часть очевидных технических различий.
Результат урока — четыре отдельных договора плюс соглашение о недоступных данных. На их основании другой человек сможет открыть CSV и понять, что разрешено считать. Следующий урок применит договор Google к разнице между итогом свойства и суммой строк страниц.
Отдельно фиксируйте состояние периода: завершённый, предварительный или частичный. Новейшие числа могут изменяться после обработки. Если один период окончательный, а другой ещё собирается, в записке нужна соответствующая оговорка. Не помогает молчаливое округление: оно скрывает неопределённость, но не устраняет её.
Проверку договора удобно начинать с вопроса «что произойдёт, если файла станет вдвое больше?». Для независимых событий сумма может иметь смысл, для пересекающихся срезов она создаст двойной счёт. В нашей лаборатории файлы страниц, устройств и стран являются разными представлениями, а не частями одного списка. Их нельзя конкатенировать и получить общий охват.
Перед объединением новых файлов спросите, можно ли указать единственный источник строки. Если после преобразования он исчезает, нормализация стала слишком разрушительной. У итогового числа должна оставаться связь с набором, окном и договором. Это особенно важно для общей таблицы нескольких сервисов: одинаковый столбец percent может скрывать разные знаменатели. Сохраняйте исходные числители там, где они действительно предоставлены, и оставляйте сервисную долю как самостоятельную величину там, где их нет. Такой слой происхождения позволяет пересматривать расчёт, не переписывая всю историю библиотеки.
Чтение сохранённого состояния
Сопоставьте договор с файлами, не начиная с чисел. Набор страниц и набор свойства похожи по названию метрики, но имеют разные агрегации. Набор примеров Яндекса и ряд SoV различаются уже по типу единицы. Именно эти различия должны пережить экспорт в общую электронную таблицу.
| Пара наборов | Правило чтения |
|---|---|
| Google property и pages | Показы относятся к разным агрегациям, поэтому сумма страниц не заменяет итог свойства. |
| Яндекс SoV и examples | Процент и выборка примеров не создают общий знаменатель; примеры нужны для содержательного разбора. |
| Панель и сервисный ряд | Редакторская выборка вопросов остаётся самостоятельной методикой даже при совпадении полученных процентов. |
| Ноль и availability | Цифра читается вместе с доступностью, иначе экспортная потеря смысла выглядит реальным отсутствием события. |
Откройте договор вне папки лаборатории. В нём должны быть названия файлов и происхождение, позволяющие понять назначение без этой статьи. Но для пересчёта всё равно понадобятся сами исходники. Договор не должен содержать готовые выводы вместо данных: его задача определить допустимые операции.
Для реального экспорта создаётся новая версия, где отражены фактически доступные поля и ограничения. Не приспосабливайте рабочую таблицу под наш вымышленный набор молчаливым удалением неудобных строк. Если поля отличаются, их смысл сначала фиксируется. После этого можно строить сопоставимый нормализованный слой и объяснять, какие сведения у источника отсутствуют.
Основной артефакт source-contracts.json находится в lesson-08 архива серии. Полный снимок содержит также исходные таблицы и договоры. Они читаются вручную; результаты примеров описаны как ожидаемые, выполнение не проводилось.