CHECK_SUM

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

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

Поддерживается в версиях: 7.6 / 7.5 / 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-запроса
).

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

по обычным логическим таблицам;
по снапшот-таблицам (рассчитывается по изменениям за соответствующий период);
по партициям.

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

Для партиционированных таблиц (Таблица, позволяющая работать с данными партиций. Сама не хранит данные
) и прокси-таблиц (Таблица без версионирования данных и отслеживания их удалений
) в ответе всегда возвращается 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"     
    }
  ] 
}'

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

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

Контрольная сумма по отдельной логической сущности рассчитывается так:

В соответствующей физической таблице (Таблица в датасорсе, хранящая данные логической сущности
) выбираются записи, которые были загружены и (или) обновлены с момента закрытия дельты (Целостный набор изменений в логической БД (аналог транзакции)
), предшествовавшей указанной (исключая границу), по момент закрытия указанной дельты (включая границу).
По каждой записи:
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-битная контрольная сумма логической базы данных.