CHECK_SUM

Содержание раздела

Связанные запросы
Поддерживаемые сущности
Режимы расчета контрольной суммы
Учитываемые датасорсы
Особенности проверки значений с плавающей точкой
Синтаксис
Варианты ответа
Ограничения
Примеры
Порядок расчета контрольных сумм

Поддерживается в версиях: 7.4 / 7.3 / 7.2 / 7.1 / 7.0 / 6.12 / 6.11 / 6.10 / 6.9 / 6.8 / 6.7 / 6.6 / 6.5 / 6.4 / 6.3 / 6.2 / 6.1 / 6.0 / 5.8 / 5.7 / 5.6 / 5.5 / 5.4 / 5.3 / 5.2 / 5.1 / 5.0.

Запрос возвращает контрольную сумму изменений данных между указанной дельтой (Целостный набор изменений в логической БД (аналог транзакции)
) (включительно) и предыдущей (не включительно). Дельта может быть закрытой или открытой.

Запрос может содержать индексированные и именованные параметры.

Контрольная сумма рассчитывается во всех учитываемых датасорсах по загруженным (Данные, записанные через Kafka или по HTTP через конечную точку /upload
) и обновленным (Данные, записанные с помощью INSERT/UPSERT VALUES, INSERT SELECT, UPDATE, DELETE.
) записям. В расчете участвуют записи указанной дельты и отдельных операций записи (Операция вставки, изменения или удаления версионируемых данных
), выполненных между указанной дельтой и предыдущей.

Подробнее об алгоритме расчета см. в секции Порядок расчета контрольных сумм.

Чтобы рассчитать контрольную сумму по итоговому состоянию данных (а не внесенным изменениям), используйте CHECK_SUM_SNAPSHOT, по выбранным строкам — SELECT с функцией CHECK_SUM_INT64 или CHECK_SUM_MD5.

Связанные запросы

CHECK_SUM_SNAPSHOT,
SELECT с функцией CHECK_SUM_INT64 или CHECK_SUM_MD5,
CHECK_DATA.

Поддерживаемые сущности

Расчет контрольной суммы в закрытой дельте (Целостный набор изменений в логической БД (аналог транзакции)
) доступен по следующим сущностям:

обычным логическим таблицам (Логическая таблица без партиционирования
),
партициям (Логическая таблица, содержащая данные с определенными значениями ключа партиционирования
),
логическим представлениям (Сущность с сохраненным SELECT-запросом (не хранит результаты)
) (см. ограничения ниже),
материализованным представлениям (Сущность с сохраненными результатами SELECT-запроса
).

Расчет контрольной суммы в открытой дельте доступен:

по обычным логическим таблицам,
по партициям.

Для партиционированных таблиц (Логическая таблица, позволяющая работать с данными партиций. Не хранит данные долговременно
) и прокси-таблиц (Логическая таблица без версионирования данных
) в ответе всегда возвращается 0.

Режимы расчета контрольной суммы

Контрольную сумму можно рассчитать:

по отдельным столбцам сущности,
всем столбцам сущности,
всем столбцам всех логических таблиц (Таблица с версионируемыми данными
) логической БД (Набор логических сущностей (датамарт)
).

При расчете контрольной суммы по отдельным столбцам рекомендуется добавлять первичный ключ в список столбцов. Это повысит уникальность контрольных сумм.

Учитываемые датасорсы

Контрольная сумма рассчитывается по каждому включенному (Датасорс, работающий в штатном режиме
) датасорсу (СУБД или кластер СУБД хранилища
), содержащему данные проверяемой логической сущности. Отключенные (Датасорс, отключенный системой из-за сбоя или администратором
) датасорсы пропускаются при расчете без возврата ошибки и не отображаются в ответе.

Подробнее об алгоритме расчета см. в секции Порядок расчета контрольных сумм.

Особенности проверки значений с плавающей точкой

Значения с типами FLOAT и DOUBLE могут иметь разные контрольные суммы из-за разницы в точности типов. Чтобы избежать расхождения в контрольных суммах, используйте любой из способов:

используйте тип DOUBLE для всех значений с плавающей точкой (он больше распространен среди СУБД, чем FLOAT);
исключайте столбцы типа FLOAT и DOUBLE из запросов CHECK_SUM.

Синтаксис

Запрос по сущности:

CHECK_SUM(delta_num[, normalization], [db_name.]entity_name[, column_list])

Запрос по предварительно выбранной логической БД (Набор логических сущностей (датамарт)
):

