Начало работы

Пререквизиты

Компетенции пользователя

• Базовые знания SQL и git. Дополнительных технических навыков для начала работы не требуется.

• Минимальный опыт написания YAML или 5 минут на знакомство с форматом
  
  

Как получить доступ

1) Для начала работы с DQ NEO вам потребуется доступ к:

• системе Vault — хранилищу секретов, используемому для хранения параметров авторизации на источниках данных

Начало работы

Прежде, чем начать настраивать DQ проверки, мы рекомендуем ознакомиться:

• с кратким описанием Модели данных и Ролевой модели DQ NEO

Создание тестовой проверки

• Сначала убедимся в успешном подключении источинка данных. для этого создадим и запустим одну тестовую проверку.
• Проверки настраиваются в формате YAML, подробное описание есть на странице 4. Конфигурация метрик и сравнений.

Пример базовой конфигурации с необходимыми полями:

---
sources:
- name: dq-course-main-db  # придумайте имя для своего источника. Имена всех сущностей должны быть уникальными.
  type: postgres           # тип нашего источника
  parameters:
    host: 127.0.0.1        # хост (ip адрес или доменное имя)
    port: 5432             # порт
    database: dq_course    # имя базы
    credentials:
      type: vault                        # тип хранилища секретов
      path: platform/dq/demo/ocean_demo  # путь в Vault, где лежат credentials подключения к источнику
      user: dq_course_user               # наш логин к базе (должен совпадать с полем key в Vault)
  owners:                  # Владельцы источника, которые могут редактировать и запускать проверки на этой БД,# 
  - user1                  #   владельцем может быть как ваша собственная УЗ
  - tech_user_2            #   так и технический пользователь
  - ad_group_name          #   или AD группа


check_objects:
  - name: datagov_products.public.dq_course.dq-course-main-db  # имя таблицы, старайтесь придерживаться naming convention {Table name}.{DB name}.{Source name}
    source: dq-course-main-db # имя из блока Source
    database: dq_course       # база
    schema: public            # схема
    table: datagov_products   # таблица

metrics:
  - name: total_records_count.datagov_products.public.dq_course.dq-course-main-db  # имя согласно конвенции
    type: row_count              # тип метрики
    check_object: datagov_products.public.dq_course.dq-course-main-db  # имя объекта проверки из предыдущего блока
    parameters:
      column: "*"                # столбец, по которому считаем
      date_column_name: Date     # столбец с бизнес датой, по которой фильтруем

  - name: product_name_distinct.datagov_products.public.dq_course.dq-course-main-db
    type: row_count_distinct
    check_object: datagov_products.public.dq_course.dq-course-main-db
    parameters:
      column: "product_name"
      date_column_name: Date

  - name: product_name_nulls.datagov_products.public.dq_course.dq-course-main-db
    type: row_count_null
    check_object: datagov_products.public.dq_course.dq-course-main-db
    parameters:
      column: "product_name"
      date_column_name: Date

compares:
  - name: Timeliness.datagov_products.public.dq_course.dq-course-main-db  # имя проверки
    type: compare_with_static_values   # тип проверки
    metric: total_records_count.datagov_products.public.dq_course.dq-course-main-db # имя метрики из блока metrics
    parameters:
      min_value: 1      # есть хотя бы 1 запись за бизнес-дату
      max_value: inf    # можно использовать значения inf и -inf, чтобы поставить порог в +/- Бесконечность
    description: 'Актуальность: проверка на наличие новых данных'  # Добавляем краткое описание нашей проверки

  - name: Uniqueness.datagov_products.public.dq_course.dq-course-main-db
    type: absolute_ratio
    metric: total_records_count.datagov_products.public.dq_course.dq-course-main-db
    parameters:
      reference_metric: product_name_distinct.datagov_products.public.dq_course.dq-course-main-db  # имя второй метрики из блока метрики, с которой будем сравнивать
      min_value: 1
      max_value: 1
    description: 'Уникальность: отсутствие дублей в колонке product_name'

  - name: Completeness_product_name.datagov_products.public.dq_course.dq-course-main-db
    type: percent_delta
    metric: product_name_nulls.datagov_products.public.dq_course.dq-course-main-db
    parameters:
      reference_metric: total_records_count.datagov_products.public.dq_course.dq-course-main-db
      min_value: 0
      max_value: 0      # ожидаем, что в поле нет NULL значений
    description: 'Полнота: заполненность product_name'

