Тема: Часть 8. Источники и Schema Manifest
Уровень сложности: Средний
Расчётное время изучения: 2.5–3 часа
Предварительные требования: Базовое понимание SQL и CSV-файлов
Знакомство с понятиями ETL/ELT и слоистой архитектурой данных
Понимание разницы между raw-слоем и mart-слоем
Начальные знания о dbt и его роли в трансформации данных
Базовое понимание PII (Personally Identifiable Information) и data governance
Цели обучения: Объяснить разницу между режимом наблюдения и режимом проектирования при работе с источниками данных
Составить Schema Manifest минимум для двух источников по заданному шаблону
Идентифицировать кандидатные ключи, кандидаты PII и пустые значения в наборе данных без интерпретации бизнес-смысла
Сформулировать не менее пяти открытых вопросов к владельцу источника для защиты от скрытых догадок
Аргументировать, почему манифест и контракт должны существовать как отдельные документы
Обзор: Профилирование источников — это первый и принципиально важный этап работы агента с сырыми данными. В отличие от этапа проектирования, где агент создаёт модели и контракты, профилирование работает исключительно в режиме наблюдения: агент фиксирует то, что реально пришло в raw-слой, не пытаясь придать этому бизнес-смысл. Главный инструмент этого этапа — Schema Manifest. Это документ, который описывает наблюдаемые поля, их типы, пустые значения, кандидатные ключи, кандидаты PII и подсказки о свежести. Важной частью манифеста является раздел открытых вопросов — он защищает от преждевременной интерпретации. Манифест описывает наблюдаемое, а контракт — обещанное. Если смешать эти слои, агент начнёт «очищать» источник до того, как человек утвердил политику, что приводит к потере важных сигналов о качестве данных и к ошибкам в отчётности. Цель этого раздела — научиться сдержанности при работе с сырыми данными и пониманию, что открытые вопросы — это не слабость, а защита от скрытых догадок.
Ключевые концепции: Профилирование источника: Режим наблюдения за сырыми данными, при котором агент читает заголовки файлов, первые строки и считает простые статистики. Главное правило — не решать бизнес-смысл самостоятельно и не писать dbt-модели на этом этапе.
Schema manifest: Документ, который описывает то, что наблюдается в источнике. Состоит из разделов: наблюдаемые поля, кандидаты ключей, кандидаты PII, заметки о качестве и открытые вопросы. Это протокол осмотра данных, а не проект их трансформации.
Режим наблюдения vs режим проектирования: В режиме наблюдения агент только описывает увиденное. В режиме проектирования — создаёт модели, контракты и принимает архитектурные решения. Смешение этих режимов ведёт к преждевременной оптимизации и потере контекста.
Манифест vs контракт: Манифест фиксирует наблюдаемое (что реально пришло в raw-слой). Контракт фиксирует обещанное (что источник гарантирует и что разрешено использовать в mart). Если в источнике есть поле pii_email, манифест обязан его показать, а контракт может запретить ему попасть в mart.
Кандидат ключа: Поле или комбинация полей, которые по наблюдениям агента выглядят устойчивыми идентификаторами. До утверждения человеком это только кандидат, а не ключ.
Кандидаты pii: Поля, которые по своему имени или содержанию похожи на персональные данные. До утверждения владельцем источника и формальной политики обработки — это только подозрение, а не факт.
Свежесть данных: Подсказки о том, насколько актуальны данные: дата выгрузки, наличие временных меток, частота обновления. Это наблюдаемый признак, а не контрактная гарантия.
Открытые вопросы: Раздел манифеста, куда записываются все неоднозначности и странности источника, которые нельзя решить без владельца. Это защита от того, чтобы догадка не стала фактом.
Сдержанность агента: Принципиальная установка не интерпретировать данные до утверждения человеком. Агент видит risk_flag и не должен сразу придавать ему бизнес-смысл — только зафиксировать существование поля.
Протокол осмотра места происшествия: Метафора качественного манифеста: как криминалист на месте происшествия описывает то, что нашёл, не делая выводов о виновнике, так и агент описывает данные без выводов об их смысле.
Защита raw-слоя: Манифест защищает сырые данные от преждевременной «чистки». Если есть странность, её нужно сначала записать и задать вопрос, а не исправить, потому что пустая дата может означать три разных вещи: ошибку, допустимый способ кодирования или потерю данных.
Наблюдаемый тип: Тип данных, который агент видит в источнике (например, строка, число, дата в виде строки). Не путать с контрактным типом — тем, который обещает источник или требует mart.
Grain источника: Уровень детализации данных (одна строка = одна транзакция, одному клиенту и т. п.). Агент не должен решать grain без утверждения человеком, даже если ему кажется, что ответ очевиден.
Важные даты: Контекст курса: Часть 8 — это этап после получения сырых данных и до проектирования моделей в курсе по data engineering с использованием dbt и LLM-агентов
Порядок работы: Сначала Schema Manifest (наблюдение), затем контракт (проектирование), затем модели (реализация)
Практические упражнения: Название: Составление манифеста для card_transactions
Проблема: Откройте specs/source-manifests/card_transactions.md. Изучите наблюдаемые поля, кандидаты ключей, кандидаты PII, заметки о качестве и открытые вопросы. На основе этого шаблона составьте собственный черновой манифест для вымышленного источника raw/orders.csv со следующими колонками: order_id, customer_id, order_date, total_amount, status, risk_flag, promo_code. Укажите наблюдаемые типы, отметьте пустые значения, предположите кандидат ключа и кандидаты PII, сформулируйте минимум четыре открытых вопроса.
Решение: Шаг 1. Создайте файл specs/source-manifests/orders.md. Шаг 2. Опишите наблюдаемые поля с их типами, например: order_id (int64), customer_id (int64), order_date (string в формате YYYY-MM-DD), total_amount (float64), status (string), risk_flag (bool или string), promo_code (string с большим количеством null). Шаг 3. Кандидат ключа — order_id (похоже на устойчивый идентификатор). Шаг 4. Кандидаты PII — customer_id (синтетический или настоящий?). Шаг 5. Заметки о качестве — promo_code пустой в большинстве строк. Шаг 6. Открытые вопросы: что означает пустой promo_code? Является ли risk_flag флагом источника или результатом антифрод-системы? Что кодирует status — финальное состояние или текущее? Свежесть — есть ли поле loaded_at?
Сложность: intermediate
Название: Анализ открытого вопроса про revoked_at
Проблема: В источнике open_api_consents.csv есть поле revoked_at, которое часто пустое. Сформулируйте, что может сломаться, если агент решит этот вопрос самостоятельно, без обращения к владельцу источника. Опишите три возможных интерпретации пустого значения и последствия каждой.
Решение: Шаг 1. Сформулируйте три гипотезы о пустом revoked_at: (а) согласие активно и никогда не отзывалось, (б) согласие отозвано, но дата не записана из-за бага в источнике, (в) поле используется особым способом кодирования. Шаг 2. Опишите последствия ошибочной интерпретации: если агент решит, что пустое revoked_at = активное согласие, а в реальности это баг, то в mart попадут строки с неактуальными согласиями, что нарушит требования GDPR/152-ФЗ. Шаг 3. Сделайте вывод: открытый вопрос в манифесте должен явно указывать на эту неоднозначность и требовать подтверждения владельца.
Сложность: intermediate
Название: Разделение манифеста и контракта
Проблема: Дан источник, в котором есть поля: pii_email, pii_phone, customer_segment, lifetime_value, registration_date. Составьте два отдельных документа: Schema Manifest (наблюдаемое) и черновик контракта (обещанное). Покажите, что манифест обязан зафиксировать все поля, включая pii_email и pii_phone, тогда как контракт должен явно указать, какие из них разрешены в mart.
Решение: Шаг 1. Schema Manifest включает все поля с типами, помечая pii_email и pii_phone как кандидаты PII. Шаг 2. В разделе открытых вопросов манифеста появляется вопрос: «Есть ли политика маскирования pii_email и pii_phone перед попаданием в mart?». Шаг 3. Контракт содержит явные разрешения и запреты: например, pii_email — запрещено в mart, разрешено только в защищённом слое с маскированием; customer_segment — разрешено в mart; lifetime_value — разрешено в mart. Шаг 4. Сделайте вывод: если бы документ был один, агент мог бы «забыть» про pii_email, или, наоборот, начать агрессивно очищать источник до утверждения политики.
Сложность: intermediate
Название: Поиск скрытых догадок в собственном манифесте
Проблема: Возьмите свой черновой манифест из упражнения 1. Прочитайте его внимательно и найдите минимум три места, где вы, сами того не замечая, придали полю бизнес-смысл до утверждения человеком. Перепишите эти места в нейтральной форме наблюдения.
Решение: Шаг 1. Типичная скрытая догадка — назвать status «статусом заказа» вместо «полем status». Шаг 2. Вторая догадка — решить, что risk_flag «означает высокий риск», хотя это только название поля. Шаг 3. Третья — написать «customer_id — это клиент», хотя customer_id может быть идентификатором сессии, устройства или учётной записи. Шаг 4. Перепишите в нейтральной форме: «поле status принимает значения из множества {new, paid, cancelled, refunded}», «поле risk_flag имеет тип bool, наблюдается в 12% строк», «поле customer_id — числовой идентификатор, смысл не подтверждён». Шаг 5. Добавьте эти неоднозначности в раздел открытых вопросов.
Сложность: intermediate
Название: Составление Qwen-запроса для профилирования
Проблема: Сформулируйте промпт для Qwen (или другого LLM-агента), который корректно ставит задачу профилирования нового источника raw/loan_applications.csv. Промпт должен явно запрещать агенту писать dbt-модели и решать grain без утверждения.
Решение: Шаг 1. Начните с явной постановки задачи: «Прочитай заголовки raw/loan_applications.csv и первые 100 строк». Шаг 2. Перечислите, что нужно сделать: «Составь Schema Manifest: поля, наблюдаемые типы, кандидатные ключи, кандидаты PII, подсказки свежести и открытые вопросы». Шаг 3. Явно запретите лишние действия: «Не пиши dbt-модели. Не решай grain без утверждения. Не заменяй пустые значения. Не интерпретируй бизнес-смысл полей». Шаг 4. Укажите формат выхода: «Результат — markdown-документ с разделами: наблюдаемые поля, кандидаты ключей, кандидаты PII, заметки о качестве, открытые вопросы». Шаг 5. Проверьте, что промпт не содержит фраз, провоцирующих интерпретацию, например «опиши, как эти данные используются в бизнесе».
Сложность: advanced
Кейсы: Название: Кейс: GDPR-аудит и преждевременная очистка поля с согласием
Сценарий: Европейский финтех-стартап готовил mart для маркетинговой аналитики. Агент получил источник с полями customer_id, consent_marketing, consent_at, revoked_at. Команда попросила агента «очистить данные и подготовить витрину активных подписок на рассылку».
Задача: Агент увидел, что revoked_at часто пустой, и решил, что это означает «согласие активно». Без обращения к владельцу данных он построил модель, которая интерпретировала пустое revoked_at как действующее согласие. Через шесть месяцев пришёл GDPR-аудит, и выяснилось, что часть «активных» подписок на самом деле была отозвана, но из-за бага в upstream-системе revoked_at не записывался. Компания получила штраф и обязана была уведомить всех затронутых клиентов.
Решение: Команда переделала процесс: внедрила обязательный шаг Schema Manifest, в котором открытый вопрос «что означает пустое revoked_at?» явно фиксировался. Перед построением mart-агент обязан был получить подтверждение владельца источника. В манифесте явно указывалось, что revoked_at — кандидат на кодирование активного согласия, но не подтверждённый факт.
Результат: После изменения процесса подобные баги стали обнаруживаться до того, как они попадали в отчётность. Юридический отдел получил возможность утверждать интерпретации до релиза. Штрафов больше не было, а процесс онбординга новых источников стал занимать на 2–3 дня больше, но сократил число инцидентов на 80%.
Извлечённые уроки: Преждевременная интерпретация данных в коде приводит к юридическим и репутационным рискам, которые не видны на этапе разработки
Schema Manifest — это не формальность, а юридический артефакт, который защищает команду и показывает, что интерпретация была утверждена человеком
Открытые вопросы — это документированная осторожность, а не слабость работы агента
Разделение манифеста и контракта позволяет избежать ситуации, когда «очищенные» данные скрывают реальные проблемы источника
Связанные концепции: Манифест vs контракт
Открытые вопросы
Сдержанность агента
Кандидаты PII
Защита raw-слоя
Название: Кейс: подозрительное поле risk_flag в антифрод-системе
Сценарий: Команда риск-аналитиков получила выгрузку транзакций с полем risk_flag. Два джуниор-аналитика интерпретировали это поле по-разному: один считал, что это «финальное решение антифрод-системы», другой — что это «входной параметр для правила». Оба начали строить отчёты без уточнения.
Задача: Через три месяца выяснилось, что отчёты аналитиков противоречат друг другу. У одного доля «рискованных» транзакций составляла 4%, у другого — 11%. Причина — разная интерпретация одного и того же поля. Без Schema Manifest оба аналитика не имели документированного основания для своей интерпретации, и владелец источника не мог быстро разрешить спор.
Решение: Команда внедрила практику обязательного Schema Manifest для каждого нового источника. В манифесте для транзакций risk_flag был записан как «поле с типом bool, встречается в 100% строк, кандидат на бизнес-смысл — флаг риска, но точная интерпретация требует подтверждения владельца». Открытый вопрос был задан владельцу источника, и через неделю пришёл ответ: «risk_flag — это результат работы rule engine до применения ML-модели, использовать как самостоятельный признак риска нельзя».
Результат: После внедрения практики споры об интерпретации полей сократились. Время онбординга нового аналитика в команду сократилось с двух недель до трёх дней, потому что Schema Manifest служил «картой» источника. Команда также обнаружила ещё два поля с неоднозначной интерпретацией, которые раньше просто использовали «как есть».
Извлечённые уроки: Имя поля не определяет его смысл — даже очевидные названия вроде risk_flag могут иметь разные интерпретации
Schema Manifest фиксирует неоднозначности и делает их видимыми для всех участников команды
Открытый вопрос без ответа — лучше, чем догадка, ставшая фактом
Документирование сырых данных — это инвестиция, которая окупается при любом споре об интерпретации
Связанные концепции: Сдержанность агента
Открытые вопросы
Протокол осмотра места происшествия
Наблюдаемый тип
Название: Кейс: миграция источника и спасённые вопросы из манифеста
Сценарий: Крупный ритейлер мигрировал систему лояльности с одной CRM на другую. Источник customer_profiles.csv имел 47 полей, многие из которых были непонятны новой команде. Предыдущая команда оставила Schema Manifest с 23 открытыми вопросами.
Задача: Новая команда могла бы проигнорировать эти вопросы и начать строить mart «как получится». Но они увидели, что многие из открытых вопросов касались критичных полей: is_vip, churn_score, lifetime_segment. Без ответов они не могли гарантировать, что отчётность будет совпадать со старой.
Решение: Новая команда обратилась к владельцам источника по каждому из 23 открытых вопросов. 14 ответов оказались критичными для отчётности. Например, выяснилось, что churn_score рассчитывался по устаревшей формуле и использование его в mart без корректировки привело бы к расхождению с историческими дашбордами на 18%.
Результат: Schema Manifest с открытыми вопросами сэкономил команде минимум 2 месяца разбирательств и предотвратил публикацию неверной отчётности. После миграции команда сделала практику обязательной: каждый источник обязан иметь актуальный Schema Manifest с разделом открытых вопросов, даже если на момент создания манифеста «всё понятно».
Извлечённые уроки: Открытые вопросы имеют долгосрочную ценность — они помогают не только текущей команде, но и тем, кто придёт после
Schema Manifest — это артефакт для передачи знаний между командами
Даже если кажется, что «всё очевидно», документирование неоднозначностей страхует от ошибок в будущем
Миграции и изменения в источниках — момент, когда Schema Manifest особенно ценен
Связанные концепции: Открытые вопросы
Защита raw-слоя
Манифест vs контракт
Профилирование источника
Советы по изучению: Практикуйте сдержанность: каждый раз, когда хочется написать «это поле означает X», переформулируйте в «это поле называется X, его смысл требует подтверждения».
Ведите личный список «опасных догадок» — полей, в которых вы уверены, но уверенность не подтверждена владельцем источника.
Открытые вопросы формулируйте как вопросы к владельцу, а не как риторические или самоочевидные утверждения. Например, не «вероятно, активное согласие», а «пустое revoked_at: что оно означает — активное согласие, баг источника или особое кодирование?».
Не пытайтесь сразу написать dbt-модель после манифеста. Сначала покажите манифест человеку и получите подтверждение интерпретаций.
Перечитывайте свой манифест через день — часто обнаруживаются скрытые интерпретации, которые не видны сразу.
Используйте единый шаблон манифеста для всех источников — это упрощает ревью и сравнение источников между собой.
Если поле выглядит «слишком очевидным» (например, customer_id), это не повод пропускать его в манифесте. Очевидность — ловушка.
Разделяйте наблюдаемое (manifest) и обещанное (contract) физически — в разных файлах, с разными владельцами и разным ритмом обновления.
При ревью чужого манифеста обращайте внимание на отсутствующие открытые вопросы. Если их нет — это повод задать вопросы самому.
Помните, что манифест читают не только инженеры, но и аналитики, юристы и менеджеры. Пишите так, чтобы документ был понятен без глубокого технического контекста.
Дополнительные ресурсы: Specs/source-manifests/card transactions.md: Образец манифеста для источника транзакций, доступный в репозитории курса
Specs/source-manifests/open api consents.md: Образец манифеста для источника согласий с примером открытых вопросов
Dbt documentation: sources: https://docs.getdbt.com/docs/build/sources — официальная документация по sources в dbt, которая логически связана с идеей манифеста
Dbt-utils: source freshness checks: https://github.com/dbt-labs/dbt-utils — инструменты для проверки свежести источников
Gdpr официальный текст: https://gdpr-info.eu — регуляция, которая объясняет, почему PII и согласия требуют особого внимания в манифесте
Data quality fundamentals (o'reilly): Книга, раскрывающая принципы профилирования данных и работы с качеством
Fundamentals of data engineering (joe reis, matt housley): Книга с подробным описанием слоистой архитектуры и места манифеста в ней
Курс по data observability (monte carlo, bigeye): Серия статей и видео о наблюдаемости данных, которая концептуально близка к идее Schema Manifest
Резюме: Часть 8 курса посвящена Schema Manifest — ключевому документу, который фиксирует наблюдаемое состояние сырых данных. Главный принцип этого этапа — сдержанность: агент описывает то, что видит, и не решает бизнес-смысл до утверждения человеком. Манифест включает наблюдаемые поля, кандидаты ключей, кандидаты PII, заметки о качестве и, что особенно важно, открытые вопросы. Открытые вопросы — это не слабость, а защита от скрытых догадок: пустое поле может означать три разные вещи, и только владелец источника может подтвердить правильную интерпретацию. Манифест принципиально отделён от контракта: манифест описывает наблюдаемое, контракт — обещанное. Смешение этих слоёв приводит к преждевременной очистке источника и потере сигналов о качестве данных. В результате изучения этой части вы научитесь составлять Schema Manifest для реальных источников, формулировать открытые вопросы, отделять наблюдение от интерпретации и обосновывать архитектурное разделение манифеста и контракта.