CHECK_SUM(delta_num[, normalization])

Любые аргументы запроса могут быть заданы как индексированные и (или) именованные параметры.

Параметры:

delta_num (BIGINT | INT64 | LONG)

Номер дельты (Целостный набор изменений в логической БД (аналог транзакции)
), по которой рассчитывается контрольная сумма изменений. Дельта может быть закрытой или открытой.

normalization (BIGINT | INT64 | LONG)

Коэффициент, увеличивающий лимит проверяемых записей в сущности, но снижающий уникальность контрольных сумм. Обязателен в параметризованном запросе, где за коэффициентом следуют другие аргументы, и опционален иначе.

Принимает целые значения от 1 (по умолчанию).

Если не указан или равен 1, запрос может проверить до 4'294'967'298 записей в каждой сущности; при увеличении коэффициента лимит растет пропорционально.

db_name (VARCHAR | CHAR | STRING)

Имя логической базы данных (Набор логических сущностей (датамарт)
), которой принадлежит проверяемая сущность. Опционально, если выбрана логическая БД, используемая по умолчанию.

entity_name (VARCHAR | CHAR | STRING)

Имя поддерживаемой логической сущности, по которой рассчитывается контрольная сумма. Если не указано, система рассчитывает контрольную сумму по всем логическим таблицам (Таблица с версионируемыми данными
) логической БД.

column_list (VARCHAR | CHAR | STRING)

Опциональный список имен столбцов, по которым рассчитывается контрольная сумма.

В параметризованном запросе элементы списка указываются в одном параметре (см. пример ниже), в остальных случаях — перечисляются в квадратных скобках через запятую (например, [id, product_code]).

Если столбцы не указаны, система рассчитывает контрольную сумму по всем столбцам сущности.

Варианты ответа

В ответе возвращается:

объект ResultSet с контрольной суммой при успешном выполнении запроса и отсутствии расхождений между датасорсами (СУБД или кластер СУБД хранилища
);
исключение при наличии расхождений или неуспешном выполнении запроса.

При наличии расхождений ответ содержит исключение с текстом ошибки Consistency breach detected for <entity_name> и списком контрольных сумм по проверенным датасорсам. Если расхождение найдено при расчете контрольной суммы по логической БД (Набор логических сущностей (датамарт)
), система останавливает расчет на первом найденном расхождении, возвращает ошибку и не проверяет следующие сущности.

Ограничения

Ограничения сущностей

Контрольная сумма по всей логической БД (Набор логических сущностей (датамарт)
) рассчитывается только по данным логических таблиц (Таблица с версионируемыми данными
). Данные логических и материализованных представлений (Сущность с сохраненными результатами SELECT-запроса
) не учитываются.
Расчет контрольной суммы недоступен для сущностей:
- логических представлений (Сущность с сохраненным SELECT-запросом (не хранит результаты)
  ), основанных на данных СУБД ADQM;
- логических представлений, основанных на данных прокси-таблиц (Логическая таблица без версионирования данных
  ) и standalone-таблиц (Таблица датасорсе вне логической и физической схем данных Prostore
  );
- партиционированных таблиц (Логическая таблица, позволяющая работать с данными партиций. Не хранит данные долговременно
  );
- прокси-таблиц.
Максимальное количество записей в одной сущности, по которым можно рассчитать контрольную сумму, ограничено и регулируется коэффициентом нормализации.

Ограничения точности

Есть небольшая вероятность, что контрольные суммы совпадут для разных наборов данных.
Значения типа FLOAT и DOUBLE могут приводить к расхождениям в контрольных суммах из-за разницы в точности типов.

Другие ограничения

Расчет контрольной суммы в открытой дельте (Целостный набор изменений в логической БД (аналог транзакции)
) доступен только для логических таблиц (Таблица с версионируемыми данными
).
Изменения, совершенные после последней закрытой дельты, учитываются в расчете только при запросе по открытой дельте. Если открытой дельты нет, контрольную сумму таких изменений рассчитать невозможно.
При обработке запроса отключенные (Датасорс, отключенный системой из-за сбоя или администратором
) датасорсы (СУБД или кластер СУБД хранилища
) пропускаются без возврата ошибки. Ошибка возвращается, если не осталось ни одного включенного (Датасорс, работающий в штатном режиме
) датасорса, подходящего для исполнения запроса.

Примеры

Запрос по отдельным столбцам логической таблицы

Расчет контрольной суммы по трем столбцам логической таблицы (Таблица с версионируемыми данными
) sales в седьмой дельте (Целостный набор изменений в логической БД (аналог транзакции)
):

