Avro Path Resolver

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

Почему эта библиотека?

Эта библиотека родилась из реальной проблемы: data contracts в распределенных системах данных. Когда схемы эволюционируют между окружениями (dev → staging → prod) или перемещаются между топиками, традиционные хеш-функции не работают, потому что они чувствительны к:

• Именам топиков (
  dev.topic
  vs
  prod.topic
  )
• Именам полей record
• Порядку полей
• Порядку элементов в union

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

Возможности

Основные возможности

• Разбор схем Avro и извлечение информации о типах
• Разрешение типов по конкретным путям в сложных схемах Avro
• Поддержка алиасов при разрешении типов массивов
• Извлечение корневых типов на основе форматов парсеров (Debezium, Confluent и др.)
• Определение типов исходных баз данных из схем Debezium (MS SQL, PostgreSQL, MongoDB)

Возможности Data Contracts

• Физическое хеширование схем: Вычисление хешей, игнорирующих изменения имен и миграции между топиками
• Проверка эквивалентности схем: Определение, имеют ли две схемы идентичные структуры данных
• Семантическая совместимость: Проверка, можно ли безопасно использовать схему из dev в prod

Поддержка мульти-диалектов

Библиотека включает определения типов для следующих диалектов:

Сравнение схем

• Сравнение двух схем и выявление различий
• Генерация структурированного вывода diff
• Поддержка анализа эволюции схем Avro

Установка

Быстрый старт

Базовое использование

Физическое хеширование схем

Сравнение схем

Работа с Debezium

Определение типа источника

Debezium сохраняет информацию о типах исходной базы данных в метаданных схемы Avro. Эта библиотека извлекает эту информацию для определения типа исходной базы данных:

Библиотека использует эти метаданные для:

1. Определения исходной базы данных (PostgreSQL, MS SQL, MongoDB)
2. Преобразования типов Debezium в нативные типы базы данных
3. Включения кросс-базового перевода схем

Расширенное использование

Разрешение путей

Граф схемы

Работа с алиасами

Поддерживаемые форматы парсеров

Технологический стек

Основные зависимости

Инструменты разработки

Инструменты документации

Архитектурные технологии

Pydantic v2

Проект использует Pydantic v2 для создания строго типизированных моделей данных:

• BaseModel
  для структурированных данных
• RootModel
  для корневых типов (List, Union, etc.)
• model_validator
  для кастомной валидации
• cached_property
  для кэширования вычислений

Pyparsing

Для разбора SQL-типов используется

• Грамматические правила определены в
  grammar/dialect/*/data_types.py
• Каждый диалект (PostgreSQL, MS SQL, Trino, Spark, Iceberg) имеет свои правила парсинга
• Результат парсинга преобразуется в Pydantic-модели через
  set_parse_action()

Fastavro

• Парсинга схем Avro через
  fastavro.schema.parse_schema
• Разворачивания схем через
  expand_schema
• Работы с именованными схемами (
  named_schemas
  )

Разработка

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

avro_path_resolver/
├── __init__.py                 # Экспорты публичного API
├── version.py                  # Информация о версии
├── exceptions/                 # Пользовательские исключения
│   └── exception_base.py
├── grammar/                    # Грамматика и определения типов
│   ├── data_type_model.py      # Базовые модели типов
│   ├── utils.py                # Утилиты разрешения типов
│   └── dialect/                # Типы для конкретных диалектов
│       ├── avro/
│       ├── postgresql/
│       ├── mssql/
│       ├── trino/
│       ├── spark/
│       ├── iceberg/
│       ├── java/
│       └── greenplum/
└── utils/                      # Утилитарные модули
    ├── avro_schema_parser/     # Основная логика разбора
    ├── analyze_diff/           # Анализ diff схем
    ├── dump_metadata/          # Выгрузка метаданных
    └── json_diff/              # JSON diff

Вклад в проект

Вклад приветствуется! Пожалуйста, прочитайте наше Руководство по вкладу для подробной информации.

1. Форкните репозиторий
2. Создайте ветку функции (
   git checkout -b feature/amazing-feature
   )
3. Закоммитьте изменения (
   git commit -m 'Add some amazing feature'
   )
4. Отправьте в ветку (
   git push origin feature/amazing-feature
   )
5. Откройте Pull Request

Лицензия

Этот проект лицензирован под лицензией MIT - см. файл LICENSE для подробной информации.

Благодарности

Эта библиотека изначально разрабатывалась как часть системы управления data contracts для распределенных пайплайнов данных. Алгоритм физического хеширования схем был разработан для решения реальных задач эволюции схем и миграции между окружениями.

История версий

Смотрите CHANGELOG.md для истории релизов.