Пояснения к потокам NiFi

MENTEE_GUIDE_JSON_FLOWS.md

@@ -0,0 +1,110 @@
+# Гайд для менти: как работают примеры flow на JSON (NiFi → Kafka → Postgres)
+
+Этот гайд про два flow definition файла:
+- `nifi-templates/Sample2Kafka.json` — генерирует записи и публикует их в Kafka topic `Sample2Kafka` в виде JSON.
+- `nifi-templates/SampleKafka2Postgres.json` — читает JSON из Kafka topic `Sample2Kafka` и пишет данные в Postgres.
+
+## 0) Что мы строим (общая картинка)
+Цепочка очень простая:
+1) NiFi генерирует запись (как “строчку данных”).
+2) NiFi отправляет эту запись в Kafka (как сообщение в topic).
+3) Другой flow в NiFi читает эти сообщения из Kafka.
+4) NiFi фильтрует/готовит данные и вставляет их в Postgres.
+
+Это учебный пример, который показывает базовые роли технологий:
+- **NiFi** — визуальный конвейер (pipeline) данных.
+- **Kafka** — “почтовый ящик”/шина сообщений между системами.
+- **Postgres** — база данных, где данные хранятся и доступны SQL-запросами.
+
+## 1) Мини-словарь NiFi (3 понятия)
+- **FlowFile** — “сообщение”, которое течёт по графу. У FlowFile есть *content* (тело) и *attributes* (метаданные).
+- **Processor** — шаг обработки (прочитать/преобразовать/записать).
+- **Controller Service** — общая настройка, которую используют процессоры (например, “как читать JSON” или “как подключаться к базе”).
+
+## 2) Какой JSON у нас в примере
+Запись состоит из двух полей:
+- `dttm` — дата/время (timestamp).
+- `txt` — строка (text).
+
+В первом flow запись создаётся процессором `GenerateRecord` по схеме (она задана в настройке процессора).
+
+Важно: в этом учебном варианте **мы не используем Avro** и не используем Schema Registry. Сообщения в Kafka — это обычный JSON.
+
+## 3) Перед стартом: что проверить
+1) Стенд поднят: `docker compose up -d`
+2) Открывается NiFi: http://localhost:18443/nifi/ (логин `admin`, пароль `Password123456`)
+3) Открывается Kafka UI: http://localhost:8082/
+4) (Если это первый запуск после `docker compose down -v`) примените SQL-скрипт для демо-таблиц:
+   - `docker compose exec -T postgres psql -U postgres -d app -f /nifi-templates/SampleKafka2Postgres.sql`
+
+## 4) Flow 1 — `Sample2Kafka.json` (NiFi → Kafka)
+Цель: регулярно публиковать новые JSON-сообщения в Kafka topic `Sample2Kafka`.
+
+### Шаги внутри flow
+1) `GenerateRecord`
+   - Создаёт запись по схеме (в настройке `schema-text`).
+   - Частота генерации задаётся расписанием процессора (например, раз в 2 секунды).
+2) `PublishKafkaRecord_2_6`
+   - Берёт записи и публикует в Kafka.
+   - Важные настройки:
+     - `bootstrap.servers`: `kafka:29092` (имя сервиса внутри Docker).
+     - `topic`: `Sample2Kafka`
+     - `record-reader`: `JsonTreeReader` (как “прочитать запись” перед отправкой)
+     - `record-writer`: `JsonRecordSetWriter` (как сериализовать в JSON)
+
+### Как проверить, что flow работает
+- В NiFi у `PublishKafkaRecord_2_6` растёт счётчик “out”.
+- В Kafka UI в topic `Sample2Kafka` появляются сообщения.
+
+Если сообщений нет:
+- Проверьте, что процессоры запущены и нет очереди/ошибок на `failure`.
+- Проверьте, что внутри NiFi указано `kafka:29092`, а не `localhost:9092`.
+
+## 5) Flow 2 — `SampleKafka2Postgres.json` (Kafka → Postgres)
+Цель: читать сообщения из `Sample2Kafka`, отфильтровать записи и записать их в Postgres.
+
+### Шаги внутри flow
+1) `ConsumeKafkaRecord_2_6`
+   - Читает сообщения из Kafka topic `Sample2Kafka`.
+   - Важные настройки:
+     - `bootstrap.servers`: `kafka:29092`
+     - `topic`: `Sample2Kafka`
+     - `record-reader`: `JsonTreeReader` (как разобрать JSON из Kafka)
+2) `QueryRecord`
+   - Выполняет простой “фильтр” по данным.
+   - В примере есть запрос `GOOD_DATE` (это имя relationship), который отбирает записи по условию на `dttm`.
+   - На выходе получаются записи, которые прошли фильтр.
+3) `MergeContent` (micro-batch)
+   - Собирает несколько FlowFile в “пачку” перед загрузкой в БД.
+   - Зачем: много маленьких вставок (каждое сообщение → отдельный insert) может перегружать БД; batching снижает накладные расходы.
+   - Важные настройки:
+     - `Minimum Number of Entries` / `Maximum Number of Entries` — размер пачки (сколько записей объединяем).
+     - `Max Bin Age` — максимальное ожидание, чтобы пачка всё равно отправилась даже если данных мало.
+   - Компромисс: чем больше batch, тем меньше нагрузка на БД, но больше задержка (latency).
+4) `PutDatabaseRecord`
+   - Вставляет записи в таблицу `stg.samplekafka2postgres`.
+   - Использует подключение к Postgres через `DBCPConnectionPool`.
+5) `ExecuteSQL`
+   - Вызывает хранимую процедуру `ods.load_samplekafka2postgres()` и чистит staging.
+   - Это шаг “переложить в витрину/ODS”, чтобы показать типичный паттерн.
+
+### Как проверить результат в Postgres
+В контейнере Postgres выполните:
+- `docker compose exec -it postgres bash -c \"export PGPASSWORD=postgres; psql -U postgres -d app\"`
+
+И затем SQL:
+- `select * from ods.samplekafka2postgres order by id desc limit 10;`
+
+Если таблица пустая:
+- Убедитесь, что в Kafka действительно есть сообщения (проверьте Kafka UI).
+- Посмотрите, нет ли ошибок на `parse.failure` (у Kafka consumer) или `failure` (у DB).
+
+## 6) Типовые проблемы (и куда смотреть)
+- **В NiFi указали `localhost` вместо имени сервиса**: из контейнера `localhost` — это сам контейнер, не Kafka/Postgres.
+- **Controller Services выключены**: внутри process group откройте `Controller Services` и включите нужные сервисы.
+- **Нет таблиц/процедуры**: после “чистого сброса” нужно снова выполнить `SampleKafka2Postgres.sql`.
+
+## 7) Мини-упражнения для закрепления (5–10 минут)
+1) В `Sample2Kafka.json` поменяйте расписание `GenerateRecord` (например, 2 sec → 5 sec) и проверьте скорость появления сообщений.
+2) В `QueryRecord` измените фильтр `GOOD_DATE` (например, более жёсткое/мягкое условие) и проверьте, как меняется количество строк в Postgres.
+3) Добавьте новое поле в схему `GenerateRecord` и протащите его до Postgres (после изменения не забудьте обновить SQL-схему/таблицы).

README.md

@@ -97,6 +97,8 @@ select * from ods.samplekafka2postgres order by id desc limit 10;
 - Из NiFi (внутри Docker): `kafka:29092`
 
 ## Примеры flow (шаблоны)
+Короткий гайд для менти по JSON-версии потоков: `MENTEE_GUIDE_JSON_FLOWS.md`.
+
 В `nifi-templates/` лежат примеры:
 - `Sample2Kafka.json` — публикует JSON-сообщения в Kafka topic `Sample2Kafka`
 - `SampleKafka2Postgres.json` — читает JSON из Kafka topic `Sample2Kafka` и пишет в Postgres (в `stg.samplekafka2postgres`, затем вызывает `ods.load_samplekafka2postgres()`)