CHECK_SUM(7, marketing.sales, [id, transaction_date, product_code])

На рисунках ниже показаны примеры ответов на запрос CHECK_SUM с перечислением столбцов: на первом — ответ при отсутствии расхождений в данных между датасорсами (СУБД или кластер СУБД хранилища
), на втором — ответ при наличии расхождений.

Ответ CHECK_SUM по отдельным столбцам таблицы при отсутствии расхождений

Ответ CHECK_SUM при наличии расхождений

Запрос по всем столбцам логической таблицы

Расчет контрольной суммы по всей логической таблице (Таблица с версионируемыми данными
) sales в седьмой дельте (Целостный набор изменений в логической БД (аналог транзакции)
):

CHECK_SUM(7, marketing.sales)

На рисунке ниже показан пример ответа CHECK_SUM по логической таблице.

Ответ CHECK_SUM по логической таблице

Запрос по всем столбцам материализованного представления

Расчет контрольной суммы по всему материализованному представлению (Сущность с сохраненными результатами SELECT-запроса
) sales_by_stores в десятой дельте (Целостный набор изменений в логической БД (аналог транзакции)
):

CHECK_SUM(10, matview_db.sales_by_stores)

Запрос по всем столбцам партиции

Расчет контрольной суммы по всей партиции (Логическая таблица, содержащая данные с определенными значениями ключа партиционирования
) marketing.sales_jan_2023 во второй дельте (Целостный набор изменений в логической БД (аналог транзакции)
):

CHECK_SUM(2, marketing.sales_jan_2023)

Запрос по логической базе данных

Расчет контрольной суммы по всем таблицам логической БД (Набор логических сущностей (датамарт)
) marketing в седьмой дельте (Целостный набор изменений в логической БД (аналог транзакции)
):

-- выбор логической базы данных marketing в качестве базы данных по умолчанию
USE marketing;

-- расчет контрольной суммы логической БД
CHECK_SUM(7);

На рисунке ниже показан пример ответа CHECK_SUM по логической базе данных.

Ответ CHECK_SUM по логической базе данных

Запрос по логической базе данных с коэффициентом нормализации

Расчет контрольной суммы по всем таблицам логической БД (Набор логических сущностей (датамарт)
) marketing с коэффициентом нормализации, равным 100:

-- выбор логической базы данных marketing в качестве базы данных по умолчанию
USE marketing;

-- расчет контрольной суммы логической БД с указанным коэффициентом нормализации
CHECK_SUM(7, 100);

На рисунке ниже показан пример ответа на такой запрос.

Запрос CHECK_SUM с коэффициентом нормализации

Запросы с индексированными параметрами

Расчет контрольной суммы по таблице с указанием коэффициента нормализации, но без столбцов:

CHECK_SUM(?, ?, ?)

Расчет контрольной суммы по таблице с указанием коэффициента нормализации и списка столбцов:

CHECK_SUM(?, ?, ?, ?)

Пример cURL-запроса:

curl -X POST \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: f261590a-f624-4990-9781-0153cd1a2a94' \
  -H 'Content-Type: application/json' \
  -d '{   
  "query": "CHECK_SUM(?, ?, ?, ?)",   
  "queryId": "2173823437",   
  "params": [     
    {         
      "value": 0,       
      "type": "LONG"     
    },
    {         
      "value": 2,       
      "type": "LONG"     
    },
    {          
      "value": "marketing.sales",       
      "type": "STRING"     
    },     
    {        
      "value": "id, product_code",       
      "type": "STRING"     
    }
  ] 
}'

Запросы с именованными параметрами

Расчет контрольной суммы по таблице с указанием коэффициента нормализации, но без столбцов:

CHECK_SUM(:delta_number, :normalization, :entity_name_with_db_name)

Расчет контрольной суммы по таблице с указанием коэффициента нормализации и списка столбцов:

CHECK_SUM(:delta_number, :normalization, :entity_name_with_db_name, :column_list)

Пример cURL-запроса:

curl -X POST \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 21775405-aae6-421a-a662-7f4e247c3947' \
  -H 'Content-Type: application/json' \
  -d '{   
  "query": "CHECK_SUM(:delta_number, :normalization, :entity_name_with_db_name, :column_list)",   
  "queryId": "287647821",   
  "params": [     
    {      
      "name": "delta_number",       
      "value": 0,       
      "type": "LONG"     
    },
    {      
      "name": "normalization",       
      "value": 10,       
      "type": "LONG"     
    },
    {       
      "name": "entity_name_with_db_name",       
      "value": "marketing.sales",       
      "type": "STRING"     
    },     
    {       
      "name": "column_list",       
      "value": "id, product_code",       
      "type": "STRING"     
    }
  ] 
}'