# группа для запуска проверок (обычно одна проверка это редкость)
groups:
  - name: datagov_products.public.dq_course.dq-course-main-db  # имя группы
    compares: # перечисляем наши проверки
      - Timeliness.datagov_products.public.dq_course.dq-course-main-db
      - Uniqueness.datagov_products.public.dq_course.dq-course-main-db
      - Completeness_product_name.datagov_products.public.dq_course.dq-course-main-db
    run:
      schedule: '0 1 * * *'  # расписание запуска, ежедневно в 01:00
      days_data_lag: 1       # метрики будут вычисляться за предыдущую дату (по полю Date)

alerts:
  - name: datagov_products.dq-course-main-db
    annotations:
      summary: 'Не прошли проверки по {check_object} за {compare_date}' # Описание сообщения в алерте с плейсхолдерами в фигурных скобках
    channels:            # каналы отправки алерта
      - smtp             # на email
    emails:
      - user@gmail.com # адреса получателей
    groups:
      - datagov_products.public.dq_course.dq-course-main-db
    fields:              # список полей, которые будут показаны в письме с алертом
      - description
      - status
      - value
      - min_value
      - max_value
    statuses: [-1, -2]   # статусы срабатывания "-1" — проверка прошла не успешно (выявилось несоответствие пороговым значениям из правила проверки). "-2" — возникла ошибка при вычислении метрики.

• При выборе имени сущностей (атрибут name) придерживайтесь рекомендаций из Naming convention и структура хранения конфигураций

Шаг 1. Создайте и сохраните у себя YAML файл по примеру выше

Шаг 2. Есть несколько вариантов сохранения получившейся конфигурации в метастор DQ, самый простой — через DQ UI

Шаг 3. Нажмите Load YAML на первой странице и выберите ваш файл

Если в файле нет синтаксических ошибок, отобразится подтверждение об успешном создании проверок:

Запуск тестовой проверки

Шаг 1. Найдите свою группу проверок через поиск на главной странице:

Шаг 2. Перейдите на страницу с Группой и выберите Дату проверки, например, сегодняшнюю:

Шаг 3. Нажмите Run. В случае успешного запуска отобразится подтверждение:

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

Шаг 4. Чтобы убедиться, что наша проверка посчиталась, перейдите на страницу Runs и добавьте фильтр по имени группы:

- В том случае, если метрика из группы была успешно вычислена, справа в таблицу к запуска будет Зеленый статус - Если при вычислении хотя бы одной метрики на источнике данных возникло исключение, статус будет Красный

Важно
Данный статус показывает только факт получения результата всем метрикам из группы. Статус проверок при этом может отрицательным.

Шаг 5. По ссылке из колонки ID запуска можно перейти на страницу с логами по данному запуску группы:

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

Также здесь можно увидеть, какие именно запросы DQ Neo отправляет на источник данных

Просмотр результатов проверок

• После завершения запуска проверок результаты можно увидеть на дашборде

• Укажите название вашей группы проверок в поле group

Описание дашборда есть на странице 6. Дашборды с результатами DQ

Просмотр логов

• Помимо UI логи DQ проверок также доступны в Kibana

• Подробнее про работу с логами в Kibana и частые ошибки при вычислении метрик можно прочитать на странице Типичные ошибки в работе проверок
  
  

Сохранение yaml конфигураций проверок в Gitlab

• В данный момент в DQ Neo не реализован аудит и версионирование сущностей, поэтому мы рекомендуем сохранять yaml файлы с настройками проверок в Git.

Краткую инструкцию по работе с Gitlab можно найти на странице 2. Работа с репозиторием проверок dq-cfg (gitlab)

Настройка регулярного запуска и алертов

• После этого можно переходить к созданию регулярных проверок. За основу можно взять Примеры конфигураций из раздела Cookbook

• Детальное описание конфигурации проверок доступно на странице 4. Конфигурация метрик и сравнений

FAQ

См. раздел F.A.Q

Расширенная документация

Описание API DQ
Перейти ↗

Cookbook с примерами конфигураций
Перейти ↗