Порядок расчета контрольных сумм

Расчет контрольной суммы по таблице или представлению

Контрольная сумма по логической таблице (Таблица с версионируемыми данными
), логическому представлению (Сущность с сохраненным SELECT-запросом (не хранит результаты)
) или материализованному представлению (Сущность с сохраненными результатами SELECT-запроса
) рассчитывается так:

В соответствующей физической таблице (Таблица в датасорсе, хранящая данные логической сущности
) выбираются записи, которые были загружены и (или) обновлены в указанной дельте (Целостный набор изменений в логической БД (аналог транзакции)
) и операциях записи (Операция вставки, изменения или удаления версионируемых данных
), выполненных между указанной дельтой и предшествующей ей.
По каждой записи:
1. Формируется текстовая строка: значения столбцов записи конвертируются в зависимости от типа данных и записываются через точку с запятой. Значение NULL записывается как пустая строка. Подробнее о конвертации значений см. ниже.
2. Для полученной строки вычисляется MD5-хеш в виде байтовой последовательности в шестнадцатеричном формате.
3. Хеш интерпретируется как ASCII-строка в нижнем регистре.
4. Выбираются первые 4 символа строки, выстраиваются в порядке от младшего к старшему (little endian) и конвертируются в целое 32-битное число.
5. Полученное число делится на коэффициент нормализации, дробная часть результата отбрасывается — получается контрольная сумма записи.
Контрольные суммы всех выбранных записей суммируются — получается 64-битная контрольная сумма изменений в логической сущности.

Если логическое представление и его сущности-источники принадлежат разным логическим БД, контрольная сумма представления рассчитывается по изменениям данным в источниках, выбранным на основе меток времени дельт в БД представления. Например, для дельты 10 представления могут использоваться изменения данных источника из дельты 2.

Конвертация значений столбцов

В таблице ниже показано, как значения столбцов (column_value), указанных в запросе, конвертируются в зависимости от их типа данных.

Тип данных	Порядок конвертации	Пример
BOOLEAN	(column_value)::int	true -> 1
DATE	column_value - make_date(1970, 01, 01)	2021-03-15 -> 18701
TIME	(extract(epoch from column_value)*1000000)::bigint	13:01:44 -> 46904000000
TIMESTAMP	(extract(epoch from column_value)*1000000)::bigint	2020-11-17 21:11:12 -> 1605647472000000
Другие типы данных	column_value	Иванов -> Иванов

Пример расчета контрольной суммы по таблице

Рассмотрим пример расчета контрольной суммы таблицы sales в дельте (Целостный набор изменений в логической БД (аналог транзакции)
), в которой была добавлена одна запись со следующими значениями:

id = 10021,
transaction_date = 2020-11-17 21:11:12,
product_code = ABC1830.

В качестве коэффициента нормализации возьмем число 10.

Контрольная сумма таблицы рассчитывается так:

Формируется строка для хеш-функции: 10021;1605647472000000;ABC1830.
Вычисляется MD5-хеш: bedbead6aea8ca373d8f0a15713639c1.
Выбираются первые 4 символа хеша: bedb.
Символы интерпретируются как ASCII-строка в нижнем регистре: 98 101 100 98.
Строка конвертируется в целое 32-битное число: 98*2⁰ + 101*2⁸ + 100*2¹⁶ + 98*2²⁴ = 1650746722.
Полученное значение делится на коэффициент нормализации, остаток отбрасывается: 1650746722 : 10 = 165074672.

Так как в таблицу добавлена одна запись в дельте, контрольная сумма таблицы в этой дельте равна полученной контрольной сумме записи (165074672).

Если бы в рассмотренной дельте в таблицу также была добавлена запись с контрольной суммой 87891666, итоговая контрольная сумма таблицы была бы равна 165074672 + 87891666 = 252966338.

Расчет контрольной суммы по логической базе данных

Контрольная сумма логической базы данных (Набор логических сущностей (датамарт)
) рассчитывается так:

По каждой логической таблице (Таблица с версионируемыми данными
) в логической базе данных рассчитывается контрольная сумма, как описано выше.
Контрольные суммы всех логических таблиц суммируются — получается 64-битная контрольная сумма логической базы данных.