Ivan Grishaev's blog

Don't be a meat proxy

Wed, 14 Oct 2026 00:00:00 +0000

Коротенькая заметка о ребятах, которые на все отвечают выхлопом нейросети: Don’t be a meat proxy. Хороша тем, что метко вводит новый термин: meat proxy. Мясной посредник между человеком и нейросетью.

Замечаю, что все больше людей скатываются к роли посредника. Задаешь коллеге вопрос – он подвисает на пять минут и кидает md-выхлоп. Разумеется, он его не читал: тебе надо – ты и разбирайся.

Попадаются ребята, которые открыто пишут: Иван, я передал твои замечания по ревью нейросети, и вот что она сказала… Далее идет md-выхлоп, который, конечно же, заботливый коллега даже не читал.

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

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

С нейросетями та же история. Есть те, кто по какой-то причине не понимает: людям нравится нормальное, живое общение. Взаимодействие с машиной – это один протокол, с человеком – другой. Если коллега отвечает макрдаун-выхлопом, то тем самым нарушает негласные договоренности. С ним просто не хочется общаться – каким бы лапочкой и хорошим человеком он ни был.

Верю, что когда-то это поймут. Я подожду.

О Конфуции

Wed, 14 Oct 2026 00:00:00 +0000

Читаю Конфуция. Вот какой случай напомнил о нем.

Жил в Америке ультра-патриот. Трамп, МАГА, все дела. Потом женился на русской эмигрантке, и пара поехала в отпуск. Супруга как раз продлевала визу, и оказалось, что старый документ уже недействителен, а новый еще не выдали.

В аэропорту к паре подошли представители ICE – Immigration and Customs Enforcement (иммиграционная и таможенная служба США). Тут важно понимать контекст. Формально ICE борется с незаконной миграций, однако при Трампе штат расширили на порядок, чтобы проводить облавы. На работу в ICE устраивается отребье вроде бывших военных, таксистов и охранников. Мало того, что эти люди озлоблены на всех; так еще государство дает им в руки летальное оружие, чтобы задерживать мигрантов.

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

Представителям ICE не понравилось, что у супруги виза еще не выдана. Ее отправили в приемник, и там она провела несколько недель. Ситуация в приемнике ICE местами хуже, чем в тюрьме. Например, свет никогда не выключают, а охранники нарочно громко говорят по рации. Неделя – и от недосыпания едет крыша. Никаких медикаментов достать нельзя, правозащитников не пускают. За грубое слово изобьют и скажут родственникам, что поскользнулся на банановой кожуре.

Все это время муж пытался вызволить супругу. Навещал ее трижды в неделю, видел все своими глазам. В итоге женщину отпустили под залог с надетым на ногу браслетом. В обращении к прессе мага-патриот сказал, что разочарован в Трампе и ситуации с преследованием людей.

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

При том, что примерно в 680 году ДО нашей эры (то есть 2700 лет назад) Конфуций вывел формулу человеколюбия: не делай другим того, чего не желаешь себе. Разумеется, и до Конфуция эту мысль высказывали в том или ином виде, но он возвел ее в абсолют. На человеколюбии держится все учение Конфуция.

Условный мага-патриот уверен: можно устраивать облавы на мигрантов ради высшего блага. Ведь это мигранты: они цветные, глупые, что с них взять. Подумаешь, в приемнике тяжело спать и нет медикаментов? Это ложь правозащитников.

Но когда в жернова попадает близкий человек, все меняется. Товарищ ~~Сталин~~ Трамп, произошла чудовищная ошибка…

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

За последние 2700 лет люди не придумали ничего лучше этой формулы. Остальные религии и учения – просто ее повторы. Например, формула целиком вмещает десять христианских заповедей: почитай родителей, не укради, не убий… В самом деле: хочешь, чтобы дети тебя уважали? Уважай своих родителей. Не хочешь, чтобы у тебя крали? Не кради сам. Не хочешь быть убитым? Не убий.

И так далее.

Глядя на историю людей, иной раз поражаешься. Мысль высказали 2700 лет назад и с тех пор повторяют во всех вариациях. Понять ее – это ведь не вырастить плавник или третью руку: тут не нужны тысячелетия. Но судя по текущей обстановке, до понимания формулы осталось еще очень и очень долго.

Чинить или отказаться

Wed, 14 Oct 2026 00:00:00 +0000

Когда что-то не работает, очевидное решение в том, чтобы починить. Второе неочевидное – отказаться. Чем старше становлюсь, тем чаще отказываюсь от того, что ломается. Разумеется, тезис слишком абстрактный и решается по ситуации. Но часто отказ не рассматривают в принципе и чинят одно и то же годами. Не надо так: отказ и пересмотр очень важны.

Повторный рендер

Wed, 14 Oct 2026 00:00:00 +0000

Почти на всех сайтах я замечаю повторный рендер. Это когда контент нарисовался, а потом Реакт решил, что виртуальное дерево устарело. Поэтому вжух – и контент рисуется еще раз.

То же самое во многих мобильных и настольных приложениях вроде Slack или Teams — которые только называются “приложениями”, а на самом деле оболочка Хрома или WebView.

Никто не считает это проблемой. Подумаешь, мигнул контент! В нулевые скорость была низкая, верстали таблицами, и сайт собирался по 30 секунд. Бывало, уже давно читаешь текст, и раз – что-то подгрузилось, подпрыгнуло, перестроилось. А тут – всего-то мигнуло.

Забавно, что современный фронтенд по-прежнему в ситуации эпохи нулевых – не может победить технические трудности. Должен быть улучшенный алгоритм рендера, который бы не срабатывал дважды. Еще лучше – дать над этим контроль разработчику.

Ну и фронтендеры хороши: никого не парит, что экран мерцает. Я вот заметил недавно, что на каждый клик огромная таблица повторно рендерится. А мне отвечают – не приоритетная задача. Спасибо, починим через никогда.

Давайте договоримся: не важно что у вас под капотом, Реакт-Вуй или что угодно. Контент не должен перерисовываться только потому, что ему так показалось. А если эти ваши Реакты-Вуи не починить, то верстайте так, чтобы не провоцировать повторный рендер.

Confirmation

Wed, 14 Oct 2026 00:00:00 +0000

Подтверждать или нет?

Кстати, лютейше бесят ребята, которые делают кнопку подтверждения слева. Это неправильно. Продолжение действия должно быть справа, а слева — возврат или отмена. Разумеется, к тем ребятам, которые не могут показать текст, это не относится — у них еще все впереди.

Кложурный тулинг

Wed, 14 Oct 2026 00:00:00 +0000

Если я правильно понимаю ты писал (пишешь?) на питоне в том числе. Просто я немного поглядываю что происходит в мире clоjure и вижу, люди как-то справляются без linter-ов, typechecker-ов и без такого инструмента, как uv (это менеджер интерпретатора, зависимостей проекта и виртуального окружения) в мире python. Когда работаешь с чужим кодом и погружаешься в него, то такие вещи очень сильно помогают. Возможно, в мире clоjure как-то можно обойтись без них, но тогда мне интересно как?

До прихода в Кложу я много писал на Питоне. Сейчас, хоть и меньше, тоже приходится: на работе есть Python-лямбды и скрипты. Питон — популярный язык, и я прибегаю к нему в случаях, если нужно что-то продемонстрировать для широкой аудитории.

Если отвечать на вопросы буквально, то да: тулинг Кложи не дотягивает до Питона. Для него созданы десятки линтеров и чекеров, а к каждому — еще столько же плагинов. Есть Jetbrains с Pycharm, которая выводит типы и предлагает автокомплит на любой чих. Программирование на Питоне в Pycharm стало как в Джаве — все типы подхватываются, и возникает ощущение, что в языке строгая типизация. Что касается uv и uvx, то я не застал их, но знаю, что это мощные средства.

До этого изобилия Кложе далеко как до Луны. IDE нет, есть только плагины к редакторам. Я пользуюсь связкой Emacs + Cider, но понимаю, что освоить ее новичку трудно. Автокомплит каждый настраивает как может. Проверку синтаксиса в полете и прочие удобства — тоже. Централизованным решением вроде Jetbrains даже не пахнет, и вряд ли оно когда-либо появится.

Не все так плохо с линтерами. Есть весьма развитый clj-kondo, который отлавливает много ошибок, например неверное число аргументов, необъявленные переменные и так далее. Суммарно кложурных линтеров наберется с десяток, и если использовать хотя бы пару из них, это решит некоторое число проблем. Также есть форматтеры кода по определенным правилам.

Существует кложурный LSP сервер (Language Server Protocol). Во многих редакторах LSP-клиент идет из коробки (VS Code, Emacs), так что здесь наблюдается развитие. С LSP у вас будет автокомплит, переход по коду и остальные базовые вещи.

В Кложе есть REPL, который закрывает много проблем. REPL основан на том положении, что единственный способ доказать, что код работает – это запустить его. Бывает, что код на Джаве выглядит корректно, но не работает. Непойманное исключение, ошибка индекса в массиве, NPE и так далее. Все это проверяется на практике, компилятор не поможет. Будет глупо оправдываться тем, что компиляция прошла: какая разница, если прод падает?

Зато REPL позволяет выполнить код в редакторе и отловить подобные случаи. Кстати, замечаю вот что: все больше джавистов топят за TDD – разработку от тестов. Парни не понимают, что TDD – это прокисший REPL, своего рода костыль, чтобы поскорее запустить код. В Джаве нет репла, но есть зеленая кнопочка Run, которая появляется в Main- и Test-классах. Нажатие этой кнопочки – просто убогий способ запустить код и ничего больше.

REPL не отменяет тестов, их пишут – юнит-, интеграционные и так далее.

Если переходить на Кложу с языков вроде Питона или Джавы, будет неудобно. Там у вас уютный Jetbrains, который по одной клавише угадывает экран кода. Здесь — самосбор: плагины к редактору, запуск линтера из командной строки. Зачем все это?

Затем, чтобы выйти из зоны комфорта, увидеть разнообразие, попробовать себя в чем-то другом. IDE и тулинг на все случаи жизни — это здорово, но нельзя на них замыкаться. Не вся работа делается в IDE по подписке. Когда Рич и Кен делали Unix и Си, разве были у них средства, аналогичные нашим? Они сами написали линтеры, парсеры, чекеры и прочие обвязки. А как написали IDE без IDE?

Удобства – это хорошо, но плохо, когда зависишь от них. Если точнее, плохо, когда кругозор сужается до той степени, когда жизнь без удобств становится немыслимой. Речь не о том, чтобы полностью от них отказаться. Но полезно быть в состоянии что-то сделать без привлечения мощных средств.

Когда вы увозите ребенка к бабушке в деревню, скорее всего там нет микроволновой печи, кондиционера, интернет-канала на 4К и других полезных вещей. Но никто не сомневается, что ребенку в деревне полезно: речка, солнце, животные. Отдохнет от гаджетов, помоется в дачном душе и вообще – не развалится.

Так и здесь. Да, чего-то не хватает, но не развалитесь. Можно и на Кложе писать хороший софт, зарабатывать и получать удовольствие. Да и не только на Кложе: я бы с удовольствием взялся за коммерческий проект на Common Lisp или Cobol — да на чем угодно! Нет тулинга? Не беда: либо обойдусь, либо напишу свой.

С таким настроем легко жить и смотреть в будущее.

On cowardness in Clojure code

Thu, 01 Oct 2026 00:00:00 +0000

Imagine you have a function accepting a value and doing something with it:

(defn double-number [x]
  (when x
    (* x 2)))

;; or

(defn get-user [id]
  (when id
    (jdbc/execute! *db* ["select..." id])))

A common pattern which comes all the time is to wrap the entire body with a (when id ...) form. You don’t want to process nil values so it’s safer to protect yourself against NPEs. Without (when ...), a nil value can ruin the entire pipeline, cause a null pointer error, trigger DB queries in vain and so on. These all sound reasonable, yet I’ve got my own term to describe such a kind of code: “coward style”.

A person who is wrapping the whole function with (when) isn’t getting one thing. If a function had been given nil, it should have never been called instead. Clojure provides a number of macros to call a function conditionally depending on arguments, for example:

(some-> (get-user-id) (get-user))

Should (get-user-id) return nil, the (get-user nil) form never gets called. The same applies to (cond->) and other macros that build an execution form conditionally.

In other words: a function must not check its input parameters for nils. But those people who call this function must.

Now let me explain the “coward style” I mentioned before. It’s when people write like this:

(defn double-number [x]
  (when x
    (* x 2)))

I don’t know what this code tells you, but to me, it’s clearly this: “Guys, I don’t want any problems. I don’t want any exceptions to be raised. If you supply me with a number, I’ll double it but won’t do anything if you pass nil. I cannot process it but won’t argue on you. Let’s keep it all quiet. Deal?”

This is a speech of a typical coward: I don’t want problems. I don’t want stack traces. I don’t want alerts and investigations. Let’s be quiet. The job is half-way done in fact as the function works partially. It won’t tell you when something is not quite right.

I’ve seen plenty of computation chains like this:

(-> some-param
    (parse-param)
    (pre-process-param)
    (get-use-id)
    (get-user-by-id)
    (send-user-somewhere))

Now imagine that every function starts with (when ...), and the final function crashes with NPE. It will be quite challenging to find who is guilty. These functions are real cowards: nobody wants to take blame. “I got nil → I returned nil. Not my business. I washed my hands”.

Thus, stop writing functions starting with (when ...). If a function silently swallows a nil value doing nothing, sooner or later you’ll pay for that. Or your teammates will.

There is still a way though to protect yourself against nils which I like a lot. Use built-in pre- and post conditions:

(defn double-number [x]
  {:pre [(number? x)]}
  (* x 2))

Now if you pass nil, you’ll get a clear error

(double-number nil)

;; Execution error (AssertionError) at … (REPL:211).
;; Assert failed: (number? x)

Preconditions help a lot with guessing types. Above, they clearly say x must be a number and nothing else. In addition to :pre and :post forms, the standard (assert ...) form might help in the middle of a function to interrupt execution when you know it makes no sense to go on with a weird value.

Keen mind that :pre, :post, and assert forms rely on the global *assert* variable. It’s a good practice to rely on assertions a lot but wipe them off on production as they slow down the code. When baking an uberjar, set clojure.core/*assert* to false. If it’s ClojureScript with a shadow compiler, pass {:elide-asserts true} into the :compiler-options map for a production release.

I agree that pre/post and assertions take lines of code, and sometimes they make code a bit noisy. But they will save you hours of debugging. Don’t be a coward whose main goal is to avoid exceptions. Don’t hide weird things. Be simple and explicit, and let your code express these two qualities.

Глава 10. Релевантный поиск

Fri, 18 Sep 2026 00:00:00 +0000

Главы

Содержание

Главы
Поиск в конкатенации полей
Слоеный поиск
Замечания к UNION
Последующая обработка
Замена UNION на FULL JOIN
Коротко о MapReduce
Поиск в исторической таблице
О быстродействии
Дальнейшие улучшения
Страничная навигация
Полнотекстовый поиск
Объект запроса
Определение и хранение языка
Полнотекстовый слой в UNION
Оптимизации и доработки
Заключение

В последней главе речь пойдет о релевантном поиске документов. При таком поиске документу назначено число, которое означает, насколько точно он подходит запросу. Мы узнаем, как выбирать документы по разным критериям, ранжировать и объединять их двумя способами. В числе прочего мы рассмотрим полнотекстовый поиск силами tsvector и tsquery.

В главе про индексы мы упомянули поиск документов. Поиск необходим любой системе, неважно стартап ли это или крупный банк. В основе поиска лежат правильные индексы, но их одних недостаточно: понадобятся и другие техники.

К поиску подходят разными способами. В одном из них пользователь заполняет форму: какое поле содержит какое значение. Интерфейс программы выглядит примерно так:

┌───────────────────────────────────────────┐
│                                           │
│   Номер заявки                            │
│  ┌──────────────────────────┐             │
│  │12345                     │             │
│  └──────────────────────────┘             │
│                                           │
│   Название организации                    │
│  ┌──────────────────────────┐             │
│  │Acme                      │             │
│  └──────────────────────────┘             │
│                                           │
│   Сотрудник                               │
│  ┌──────────────────────────┐             │
│  │Maria                     │             │
│  └──────────────────────────┘             │
│                                           │
│   Комментарий                             │
│  ┌──────────────────────────┐             │
│  │reconciliation            │             │
│  └──────────────────────────┘             │
│                                           │
│  ┏━━━━━━━━━━━━━━┓                         │
│  ┃    Найти     ┃                         │
│  ┗━━━━━━━━━━━━━━┛                         │
│                                           │
└───────────────────────────────────────────┘

Клиент отправляет форму на сервер. По четырем полям приложение строит запрос с условиями:

select
    id, doc
from
    applications
where
        (doc #>> '{application_id}')          =     '12345'
    and (doc #>> '{organization,short_name}') ilike '%acme%'
    and (doc #>> '{created_by,name}')         ilike '%maria%'
    and (doc #>> '{comment}')                 ilike '%reconciliation%'
limit
    100;

Подход “поле – значение” был популярен и встречается до сих пор. Однако со временем стало ясно: чем меньше полей требуется от клиента, тем проще ему пользоваться программой. С появлением сервисов вроде Гугла и Яндекса форма поиска сократилась до одного поля. Привыкнув к минимализму, некоторые пользователи теряются, видя интерфейс с дюжиной полей.

В случае Гугла и Яндекса минимализм, конечно, ложный. Поисковое выражение может содержать параметры: искать только на указанном сайте, обязательно включить одно слово, исключить другое. Поисковые системы опираются на историю запросов, геолокацию, интересы пользователя, собранные из разных источников. Запрос, отправленный клиентом, играет далеко не решающую роль. В этом легко убедиться, если выполнить в Гугле два одинаковых запроса под разными учетными записями.

Мы не можем построить поиск такого же масштаба, однако возьмем его за ориентир. Задача в том, чтобы принять от клиента как можно меньше данных и вернуть документы, которые соответствуют запросу в некоторой степени. Эта степень называется релевантностью, и мы рассмотрим ее ниже.

Поиск в конкатенации полей

В главе про индексы мы обсудили следующий прием. Предположим, форма имеет только одно поле – поисковое выражение (терм):

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  Номер заявки, ФИО сотрудника, комментарий (см. справку)    │
│ ┌──────────────────────────────────────────────┐┏━━━━━━━━━┓ │
│ │12345                                         │┃  Поиск  ┃ │
│ └──────────────────────────────────────────────┘┗━━━━━━━━━┛ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Это выражение проверяется для многих полей с разной логикой. Если пользователь ввел 123456, мы должны показать заявки, где:

либо номер заявки включает 123456;
либо название организации, подавшей заявку, включает 123456;
либо над заявкой работал пользователь, чье имя содержит 1234565;
либо в комментарии встречается такая последовательность.

Очевиден шаблон: каждое условие – отбор по определенному полю; условия объединяются оператором OR:

select
    id, doc
from
    applications
where
       (doc #>> '{application_id}')          ilike '%12398%'
    or (doc #>> '{organization,short_name}') ilike '%12398%'
    or (doc #>> '{created_by,name}')         ilike '%12398%'
    or (doc #>> '{comment}')                 ilike '%12398%'
limit
    100;

Для каждого поля и оператора создан индекс: btree для равенства или триграммный для вхождения. Если требуется пятый критерий, в часть WHERE добавляется новое поле, и для него строится индекс.

Подход со многими полями можно обобщить – объединить их в одно и искать по нему. Для этого пишут функцию, которая принимает документ и возвращает строку. В ней через пробел следуют поля, по которым ищут документ:

create or replace function immutable_concat_ws(text, variadic text[])
  returns text
  language internal immutable parallel safe AS 'text_concat_ws';

create or replace function application_search_pattern(doc jsonb)
returns text
language sql immutable strict parallel safe
return immutable_concat_ws(
    ' ',
    (doc #>> '{application_id}'),
    (doc #>> '{organization,short_name}'),
    (doc #>> '{created_by,name}'),
    (doc #>> '{comment}')
);

Создается триграммный индекс на выражение с функцией:

create index if not exists
idx_applications_application_trgm_pattern
on applications using gin
((application_search_pattern(doc)) gin_trgm_ops);

С ним поиск документов выглядит так:

select id from applications
where application_search_pattern(doc) ilike '%12345%'
limit 100;

Если вам что-либо непонятно из кода выше, обратитесь к третьей главе, где мы подробно объяснили каждое действие.

Несмотря на преимущества, подход с единым выражением обладает недостатком: поиск по нему не знает о релевантности. Оператор ilike сообщает, что совпадение нашлось, но в какой именно части – неизвестно. Наоборот, нам бы хотелось это знать, потому что поля следуют по убыванию важности. Чем ближе к началу нашлось совпадение, тем выше должен быть документ в выдаче.

Предположим, для двух документов функция application_search_pattern возвращает строки как в примере ниже (пробелы добавлены для читаемости):

code  org name         user name     comment
61312 Global Corp      Suzanne Smith reconciliation started ref #991015123
10151 General Acme Inc John Brown    some long comment about the app

Видим, что последовательность 10151 встретилась в обоих случаях, однако в первой строке это комментарий (последнее поле), а во втором – код заявки (первое). Из-за меньшей позиции второй документ считается более приоритетным, и мы должны показать его раньше. Однако оператор ilike не сообщает позицию, в которой нашлось совпадение. Если не принять мер, в поисковой выдаче документы окажутся в произвольном порядке.

Слоеный поиск

Рассмотрим технику, которая определяет приоритет точнее. Идея в следующем: документы разбивают на группы (слои), которым назначают им число – показатель релевантности (ранг). В нашем поиске выделим следующие группы:

код заявки в точности равен поисковому значению;
код организации равен поисковому значению;
код заявки содержит значение;
код организации содержит значение;
комментарий содержит значение.

Мы не случайно разделяем точность и вхождение. Во-первых, если пользователь ищет заявку 999, будет странно обнаружить ее на десятом месте после 9991, 3999 и других чисел с тремя девятками. Во-вторых, точное совпадение опирается на индекс btree, который быстрее триграммного.

Назначим группам нарастающие числа: 10, 20, 30 и так далее. Чем меньше этот показатель, тем раньше в выдаче идет строка. Интервал 10 подобран с умыслом: с ним между группами можно вставить еще одну, например с рангом 15. Если же интервал равен единице, придется сдвигать остальные ранги или переходить к вещественным числам: 1.0, 1.5, 2.0.

Для каждой группы пишут отдельный SELECT, который выбирает ключ документа и его ранг. Напомним, первая группа – та, где номер заявки в точности равен введенному выражению. Ее запрос следующий:

select id, 10 as rank
from applications
where (doc #>> '{application_id}') = '12398'

Ожидаемый результат:

┌──────────────────────────────────────┬──────┐
│                  id                  │ rank │
├──────────────────────────────────────┼──────┤
│ 00000000-0000-0000-0000-000000012398 │   10 │
└──────────────────────────────────────┴──────┘

Чтобы поиск по равенству был быстрым, понадобится btree-индекс. А поскольку номер заявки уникален, добавим директиву unique:

create unique index idx_doc_application_id
on applications ((doc #>> '{application_id}'))
nulls not distinct;

Вторая группа – равенство коду организации. Запрос аналогичен тому, что мы написали выше, отличаются только поле и ранг:

select id, 20 as rank
from applications
where (doc #>> '{organization.code}') = '12398'

Конкретно для 12398 результат будет пустым, потому что в базе нет организаций с таким кодом.

Третья группа – поиск по вхождению строки в номер заявки. Здесь мы используем триграммный поиск с шаблоном:

select id, 30 as rank
from applications
where (doc #>> '{application_id}') ilike '%12398%'

Запрос возвратит около десяти документов:

┌──────────────────────────────────────┬──────┐
│                  id                  │ rank │
├──────────────────────────────────────┼──────┤
│ 00000000-0000-0000-0000-000000912398 │   30 │
│ 00000000-0000-0000-0000-000000012398 │   30 │
│ 00000000-0000-0000-0000-000000112398 │   30 │
│ 00000000-0000-0000-0000-000000123980 │   30 │
│ 00000000-0000-0000-0000-000000123981 │   30 │
│ 00000000-0000-0000-0000-000000123982 │   30 │
│ 00000000-0000-0000-0000-000000123983 │   30 │
│ 00000000-0000-0000-0000-000000123984 │   30 │
│ 00000000-0000-0000-0000-000000123985 │   30 │

Четвертая группа – то же самое, но для кода клиента:

select id, 40 as rank
from applications
where (doc #>> '{organization.code}') ilike '%12398%'

Пятая и последняя – вхождение строки в комментарий:

select id, 50 as rank
from applications
where (doc #>> '{comment}') ilike '%12398%'

Частичный результат:

┌──────────────────────────────────────┬──────┐
│                  id                  │ rank │
├──────────────────────────────────────┼──────┤
│ 00000000-0000-0000-0000-000000912398 │   50 │
│ 00000000-0000-0000-0000-000000012398 │   50 │
│ 00000000-0000-0000-0000-000000112398 │   50 │
│ 00000000-0000-0000-0000-000000123980 │   50 │
│ 00000000-0000-0000-0000-000000123981 │   50 │
│ 00000000-0000-0000-0000-000000123982 │   50 │

Во всех случаях мы выбираем только ключ и ранг, но не сам документ. Это сделано нарочно: на данном этапе документ избыточен, требуются лишь минимальные сведения о нем.

Имея пять отдельных запросов, объединим их оператором UNION ALL. Слово ALL необходимо, чтобы Postgres не пытался удалить дубликаты строк – их все равно не будет. Даже если один и тот же документ встречается в разных выборках, у них будет разный ранг, и записи будут отличаться.

Предположим, пользователь ввел строку 12398 нажал ввод. Вот каким окажется промежуточный запрос:

select id, 10 as rank
from applications
where (doc #>> '{application_id}') = '12398'

union all

select id, 20 as rank
from applications
where (doc #>> '{organization.code}') = '12398'

union all

select id, 30 as rank
from applications
where (doc #>> '{application_id}') ilike '%12398%'

union all

select id, 40 as rank
from applications
where (doc #>> '{organization.code}') ilike '%12398%'

union all

select id, 50 as rank
from applications
where (doc #>> '{comment}') ilike '%12398%'

limit 200;

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

┌──────────────────────────────────────┬──────┐
│                  id                  │ rank │
├──────────────────────────────────────┼──────┤
│ 00000000-0000-0000-0000-000000012398 │   10 │
│ 00000000-0000-0000-0000-000000812398 │   30 │
│ 00000000-0000-0000-0000-000000712398 │   30 │
│ 00000000-0000-0000-0000-000000312398 │   30 │
│ 00000000-0000-0000-0000-000000912398 │   30 │
│ 00000000-0000-0000-0000-000000012398 │   30 │
│ 00000000-0000-0000-0000-000000112398 │   30 │
│ 00000000-0000-0000-0000-000000123980 │   30 │
│ 00000000-0000-0000-0000-000000123981 │   30 │
│ 00000000-0000-0000-0000-000000123982 │   30 │
│ 00000000-0000-0000-0000-000000123983 │   30 │
│ 00000000-0000-0000-0000-000000123984 │   30 │
│ 00000000-0000-0000-0000-000000123985 │   30 │
│ 00000000-0000-0000-0000-000000123986 │   30 │
│ 00000000-0000-0000-0000-000000123987 │   30 │
│ 00000000-0000-0000-0000-000000123988 │   30 │
│ 00000000-0000-0000-0000-000000123989 │   30 │
│ 00000000-0000-0000-0000-000000212398 │   30 │
│ 00000000-0000-0000-0000-000000412398 │   30 │
│ 00000000-0000-0000-0000-000000512398 │   30 │
│ 00000000-0000-0000-0000-000000612398 │   30 │
│ 00000000-0000-0000-0000-000000812398 │   50 │
│ 00000000-0000-0000-0000-000000012398 │   50 │
│ 00000000-0000-0000-0000-000000112398 │   50 │
│ 00000000-0000-0000-0000-000000123980 │   50 │
│ 00000000-0000-0000-0000-000000123981 │   50 │
│ 00000000-0000-0000-0000-000000123982 │   50 │
│ 00000000-0000-0000-0000-000000123983 │   50 │

Замечания к UNION

Результат, что мы получили, заслуживает некоторых обсуждений. Во-первых, за счет ранга четко видны группы (слои), к которым относятся документы. В нашем случае они пришли из первой, третьей и пятой групп (ранги 10, 30 и 50), а второй и четвертый запрос ничего не нашли.

Во-вторых, записи следуют в том же порядке, в каком расположены запросы в UNION. Это случайность: порядок запросов в UNION не влияет на порядок финальных строк. В простейшем случае Postgres выполнит запросы по одному и объединит результат. Но если условия позволяют, запросы могут быть выполнены параллельно, и предсказать порядок строк невозможно. Первый слой может оказаться третьим, второй – первым, а иногда записи из разных запросов чередуются, как зубчики в замке-молнии.

Третье важное замечание – один и тот же документ может быть в разных слоях. Выше мы привели пример, где последовательность 12345 встречалась в коде заявки и комментарии. Если присмотреться, наша выборка тоже содержит повторы: документ 00000000-0000-0000-0000-000000012398 встречается в трех слоях с рангами 10, 30 и 50. Показать его трижды в выдаче значит запутать пользователей.

Из сказанного следует, что выборка (id, rank), прежде чем присоединять к ней документы, нуждается в обработке. Сперва удалим повторные документы с учетом их ранга: из записей с одинаковым id оставить ту, что имеет наименьший ранг. Например, если документ А встречается с рангами 10, 20 и 30, оставим только ранг 10. Затем, добившись уникальности документов, упорядочим их по рангу.

Последующая обработка

Задача решается разными способами. Один из них в том, чтобы вынести UNION в подзапрос или общее табличное выражение. Сгруппируем его по ключу документа (id), а рангу назначим агрегатную функцию MIN – наименьшее значение. Упорядочим по наименьшему рангу результат, и задача решена. Все вместе дает запрос (приведем в сокращении):

with
layers as (

  select id, 10 as rank
  from applications
  where (doc #>> '{application_id}') = '12398'

  union all

  select id, 20 as rank
  from applications
  where (doc #>> '{organization.code}') = '12398'

  union all

  select id, 30 as rank
  from applications
  where (doc #>> '{application_id}') ilike '%12398%'

  union all

  select id, 40 as rank
  from applications
  where (doc #>> '{organization.code}') ilike '%12398%'

  union all

  select id, 50 as rank
  from applications
  where (doc #>> '{comment}') ilike '%12398%'

)
select
    id, min(rank) as rank
from
    layers
group by id
order by 2;

Выражение order by 2 означает сортировку по второму столбцу, в нашем случае – минимальному рангу. Выполним запрос и убедимся, что дубликаты ушли и порядок записей верный:

┌──────────────────────────────────────┬──────┐
│                  id                  │ rank │
├──────────────────────────────────────┼──────┤
│ 00000000-0000-0000-0000-000000012398 │   10 │
│ 00000000-0000-0000-0000-000000112398 │   30 │
│ 00000000-0000-0000-0000-000000123980 │   30 │
│ 00000000-0000-0000-0000-000000123981 │   30 │
│ 00000000-0000-0000-0000-000000123982 │   30 │
│ 00000000-0000-0000-0000-000000123983 │   30 │
│ 00000000-0000-0000-0000-000000123984 │   30 │
│ 00000000-0000-0000-0000-000000123985 │   30 │
│ 00000000-0000-0000-0000-000000123986 │   30 │
│ 00000000-0000-0000-0000-000000123987 │   30 │
│ 00000000-0000-0000-0000-000000123988 │   30 │
│ 00000000-0000-0000-0000-000000123989 │   30 │
│ 00000000-0000-0000-0000-000000212398 │   30 │
│ 00000000-0000-0000-0000-000000312398 │   30 │
│ 00000000-0000-0000-0000-000000412398 │   30 │
│ 00000000-0000-0000-0000-000000512398 │   30 │
│ 00000000-0000-0000-0000-000000612398 │   30 │
│ 00000000-0000-0000-0000-000000712398 │   30 │
│ 00000000-0000-0000-0000-000000812398 │   30 │
│ 00000000-0000-0000-0000-000000912398 │   30 │
└──────────────────────────────────────┴──────┘

Обратите внимание, что записи из пятого слоя исчезли: все они встречались в слоях с рангом 10 или 30 и были исключены группировкой.

Теперь добавим к полученной выборке документы. Поместим ее в табличное выражение с именем grouped и свяжем с таблицей applications по полю id:

with
layers as (
  ...
),
grouped as (
  select
      id, min(rank) as rank
  from
      layers
  group by id
  order by 2
)
select
    g.id, a.doc
from grouped g
join applications a on g.id = a.id;

Полученный запрос и есть то, к чему мы стремились:

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

Подобные запросы полезно изображать схемой: так легче понять их устройство. Приведем схему для нашего запроса:

┌───────────────────────────────────────────────────────────────┐
│┌───────────────┐                                              │
││    id, 10     │──┐                                           │
│└───────────────┘  │                                           │
│                   │                                           │
│┌───────────────┐  │                                           │
││    id, 20     │──┤                                           │
│└───────────────┘  │   ┌──────────────────┐    ┌──────────────┐│
│                   │   │                  │    │              ││
│┌───────────────┐  │   │remove duplicates │    │    fetch     ││
││    id, 30     │──┼──▶│   sort by rank   │───▶│  documents   ││
│└───────────────┘  │   │                  │    │              ││
│                   │   └──────────────────┘    └──────────────┘│
│┌───────────────┐  │                                           │
││    id, 40     │──┤                                           │
│└───────────────┘  │                                           │
│                   │                                           │
│┌───────────────┐  │                                           │
││    id, 50     │──┘                                           │
│└───────────────┘                                              │
└───────────────────────────────────────────────────────────────┘

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

Замена UNION на FULL JOIN

Запрос можно переписать так, чтобы он не использовал UNION. Для этого результаты собирают не по вертикали, а по горизонтали при помощи FULL JOIN. Первый слой выступает точкой опоры, а последующие “цепляются” к результату, просматривая ключи слева в поисках первого отличного от NULL. Для ясности приведем схему:

┌─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┐
│   app.code =    │   org.code =    │ app.code ilike  │ org.code ilike  │  comment ilike  │
├────────┬────────┼────────┬────────┼────────┬────────┼────────┬────────┼────────┬────────┤
│   id   │  rank  │   id   │  rank  │   id   │  rank  │   id   │  rank  │   id   │  rank  │
├────────┴────────┼────────┼────────┼────────┴────────┼────────┴────────┼────────┴────────┤
                  │  1002  │   20   │
│                 ├────────┼────────┼────────┬────────┤                 │                 │
                  │  1003  │   20   │  1003  │   30   │
│                 ├────────┼────────┼────────┼────────┤                 │                 │
                  │  1004  │   20   │  1004  │   30   │
├────────┬────────┼────────┼────────┼────────┼────────┤                 │                 │
│  1005  │   10   │  1005  │   20   │  1005  │   30   │
├────────┼────────┼────────┴────────┼────────┼────────┤                 │                 │
│  1006  │   10   │                 │  1006  │   30   │
├────────┼────────┤                 ├────────┼────────┤                 │                 │
│  1007  │   10   │                 │  1007  │   30   │
├────────┼────────┤                 ├────────┴────────┤                 │                 │
│  1008  │   10   │
├────────┴────────┤                 │                 ├────────┬────────┤                 │
                                                      │  1009  │   40   │
│                 │                 │                 ├────────┴────────┼────────┬────────┤
                                                                        │  1010  │   50   │
└ ─ ─ ─ ─ ─ ─ ─ ─ ┴ ─ ─ ─ ─ ─ ─ ─ ─ ┴ ─ ─ ─ ─ ─ ─ ─ ─ ┴ ─ ─ ─ ─ ─ ─ ─ ─ ┴────────┴────────┘

Так выглядят слои, соединенные FULL JOIN по полю id. Видим, что в каждой строке есть хотя бы один ключ: полностью пустых строк получиться не может. Если строка пересекает более одного слоя, это значит, один и тот же документ нашелся в нескольких выборках.

Полученную матрицу нужно свернуть, то есть получить финальные ключ и ранг. Для обоих полей алгоритм одинаков: движемся слева направо и берем первое отличное от NULL значение. Поскольку ранги слоев нарастают тоже слева направо, первый непустой ранг будет минимальным. Вот что вернет описанный алгоритм:

┌────────┬────────┐
│   id   │  rank  │
├────────┼────────┤
│  1002  │   20   │
├────────┼────────┤
│  1003  │   20   │
├────────┼────────┤
│  1004  │   20   │
├────────┼────────┤
│  1005  │   10   │
├────────┼────────┤
│  1006  │   10   │
├────────┼────────┤
│  1007  │   10   │
├────────┼────────┤
│  1008  │   10   │
├────────┼────────┤
│  1009  │   40   │
├────────┼────────┤
│  1010  │   50   │
└────────┴────────┘

Полученную свертку сортируют по рангу. Результат готов к тому, чтобы присоединить документы и вернуть их клиенту.

┌────────┬────────┐
│   id   │  rank  │
├────────┼────────┤
│  1005  │   10   │
├────────┼────────┤
│  1006  │   10   │
├────────┼────────┤
│  1007  │   10   │
├────────┼────────┤
│  1008  │   10   │
├────────┼────────┤
│  1002  │   20   │
├────────┼────────┤
│  1003  │   20   │
├────────┼────────┤
│  1004  │   20   │
├────────┼────────┤
│  1009  │   40   │
├────────┼────────┤
│  1010  │   50   │
└────────┴────────┘

Приведем запрос, построенный по этой схеме:

with
matrix as (
  select
      coalesce(sub1.id, sub2.id, sub3.id, sub4.id, sub5.id) as id,
      coalesce(sub1.rank, sub2.rank, sub3.rank, sub4.rank, sub5.rank) as rank
  from (
      select id, 10 as rank
      from applications app
      where (doc #>> '{application_id}') = '12398'
  ) as sub1

  full join (
      select id, 20 as rank
      from applications
      where (doc #>> '{organization.code}') = '12398'
  ) as sub2 on coalesce(sub1.id) = sub2.id

  full join (
      select id, 30 as rank
      from applications
      where (doc #>> '{application_id}') ilike '%12398%'
  ) as sub3 on coalesce(sub1.id, sub2.id) = sub3.id

  full join (
      select id, 40 as rank
      from applications
      where (doc #>> '{organization.code}') ilike '%12398%'
  ) as sub4 on coalesce(sub1.id, sub2.id, sub3.id) = sub4.id

  full join (
      select id, 50 as rank
      from applications
      where (doc #>> '{comment}') ilike '%12398%'
  ) as sub5 on coalesce(sub1.id, sub2.id, sub3.id, sub4.id) = sub5.id

  order by 2
)
select
    matrix.id, app.doc
from
    matrix
join applications app
    on matrix.id = app.id;

В запросе часто встречается выражение coalesce. Напомним, что это не функция, а особая форма, которая принимает произвольное аргументы и возвращает первый отличный от NULL. Аргументы вычисляются лениво по мере того как Postgres перебирает их. Конструкция coalesce(sub1.id, sub2.id, sub3.id, ...) сканирует столбцы слева направо и возвращает первый не пустой. В случае с рангами форма coalesce(sub1.rank, sub2.rank, ...) работает как функция LEAST, потому что мы специально расположили ранги по нарастанию.

Какой именно способ предпочесть – по вертикали с UNION или горизонтали с FULL JOIN, – зависит от предпочтений. UNION несколько проще в понимании и удобстве: можно переставить слои местами, и это не повлияет на дальнейшие шаги. Для FULL JOIN это не так, потому что перестановка нарушит выражения coalesce, по которым мы соединяем слои. Текст ниже подразумевает, что мы остановили выбор на UNION.

Коротко о MapReduce

Поиск, что мы написали, отдаленно напоминает технику MapReduce. Согласно ей, поиск информации проходит в два этапа. На первом этапе (map – назначить, разметить) приложение собирает данные из разных источников. На втором этапе (reduce – свернуть, понизить) из каждого фрагмента берутся лучшие экземпляры. Вместе они образуют результат поиска.

MapReduce предполагает, что данные приходят не только из реляционных таблиц, но и вообще отовсюду, включая файлы, сетевые хранилища, сервисы. В нашей книге мы работаем с SQL и не можем выйти за пределы реляционной базы. Технически возможно обратиться из Postgres к другой базе данных (postgres_fdw) или HTTP-сервису (pgsql-http), однако такие трюки мы не рассматриваем.

Поиск в исторической таблице

Доработаем поиск так, чтобы наряду с таблицей applications он учитывал и другие. Так, в прошлой главе мы рассмотрели версии документов и таблицу history. Коротко рассмотрим, чем она может быть полезна.

Предположим, организация сменила название с “Acme Inc” на “Global Corp”. Пользователь, который еще об этом не знает, вводит “Acme” и ничего не находит – в таблице applications нет заявки с organization.short_name, равным Acme. Но если выполнить поиск в history, мы найдем версию документа с прежним названием. По полю pk мы присоединим актуальный документ, и он окажется в выдаче.

Задача сводится к тому, чтобы добавить в подзапрос layers новый слой. Его ранг еще ниже – 60, потому что исторические данные интересуют нас в последнюю очередь. Приведем запрос с учетом истории:

with
layers as (

  select id, 10 as rank
  from applications
  where (doc #>> '{application_id}') = '12398'

  union all

  select id, 20 as rank
  from applications
  where (doc #>> '{organization.code}') = '12398'

  union all

  select id, 30 as rank
  from applications
  where (doc #>> '{application_id}') ilike '%12398%'

  union all

  select id, 40 as rank
  from applications
  where (doc #>> '{organization.code}') ilike '%12398%'

  union all

  select id, 50 as rank
  from applications
  where (doc #>> '{comment}') ilike '%12398%'

  union all

  select pk, 60 as rank
  from history
  where
      entity = 'application'
  and created_at > now() - interval '1 week'
  and (doc #>> '{organization,short_name}') ilike '%12398%'
),
grouped as (
  select
      id, min(rank) as rank
  from
      layers
  group by id
  order by 2
)
select
    g.id, a.doc
from grouped g
join applications a on g.id = a.id;

Последний слой (ранг 60) интересен следующим. Во-первых, мы выбираем поле pk, а не id, потому что id – код версии, а нам нужен код документа (pk). Во-вторых, обратите внимание на фильтрацию по created_at. Поиск по всей истории будет дорогим и избыточным, поэтому ограничим его разумным диапазоном, например за последнюю неделю. Диапазон можно передавать параметром. Также учтите отбор по полю entity – историческая таблица хранит все сущности, и нам не хотелось бы искать что-либо, отличное от заявок.

Убедитесь, что исторический запрос попадает в индекс. Скопируйте часть select pk, 60 as rank..., предварите ее командой explain analyze и выполните c разными параметрами.

О быстродействии

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

Далее по тексту мы берем слово “быстрый” в кавычки. Этим мы подчеркиваем относительность термина, ведь на каждой машине один и тот же запрос ведет себя по-разному в зависимости от оборудования, настроек и объема данных. Под быстротой мы имеем в виду прогнозируемость и постоянство. Например, если поиск по номеру заявки занимает три миллисекунды, потому что опирается на индекс, то при добавлении еще миллиона записей время почти не увеличится. И наоборот: запрос, быстрый на небольшом числе записей, но без индекса, перестанет быть таковым с ростом данных.

Когда запускается поиск с UNION, выполняются SELECT-запросы слоев: точное равенство, ilike и другие. Если условие попадает в индекс, выборка производительна. Предполагается, что мы создали индексы для каждого слоя и все они “быстрые”. В UNION запросы могут выполняться параллельно – при условии, что это позволяет окружение и планировщик выбрал такой алгоритм. Из этих соображений можно сделать вывод, что часть UNION тоже “быстрая”.

Шаг, на котором удаляются дубли, включает группировку по ключу документа. Хотя группировка считается дорогой операцией, ее реальное время зависит от объема данных. Если предположить, что каждый слой UNION вернул в среднем пятьдесят записей, а всего слоев пять, записей окажется не более двухсот пятидесяти. Это немного, и даже на слабой машине их группировка недолгой.

Последний шаг, где мы присоединяем документы, тоже хорошо прогнозируется. Условие JOIN опирается на первичный ключ id таблицы applications, который индексирован. Соединение двухсот документов по ключам тоже сработает “быстро”. Итого – если каждый шаг “быстрый” (опирается на индекс), запросом можно пользоваться, не боясь деградации базы.

Привести полные планы запросов мы не сможем, потому что они слишком велики; ограничимся лишь финальными материками. На ноутбуке Macbook M4 Pro 48G поиск с UNION ALL занял в среднем 12 миллисекунд (Execution Time), cost верхнего узла равен 2951..4621. Запрос с FULL JOIN оказался эффективней: 3 миллисекунды (Execution Time), стоимость верхнего узла – 3795..4636. Полные планы вы найдете в репозитории с исходным кодом глав.

Дальнейшие улучшения

Изучив метрики, подумаем, как можно улучшить поиск. Одна из доработок в следующем: перед тем как выполнить запрос, проверьте поисковое выражение на разные критерии. Уже на этом этапе можно определить, что некоторые слои не понадобятся, и не включать их в построитель SQL.

Очевидный случай – пустая строка или содержащая только незначащие символы (пробелы, перенос строки, табуляция). Такие запросы не должны выполняться, потому что напрасно расходуют ресурсы. Другой вариант – проверка на определенные шаблоны, например, что номер заявки содержит только цифры. Если в поиск ввели что-то отличное от цифр, поиск по номеру будет заведомо пустым, и этот слой исключают из UNION. Обратная ситуация – имя пользователя: если на вход поступили только цифры, поиск по такому “имени” ничего не даст.

В главе про индексы мы упоминали, что триграммному индексу нужны хотя бы три символа. Иногда пользователь ищет заявку с коротким номером: 26 или 88. В такой ситуации триграммные слои не участвуют в запросе.

Другая доработка касается длины выборки. На текущий момент каждый слой UNION неограничен – мы получим столько записей, сколько подошло условию. Для точных совпадений это не проблема: мы получим одну или несколько строк. Однако неточные совпадения порой дают сотни записей. Например, для выражения 123 мы получим документы 551235, 9123, 123512 и так далее. Если предположить, что код заявки меняется от единицы до миллиона, то кодов, содержащих “123”, окажется много.

Сколько именно? Проверим следующим запросом:

select count(*)
from generate_series(1, 1000000) as _(x)
where x::text like '%123%'

-- 3999

По поиску “123” мы получим без одного четыре тысячи документов! Недостаток такого слоя в том, что он нарушает технику MapReduce. Согласно ей, из каждого слоя выбирается часть записей, а не все подряд. Клиенту будет неудобно просматривать столь длинную выдачу. Кроме того, неограниченная выборка может замедлить запрос даже с учетом индекса.

Ограничим каждый SELECT оператором LIMIT. Конкретное значение зависит от многих факторов и подбирается вручную; в случае автора им оказалось число 50. Приведем фрагмент запроса, где в каждый слой добавлен LIMIT:

with
layers as (

  select * from (
    select id, 10 as rank
    from applications
    where (doc #>> '{application_id}') = '12398'
    limit 50
  )

  union all

  select * from (
    select id, 20 as rank
    from applications
    where (doc #>> '{organization.code}') = '12398'
    limit 50
  )

Обратите внимание: мы обернули каждый SELECT в подзапрос и выбираем из него. Дело в том, что если добавить LIMIT 250 в конец UNION (250 мы получили, умножив 50 на число слоев), оператор действует на объединение в целом, а не слои. Мы словно говорим Postgres: выбери из нескольких запросов не более 250 записей, а в какой пропорции – решай сам. Может оказаться, что все записи пришли из одного слоя, а до остальных даже не дошло. Чтобы избежать диспропорции, каждый слой оборачивается в подзапрос с персональным LIMIT, в нашем случае 50.

Порой определенному слою делают исключение и выделяют больший LIMIT. Стремитесь к тому, чтобы основные показатели слоев (ранг и limit) хранились в настройках приложения и передавались параметрами.

Страничная навигация

Возможно, читатель задался вопросом: как организовать в поиске страничную навигацию (пагинацию)? Хотя технически это возможно, мы воздержимся от решения на страницах книги. Во-первых, оно требует деталей, которые уведут нас от темы. Во-вторых, прежде чем садиться за пагинацию, подумаем – нужна ли она вообще?

На первый взгляд ответ очевиден: разумеется да! В каждой поисковой системе есть навигатор, с помощью которого мы переходим на вторую, третью и другие страницы. Иной раз число страниц поражает воображение. Так, по слову “python” Гугл находит почти 400 миллионов ссылок (если точнее, 394,000,000). Если предположить, что одна страница вмещает десять ссылок, всего страниц окажется 40 миллионов. Одному человеку физически не под силу их разобрать.

Чем больше номер страницы, тем меньше людей ее посещают. Эта зависимость даже не линейна, а обратно экспоненциальна: с увеличением номера посещаемость падает в разы или даже на порядки. Как давно вы искали что-нибудь на седьмой странице Гугла? Как часто заходите так далеко?

Другой довод против пагинации – она раскрывает данные. Если из логов видно, что клиент перебирает страницы с первой по десятитысячную, очевидно, это бот, собирающий данные. Здесь поиск оказывает услугу злоумышленнику.

Мы подталкиваем читателя к следующей мысли. Вместо того, чтобы делить выдачу на страницы и предлагать клиентам листать ее, улучшайте качество поиска. Пусть клиент получит не миллион, а только сто записей, которые совпадают с его запросом. Если нужного документа нет, пусть клиент перефразирует запрос. Определите наиболее частые сценарии поиска и оптимизируйте их. Поговорите с клиентами: чего они ожидают от поиска, насколько довольны его результатом? Скорее всего, вы получите много замечаний, и все они будут связаны с точностью, а не размером выдачи.

Полнотекстовый поиск

Напоследок рассмотрим еще один вопрос, связанный с качеством поиска. До сих мы писали запросы с точным совпадением (=) и соответствием шаблону (ilike). Postgres предлагает полнотекстовый поиск с богатыми возможностями. Среди них — поддержка многих языков, включая русский, позиция слов, расстояние между ними, словари синонимов и многое другое.

Чтобы начать работу с поиском, не требуется расширений: все доступно по умолчанию. Однако желательно, чтобы перед этим разработчик изучил документацию. На сайте Postgres Pro она занимает одиннадцать разделов; каждый из них рассматривает свой аспект поиска с примерами.

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

Поиск в Postgres опирается на понятие “документ” — специальный вектор, полученный из текста. Просим не путать его с JSON-документом, о котором мы говорим всю книгу. Чтобы избежать путаницы, по возможности будем писать “поисковой документ” и “JSON-документ”.

Чтобы получить поисковой документ из обычного текста, его преобразуют следующим образом:

все символы приводятся к нижнему регистру.
Удаляются незначащие (стоп-) слова: союзы, предлоги, артикли (английские a, an, the, французские le, la).
Удаляются окончания слов, чтобы падеж и число не влияли на результат. Усеченные слова называют лексемами.
Каждая лексема знает позицию в исходном тексте. Это необходимо для расчета близости слов: чем она меньше, тем выше релевантность. Каждая лексема хранится в одном экземпляре. Если в тексте их несколько, перечислены все позиции.
Каждой лексеме можно назначить вес, который позже учитывается в ранге.

Для хранения поискового документа служит особый тип tsvector, а для запроса к нему – tsquery. В обоих случаях префикс ts_ означает text search. С него начинаются все типы и функции, имеющих отношение к поиску.

Чтобы получить документ из текста, вызовите функцию to_tsvector с указанием языка и произвольным текстом:

select to_tsvector('russian', 'Все животные равны, но некоторые животные равнее других');

Вот что окажется в векторе. Обратите внимание на изменения, что мы перечислили: регистр, предлоги, окончанния, повторы слов.

┌──────────────────────────────────────────────┐
│                 to_tsvector                  │
├──────────────────────────────────────────────┤
│ 'друг':8 'животн':2,6 'некотор':5 'равн':3,7 │
└──────────────────────────────────────────────┘

Функцию to_tsquery можно вызвать без языка (первого аргумента). В этом случае сработает язык по умолчанию; узнать его можно командой show:

show default_text_search_config;
 default_text_search_config
----------------------------
 pg_catalog.english

Если применить к тексту не тот язык, это резко ухудшит его обработку. Вызовем to_tsquery еще раз с языком по умолчанию (английским):

select to_tsvector('Все животные равны, но некоторые животные равнее других');

┌─────────────────────────────────────────────────────────────────────────────┐
│                                 to_tsvector                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 'все':1 'других':8 'животные':2,6 'некоторые':5 'но':4 'равнее':7 'равны':3 │
└─────────────────────────────────────────────────────────────────────────────┘

Английский язык не исключил союз “но” – с его точки зрения это обычное слово. Предлоги, союзы и артикли встречаются в тексте часто и, если не удалить их, приводят к ложным совпадениям. Слово “животные” не потеряло окончание: если подать на вход слово “животное”, совпадения не будет. Также русская грамматика приводит букву “ё” к “е”. Хотя этот случай не входит в наш пример, он тоже важен для поиска.

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

Объект запроса

Когда мы получили поисковой документ, его проверяют на соответствие запросу. Запрос – это сущность с типом tsquery. Из него тоже удаляются союзы, артикли и незначащие слова; у слов отбрасываются окончания. Вместе это приводит к лучшему совпадению запроса с вектором.

В общем случае запрос получают функцией to_tsquery. Ее первый необязательный документ – язык, который, как и в случае с tsvector, оказывает решающее значение на разбор слов.

Важно, что в запросе не может быть пробелов между словами. Вместо них стоят операторы, которые означают, как обрабатывать слова. Наиболее частый оператор & означает, что слова встречаются в документе без учета порядка. Оператор <-> строже: совпадение случится, если в поисковом документе слова идут в том же порядке, что и в запросе. Палочка | означает либо одно слово, либо другое.

select to_tsquery('russian', 'все & животные & равны');

┌───────────────────┐
│    to_tsquery     │
├───────────────────┤
│ 'животн' & 'равн' │
└───────────────────┘

Для получения tsquery служит целое семейство функций, каждая со своей особенностью. Среди прочих нас интересует plainto_tsquery, которая подходит под самый востребованный случай. Она принимает обычный текст, находит лексемы и объединяет их оператором &.

select plainto_tsquery('russian', 'все животные равны');

┌───────────────────┐
│  plainto_tsquery  │
├───────────────────┤
│ 'животн' & 'равн' │
└───────────────────┘

Полученный запрос проверяет, что в документ содержит все указанные слова без учета порядка или расстояния.

Определение и хранение языка

Postgres не предлагает способа определить язык, и как это сделать – остается на ваше усмотрение. Один из способов в том, чтобы вызвать библиотеку langdetect на Python через расширение plpython3u. Приведем минимальный пример:

import langdetect
from langdetect import detect, detect_langs

text = "Все животные равны, но некоторые животные равнее других"

print(detect(text))
print(detect_langs(text))

# ru
# [ru:0.9999961866373268]

Функция detect возвращает наиболее вероятный язык, а detect_langs – их список с вероятностью каждого, если подходят несколько вариантов.

Для Perl написано семейство модулей Lingua, один из которых служит для определения текста. Для вызова кода на Perl установите расширение plperl. Автор уверен, что после главы об интерпретаторах читатель справится с этой задачей.

Значения tsvector и tsquery должны быть произведены с одинаковым языком. Как мы уже видели, в противном случае для одинаковых слов получаются разные лексемы, и качество поиска снижается.

Язык, что мы передаем в функции, на самом деле не строка, а более сложный тип — regconfig. Список поддерживаемых языков мы узнаем запросом:

select cfgname from pg_ts_config;

┌────────────┐
│  cfgname   │
├────────────┤
│ simple     │
│ arabic     │
│ armenian   │
│ basque     │
│ catalan    │
│ danish     │
│ dutch      │
│ english    │
│ finnish    │
│ french     │
│ german     │
│ greek      │
│ hindi      │
│ hungarian  │
│ indonesian │
│ irish      │
│ italian    │
│ lithuanian │
│ nepali     │
│ norwegian  │
│ portuguese │
│ romanian   │
│ russian    │
│ serbian    │
│ spanish    │
│ swedish    │
│ tamil      │
│ turkish    │
│ yiddish    │
└────────────┘

Упоминания заслуживает первый элемент simple — самый простой, примитивный анализатор текста. Постарайтесь не использовать его в боевом запуске.

Один из способов добиться того, чтобы язык tsvector и tsquery был одинаков – хранить его в отдельной колонке:

alter table applications add column lang regconfig null;

update applications set lang = 'english';

Приведем функцию, которая по документу определяет язык. В ней поле comment передается в функцию detect модуля langdetect. Далее ответ detect приводится к одному из значений regconfig силами промежуточного словаря. Для краткости мы добавили в него только три элемента:

create or replace function app_detect_lang(doc jsonb)
returns regconfig
transform for type jsonb
language plpython3u immutable strict parallel safe as $$
    from langdetect import detect
    lang = detect(doc["comment"])

    mapping = {
        "en": "english",
        "ru": "russian",
        "fr": "french"
    }

    if lang in mapping:
        return mapping[lang]
    else:
        return 'simple'
$$;

Определение языка можно вынести в фоновую задачу pg_cron. Задача обновляет те документы, где язык еще не определен:

update applications
set lang = app_detect_lang(doc)
where lang is null;

Полнотекстовый слой в UNION

Теперь когда у нас есть поисковой документ и запрос, проверим их на соответствие. Для этого служит оператор @@, с которым мы познакомились в главе про JSON Path. У него схожая семантика: документ слева проверяется на соответствие запросу справа. Оператор возвращает истину или ложь:

select to_tsvector('russian', 'Все животные равны, но некоторые животные равнее других')
    @@ plainto_tsquery('russian', 'животные равны') as res;

┌─────┐
│ res │
├─────┤
│ t   │
└─────┘

Убедимся, что из-за неверного языка совпадения не будет:

select to_tsvector('russian', 'Все животные равны, но некоторые животные равнее других')
    @@ plainto_tsquery('english', 'животные равны') as res;

┌─────┐
│ res │
├─────┤
│ f   │
└─────┘

Встроим полнотекстовый поиск в наш запрос. Предположим, в комментариях к заявкам пишут большие сообщения. Ранее мы использовали триграммный поиск, но его стало не хватать. Идея в том, чтобы заменить этот слой в операторе UNION на другой, основанный на tsvector. Новый слой выглядит так:

  select * from (
    select id, 50 as rank
    from applications
    where to_tsvector('english', doc->>'comment') @@ to_tsquery('english', '12398')
    limit 50
  ) as sub5

Без индекса полнотекстовый поиск будет медленным. Объявите его следующим образом:

create index idx_application_comment_tsvector
on applications
using gin (to_tsvector('english', doc->>'comment'));

Обратите внимание, что индекс зависит от языка, в нашем случае – английского. В запросе с другим языком индекс не будет использоваться. Поэтому повторим: необходимо знать язык документа заранее, в идеале быстро вычислять его или хранить в колонке. В промышленном запуске значение 'english' заменяют на колонку lang, где хранится язык.

Оптимизации и доработки

К полнотекстовому поиску применяются все оптимизации, что мы рассмотрели для триграммного. Можно индексировать не одно поле, а несколько за счет конкатенации строк. Объединяет строки оператор || или функция concat_ws:

where to_tsvector(lang, concat_ws(
    ', ',
    doc #>> '{comment}',
    doc #>> '{description}',
    doc #>> '{path,to,field}'
)) @@ plainto_tsquery(lang, '12398')

Логику, которая вычисляет tsvector, лучше поместить в функцию и построить по ней индекс. Тем самым достигается изоляция и снижение копирования. Функция:

create or replace function app_tsvector(doc jsonb, lang regconfig)
returns tsvector
language sql immutable strict parallel safe
return ...;

Индекс:

create index idx_application_comment_tsvector
on applications
using gin (app_tsvector(doc, lang));

Поиск:

select id, doc from applications
where app_tsvector(doc, lang) @@ <query>

Поисковой вектор можно вынести в вычисляемый столбец. При обновлении документа перестроится и вектор:

alter table applications
add column _ts_vect tsvector generated always
as (app_tsvector(doc, lang)) stored;

select id, doc from applications
where _ts_vect @@ <query>

Еще одна оптимизация: вынести вектор в отдельную таблицу по принципу “один к одному”:

create table applications_tsvector (
    app_id uuid primary key references applications(id),
    tsvect tsvector not null
);

Чтобы найти документ, сперва мы фильтруем таблицу applications_tsvector по полю tsvect, а затем JOIN-им документ по app_id. Это позволяет индексировать документ, не затрагивая таблицу applications. Тем самым достигается разделение ответственности: сущности – отдельно, поисковой индекс – отдельно.

Когда вектор находится в отдельной таблице, можно индексировать документы отложенно. Сперва документ пишется только в applications, чтобы его индексирование не замедляло вставку. Затем фоновая задача заполняет applications_tsvector для этого документа. Если мы обнаружили, что вектор можно улучшить (об этом ниже), мы пересчитаем его, не затрагивая таблицу applications.

Вектор можно улучшить по многим критериям. Один из них в том, что иногда документ содержит фрагменты на разных языках, например основная часть изложена на русском, а цитаты – на английском. Предположим, мы написали скрипт, который делит документ на языковые блоки. Для каждого блока вычисляется tsvector. Полученные векторы объединяются оператором || (“палочки”), который порождает новый вектор. В нем окажутся все уникальные лексемы, разобранные соответствующим языком. Такой вектор обслуживает запросы на русском и английском без потери качества.

Давайте получим вектор из двух других: русского и английского.

select to_tsvector(
    'russian',
    'Все животные равны но некоторые животные равнее других'
) || to_tsvector(
    'english',
    'All animals are equal, but some animals are more equal than others'
) as vec;

┌────────────────────────────────────────────────────────────────────────────────────┐
│                                        vec                                         │
├────────────────────────────────────────────────────────────────────────────────────┤
│ 'anim':10,15 'equal':12,18 'other':20 'друг':8 'животн':2,6 'некотор':5 'равн':3,7 │
└────────────────────────────────────────────────────────────────────────────────────┘

Убедимся, что запросы на разных языках ему соответствуют (<res> означает вектор из прошлого примера):

select <res> @@ plainto_tsquery('russian', 'животные равны') as res;
-- true

select <res> @@ plainto_tsquery('english', 'animal equal') as res;
-- false

Другие возможные улучшения – подключить словари стоп-слов и синонимов, специфичных для вашей отрасли. Скажем, можно задать правило, чтобы при разборе текста слово “application” сокращалось до “app”. В этом случае запрос “app 123” найдет документ, где в исходном тексте встречается “Application 123”. То же самое касается слова “customer”, которое часто сокращают до “cust”. Устойчивые сочетания слов можно свести к аббревиатурам, например “country of risk” → “cor”, “know your customer” → “kyc” и другие. В разделе “Textsearch Dictionaries” документации Postgres эта техника описана подробно.

Еще больше сведений, связанных с поиском и релевантностью, вы найдете в англоязычной статье “Postgres as a search engine”. На Хабре доступен ее перевод на русский язык.

Заключение

Подведем итоги этой главы. Для поиска документов используют разные стратегии. В простом случае это точное совпадение с btree-индексом. Такой поиск быстр и потребляет мало ресурсов. Индексированное поле можно использовать для сортировки.

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

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

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

Работая над поиском, не спешите внедрять сторонние решения вроде ElasticSearch, OpenSearch и аналогов. Даже если их результаты точнее, затраты на ввод в эксплуатацию и поддержку окажутся значительными. Идите на этот шаг только если полностью исчерпали потенциал Postgres.

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

Глава 9. Версии и патчи

Tue, 18 Aug 2026 00:00:00 +0000

Главы

Содержание

В этой главе мы поговорим о том, как хранить разные версии одного документа. Обсудим, как организовать историческую таблицу, перемещать в нее документы и восстанавливать их. Также мы затронем тему разности JSON и познакомимся со стандартом JSON Patch (не путать с JSON Path).

Как мы упоминали, документ – это большая структура данных. Некоторые документы содержат сотни полей, и они часто меняются. При этом изменения фиксируют: создают резервные копии документов. Эти копии открывают полезные возможности, например:

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

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

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

Иногда версии хранятся неограниченно долго, а иногда их “подрезают”. Записи старше определенного срока считаются устаревшими, и спецальная задача переносит их в другое место, например хранилище S3. Очистка запускается регулярно по расписанию.

В особых случаях таблица хранит не сам документ, а разницу (патч) между прошлой и новой версиями. Имея патч, можно определить, какие именно поля документа затронули изменения. Эти и другие техники мы рассмотрим по тексту ниже.

Историческая таблица

Подумаем, какие поля понадобится для исторической таблицы. Кроме своего первичного ключа (id), таблица должна хранить первичный ключ документа. Назовем его pk или doc_id. Это поле не будет уникальным, потому что один и тот же документ может иметь несколько версий.

Поле doc типом jsonb хранит документ в состоянии до того, как к нему применили изменения.

Вспомогательное поле entity содержит имя таблицы, которой принадлежит документ: application, organization, user и так далее. С его помощью мы определим, на какую таблицу ссылается поле pk. В некоторых случаях (например, в триггерах) поле entity заполняется из локальной переменной.

Колонка operation пригодится, чтобы знать тип операции над документом: обновление или удаление. Будем хранить в ней значения “update” и “delete”. Как и в случае с entity, иногда имя операции доступно в переменной.

Необходимо поле, по которому различают версии в рамках одного документа. Наивный подход в том, чтобы использовать счетчик: версия 1, 2, 3 и так далее. Недостаток счетчиков в том, что произвести новое значение может только база данных. Приходится выполнять запрос вида “взять последнюю версию и добавить к ней единицу”, что неудобно и чревато конфликтами.

Кроме того, даже имея число, необходимы дата и время события. Поэтому желательно хранить версию как метку времени, потому что они упорядочены и могут быть произведены в приложении. Еще лучшим выбором будет UUID версии 7, который, как мы помним, совмещает время и упорядоченность и тоже же может быть сгенерирован в приложении.

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

С учетом сказанного таблица выглядит так:

create table history(
    id uuid not null default gen_random_uuid(),
    pk uuid not null,
    entity text not null,
    operation text not null,
    doc jsonb not null,
    created_at timestamptz not null default current_timestamp,
    user_id uuid null,
    comment text null
);

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

Подумаем теперь, за какой информацией мы будем обращаться к таблице history. В основном это два запроса:

Зная ключ документа и дату, определить актуальную на тот момент версию.
По ключу документа получить версии по убыванию даты, возможно за какой-то период.

Обе задачи решаются составным уникальным индексом (pk, created_at desc). Поскольку pk – лидирующий компонент, он сразу находит все версии документа. Они упорядочены по убыванию даты, и это полезно по двум критериям. Во-первых, чаще всего нас интересуют недавние версии, и они будут в начале выборки. Во-вторых, чтобы получить актуальную версию на дату, ограничим выборку по created_at и добавим limit 1. Уникальность индекса не позволит иметь несколько версий с одинаковой датой.

Демонстрация

Опробуем историческую таблицу в действии. Запишем в нее сто документов по десять версий на каждый, что в дает тысячу записей. Для этого подготовим функцию для генерации UUID:

create or replace function gen_uuid(x integer)
returns uuid
language sql immutable strict parallel safe
return to_char(x, 'FM00000000-0000-0000-0000-000000000000')::uuid;

Далее выполним запрос:

insert into history (pk, entity, operation, doc, created_at, user_id, comment)
select
    gen_uuid(x % 100),
    ((array['applications', 'organizations', 'users', 'events'])[ceil(random() * 4)]),
    ((array['update', 'delete'])[ceil(random() * 2)]),
    jsonb_build_object(
        'foo', x,
        'bar', format('some field %s', x),
        'test', 'hello'
    ),
    now() - interval '1 year' * random(),
    gen_random_uuid(),
    format('comment %s', x)
from
    generate_series(1, 1000) as seq(x);

Проверим случайные записи из середины таблицы:

select * from history
limit 10 offset 855;

┌─[ RECORD 1 ]────────────────────────────────────────────────────────┐
│ id         │ cc896171-b22e-443e-9f1e-d31cc1bf7d0b                   │
│ pk         │ 00000000-0000-0000-0000-000000000056                   │
│ entity     │ events                                                 │
│ operation  │ delete                                                 │
│ doc        │ {"bar": "some field 856", "foo": 856, "test": "hello"} │
│ created_at │ 2025-10-03 08:32:13.55007+03                           │
│ user_id    │ 6a7b7910-8baa-4cd3-8b7a-e2337e3430a8                   │
│ comment    │ comment 856                                            │
├─[ RECORD 2 ]────────────────────────────────────────────────────────┤
│ id         │ b878b211-11bf-4ce6-b3ab-dd23246cde6e                   │
│ pk         │ 00000000-0000-0000-0000-000000000057                   │
│ entity     │ organizations                                          │
│ operation  │ delete                                                 │
│ doc        │ {"bar": "some field 857", "foo": 857, "test": "hello"} │
│ created_at │ 2026-01-09 16:44:54.44607+03                           │
│ user_id    │ 2bec5043-f61e-4dfe-97ad-75fc95588174                   │
│ comment    │ comment 857                                            │
├─[ RECORD 3 ]────────────────────────────────────────────────────────┤
│ id         │ c92ee4a1-f634-4d94-bf59-0b9e727c17c5                   │
│ pk         │ 00000000-0000-0000-0000-000000000058                   │
│ entity     │ events                                                 │
│ operation  │ delete                                                 │
│ doc        │ {"bar": "some field 858", "foo": 858, "test": "hello"} │
│ created_at │ 2026-03-15 23:42:29.06367+03                           │
│ user_id    │ baa57871-0134-4b66-8c73-bfa6772f2b84                   │
│ comment    │ comment 858                                            │
├─[ RECORD 4 ]────────────────────────────────────────────────────────┤

Убедимся, что конкретный документ содержит десять версий:

select count(*) from history
where pk = '00000000-0000-0000-0000-000000000056';

┌───────┐
│ count │
├───────┤
│    10 │
└───────┘

Добавим составной индекс:

create unique index idx_history_pg_created_at
on history (pk, created_at desc);

Следующий запрос вернет версии документа по убыванию даты. Для краткости мы выбираем только ключ и дату:

select id, created_at from history
where pk = '00000000-0000-0000-0000-000000000056'
order by created_at desc;

┌──────────────────────────────────────┬──────────────────────────────┐
│                  id                  │          created_at          │
├──────────────────────────────────────┼──────────────────────────────┤
│ 13aad2e6-dc8d-4506-a502-4a906f5098ae │ 2026-05-25 13:51:35.42847+03 │
│ 61e69328-cf7d-4c08-b1e4-4348ec90a355 │ 2026-03-06 13:49:14.76927+03 │
│ 2114a3bd-8227-4fc2-8d19-792b67efb24c │ 2026-02-28 22:41:54.82047+03 │
│ 41e96a49-dddc-45c2-acec-440476fcbae7 │ 2026-01-26 15:56:18.70527+03 │
│ 9d0bb1e6-31a5-4c15-b860-56ca36bb2bf1 │ 2026-01-03 04:48:32.26047+03 │
│ 44c8ddf0-0a24-4f98-b05f-7cd920bf06f0 │ 2025-11-27 12:14:12.45567+03 │
│ af7004de-ac56-4263-818f-b1de9d07dcaf │ 2025-11-08 01:02:17.17887+03 │
│ cc896171-b22e-443e-9f1e-d31cc1bf7d0b │ 2025-10-03 08:32:13.55007+03 │
│ 2e903e63-65e8-4b78-89f2-938415d5e762 │ 2025-09-20 21:43:27.49887+03 │
│ 8b6d1d09-568e-481a-a96f-a8e3cd9626d7 │ 2025-07-19 18:00:57.48927+03 │
└──────────────────────────────────────┴──────────────────────────────┘

Последнюю версию мы получим, снабдив запрос выражением LIMIT 1:

select id, created_at from history
where pk = '00000000-0000-0000-0000-000000000056'
order by created_at desc
limit 1;

┌──────────────────────────────────────┬──────────────────────────────┐
│                  id                  │          created_at          │
├──────────────────────────────────────┼──────────────────────────────┤
│ 13aad2e6-dc8d-4506-a502-4a906f5098ae │ 2026-05-25 13:51:35.42847+03 │
└──────────────────────────────────────┴──────────────────────────────┘

Актуальную версию на дату мы получим, ограничив поле created_at параметром:

select id, created_at from history
where pk = '00000000-0000-0000-0000-000000000056'
    and created_at <= '2025-11-08 00:00:00+03'::timestamptz
order by created_at desc
limit 1;

┌──────────────────────────────────────┬──────────────────────────────┐
│                  id                  │          created_at          │
├──────────────────────────────────────┼──────────────────────────────┤
│ cc896171-b22e-443e-9f1e-d31cc1bf7d0b │ 2025-10-03 08:32:13.55007+03 │
└──────────────────────────────────────┴──────────────────────────────┘

Если предварить запросы командой EXPLAIN, план подтвердит, что мы попали в индекс.

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

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

Уточним, что версию создают только обновлении или удалении документа. Это значит, мы заинтересованы в запросах UPDATE и DELETE. При создании документа (INSERT) порождать версию бессмысленно: она будет точной копией документа.

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

Хотя автор не поощряет триггеры, наше первое решение будет основано на них.

Версии на триггерах

Чтобы при обновлении и удалении заявки в таблице history появлялась версия документа, проделаем следующее. Сперва подготовим триггерную функцию, которая выполняет вставку в history. Триггерные функции отличаются от обычных тем, что им доступны переменные OLD, NEW, TG_OP и другие. OLD и NEW Содержат прежнюю и новую версии строки, связанной с событием. TG_OP хранит имя операции: UPDATE или DELETE. Функция:

create or replace function fn_applications_history()
returns trigger as $$
begin
    insert into history(pk, entity, operation, doc, created_at)
    values (
        OLD.id,
        'applications',
        TG_OP,
        old.doc,
        current_timestamp
    );
    return OLD;
end;
$$ language plpgsql;

Команда create trigger связывает таблицу, событие и функцию, которую следует вызывать. Вызовем команду дважды для обновления и удаления. Мы заинтересованы в прошлой версии документа (до события), поэтому указываем before delete/update:

create trigger trg_application_before_delete
before delete on applications
for each row execute function fn_applications_history();

create trigger trg_application_before_update
before update on applications
for each row execute function fn_applications_history();

Обновим одну из заявок и проверим таблицу версий:

update applications
set doc['extra'] = to_jsonb(42)
where id = '00000000-0000-0000-0000-000000123999';

select
    id,
    pk,
    entity,
    operation,
    created_at,
    jsonb_pretty(doc) as doc
from history where pk = '00000000-0000-0000-0000-000000123999';

┌─[ RECORD 1 ]───────────────────────────────────────────────────────────────────┐
│ id         │ 009cc4ce-ea6b-4ea1-87b1-bed7825c8781                              │
│ pk         │ 00000000-0000-0000-0000-000000123999                              │
│ entity     │ applications                                                      │
│ operation  │ UPDATE                                                            │
│ created_at │ 2026-06-21 15:52:54.03302+03                                      │
│ doc        │ {                                                                ↵│
│            │     "id": "00000000-0000-0000-0000-000000123999",                ↵│
│            │     "status": "approved",                                        ↵│
│            │     "amounts": [                                                 ↵│
│            │         {                                                        ↵│
│            │             "amount": 41513124,                                  ↵│
│            │             "period": {                                          ↵│
│            │                 "d": 4,                                          ↵│
│            │                 "m": 8,                                          ↵│
│            │                 "w": 7,                                          ↵│
│            │                 "y": 1                                           ↵│
│            │             },                                                   ↵│
│            │             "currency": "USD"                                    ↵│

Видим, что версия с таким ключом появилась. То же самое с удалением: перед тем как запись исчезнет из основной таблицы, ее копия окажется в архивной таблице. Быстрая проверка:

delete from applications
where id = '00000000-0000-0000-0000-000000012345';

select
    id,
    pk,
    entity,
    operation,
    created_at,
    jsonb_pretty(doc) as doc
from history where pk = '00000000-0000-0000-0000-000000012345';

┌─[ RECORD 1 ]───────────────────────────────────────────────────────────────────┐
│ id         │ e0437f5d-19b6-4850-a2ae-51b21e626a0e                              │
│ pk         │ 00000000-0000-0000-0000-000000012345                              │
│ entity     │ applications                                                      │
│ operation  │ DELETE                                                            │
│ created_at │ 2026-06-21 15:48:55.118652+03                                     │
│ doc        │ {                                                                ↵│
│            │     "id": "00000000-0000-0000-0000-000000012345",                ↵│
│            │     "status": "archived",                                        ↵│
│            │     "amounts": [                                                 ↵│
│            │         {                                                        ↵│
│            │             "amount": 40528181,                                  ↵│
│            │             "period": {                                          ↵│
│            │                 "d": 7,                                          ↵│
│            │                 "m": 7,                                          ↵│

В целом задача выполнена: версии создаются автоматически, и теперь мы обсудим детали.

Доводы против триггеров

Выше мы упомянули, что, возможно, триггеры – не лучшее решение для версий. Дело в том, что триггеры слишком буквальны: они выполняются строго на все операции UPDATE и DELETE. У этой строгости недостаток: она не допускает исключений, а порой они необходимы. Например, при изменении некоторых полей создавать версии не нужно. Также они не требуются в служебных миграциях: исправлении дат, часовых поясов, корректировки ссылок. Наоборот, будет хуже, если мы исправили миллион документов и получили лишний миллион версий.

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

Можно временно отключить триггеры для тех тестов, которые в них не нуждаются. Для этого служит команда alter table ... disable trigger и ее обратное действие enable. Эти запросы помещают в фикстуру, которая выполняется однажды для блока тестов:

alter table applications disable trigger trg_application_before_delete;
/* run all tests */
alter table applications disable trigger trg_application_before_delete;

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

Еще один довод не использовать триггеры в том, что некоторые документы меняются слишком часто. Поминутные версий избыточны и вдобавок мешают пользователям: им трудно отличить важное изменение от косметического. Скорее всего, вас попросят сделать так, чтобы версия сохранялась не чаще чем раз в десять минут и около. Перед тем как записать новую версию, нужно узнать дату последней и рассчитать разницу во времени. Если она меньше порога, версию не создавать.

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

Версии в приложении

Другое возможное решение – поручить создание версий приложению. Если оно написано на Python, Java и другом высокоуровневом языке, скорее всего для работы с базой используется ORM. Почти все ORM поддерживают события, которые вызываются до или после операции над сущностью. В зависимости от языка они называются сигналами, хуками или иначе, но принцип одинаков.

Идея в том, чтобы назначить модели событие before update или before delete, а в обработчике записать документ в историческую таблицу. Приведем пример для ORM из фреймворка Django:

from django.db.models.signals import pre_save
from django.dispatch import receiver

from project.models import Application, History

@receiver(pre_save, sender=Application)
def save_history(sender, instance, **kwargs):
    if not instance.pk:
        return
    History.objects.create(
        pk=instance.id,
        entity='application',
        operation='UPDATE',
        doc=instance.doc
    )

Декоратор receiver объединяет событие pre_save (до записи в базу), модель Application и обработчик save_history. Последний сработает до того, как вызван метод .save() модели. Параметр instance содержит саму модель (экземпляр Application), которую мы намерены изменить. Если она новая (первичный ключ не заполнен), версия не создается.

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

По аналогии устроена реакция на удаление модели: разница лишь в типе сигнала (pre_delete).

Недостаток сигналов в том, что они работают только для одного экземпляра модели. При пакетных операциях (bulk_update, bulk_delete) они не вызываются. Кроме того, сигналы выполняются силами приложения, и база данных ничего не знает о них. Если подключиться к базе из другого фреймворка, сигналы первого не будут работать.

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

Версии в Postgres

Опишем удаление документа на SQL. Это подготовленный оператор с одним параметром – ключом документа. В нем две операции: удаление из основной таблицы и вставка в историческую. Обе операции выполняются атомарно, им доступен один и тот же снимок данных.

prepare delete_application as
with
OLD as (
    delete from applications where id = $1::uuid
    returning *
)
insert into history(pk, entity, operation, doc, created_at)
select
    OLD.id,
    'applications',
    'DELETE',
    old.doc,
    current_timestamp
from
    OLD;

Сперва запрос с псевдонимом OLD удаляет документ из основной таблицы, при этом удаленные строки возвращаются. В главном запросе OLD выступает источником данных: строки из него вставляются в таблицу версий. Данные словно перетекают из одной таблицы в другую. Процесс происходит атомарно и без нашего участия: клиент ничего не передает через себя, а только командует.

Убедимся, что вызов оператора порождает копии:

execute delete_application('00000000-0000-0000-0000-000000100999'::uuid);

select id from applications
where id = '00000000-0000-0000-0000-000000100999';
-- (0 rows)

В таблице заявок таковой больше нет. Документ переехал в history:

select
    id,
    pk,
    entity,
    operation,
    created_at,
    jsonb_pretty(doc) as doc
from history where pk = '00000000-0000-0000-0000-000000100999';

┌─[ RECORD 1 ]───────────────────────────────────────────────────────────────────┐
│ id         │ 78ce995b-c865-489c-8c24-0ab26d62caef                              │
│ pk         │ 00000000-0000-0000-0000-000000100999                              │
│ entity     │ applications                                                      │
│ operation  │ DELETE                                                            │
│ created_at │ 2026-06-21 16:16:23.510292+03                                     │
│ doc        │ {                                                                ↵│
│            │     "id": "00000000-0000-0000-0000-000000100999",                ↵│
│            │     "status": "archived",                                        ↵│
│            │     "amounts": [                                                 ↵│
│            │         {                                                        ↵│
│            │             "amount": 11520867,                                  ↵│
│            │             "period": {                                          ↵│
│            │                 "d": 2,                                          ↵│
│            │                 "m": 8,                                          ↵│
│            │                 "w": 6,                                          ↵│
│            │                 "y": 1                                           ↵│
│            │             },                                                   ↵│
│            │             "currency": "EUR"                                    ↵│

Подчеркнем, что логика не зависит от того, из какого языка или фреймворка обращается клиент.

Обновление документа несколько сложнее. Сначала документ копируют в таблицу версий, а затем обновляют. Оператор update_application ниже ожидает два параметра: ключ документа $1::uuid и его тело $2::jsonb:

prepare update_application as
with
OLD as (
    select * from applications
    where id = $1
),
NEW as (
    update applications
    set doc = $2::jsonb
    where id = $1::uuid
    returning *
)
insert into history(pk, entity, operation, doc, created_at)
select
    OLD.id,
    'applications',
    'UPDATE',
    OLD.doc,
    current_timestamp
from
    OLD;

Очевидны три этапа запроса:

OLD читает прежний документ;
NEW обновляет текущий;
insert записывает OLD в историческую таблицу.

Обновим одну из заявок и убедимся, что в таблице applications ее новая версия:

execute update_application(
    '00000000-0000-0000-0000-000000100321'::uuid,
    $$
{
    "application_id": 100321,
    "some_field": "test"
}
    $$::jsonb
);

select doc from applications
where id = '00000000-0000-0000-0000-000000100321';

┌─[ RECORD 1 ]───────────────────────────────────────────┐
│ doc │ {"some_field": "test", "application_id": 100321} │
└─────┴──────────────────────────────────────────────────┘

А исторической таблице – прежняя:

select
    id,
    pk,
    entity,
    operation,
    created_at,
    jsonb_pretty(doc) as doc
from history where pk = '00000000-0000-0000-0000-000000100321';

┌─[ RECORD 1 ]───────────────────────────────────────────────────────────────────┐
│ id         │ 47e6cdba-e1fe-4320-acdb-ef193ef7f3e6                              │
│ pk         │ 00000000-0000-0000-0000-000000100321                              │
│ entity     │ applications                                                      │
│ operation  │ UPDATE                                                            │
│ created_at │ 2026-06-21 16:27:53.384049+03                                     │
│ doc        │ {                                                                ↵│
│            │     "id": "00000000-0000-0000-0000-000000100321",                ↵│
│            │     "status": "archived",                                        ↵│
│            │     "amounts": [                                                 ↵│
│            │         {                                                        ↵│
│            │             "amount": 50222648,                                  ↵│
│            │             "period": {                                          ↵│

Ограничение по времени

Усложним требования: предположим, версию документа нужно создавать не чаще чем раз пять минут. Изучите новый код, а ниже мы разберем его:

prepare update_application_throttled as
with
upsert as (
    insert into applications(id, doc)
    values ($1::uuid, $2::jsonb)
    on conflict (id) do update set
    doc = excluded.DOC,
    updated_at = now()
    returning NEW.id, OLD.doc as doc_old
)
insert into history(pk, entity, operation, doc, created_at)
select
    id,
    'applications',
    'UPDATE',
    doc_old,
    current_timestamp
from
    upsert
where
        doc_old is not null
    and not exists(
      select id from history
      where
          pk = upsert.id
          and created_at > now() - interval '1 minute'
);

Ключевая деталь кроется в самом конце в выражении not exists. Подзапрос ищет в исторической таблице запись таким же ключом и датой создания позже порога. Если запись нашлась, not exists вернет ложь. В результате insert получит пустой набор записей, и версия не будет создана.

Еще одно улучшение кроется в части upsert. Как ясно из названия, она не только обновляет документ, но и создает в случае отсутствия. При этом возвращается прежнее значение документа – поле OLD.doc под именем doc_old. За счет него мы определим тип события: вставку или обновление. Значение doc_old помещается в историческую таблицу, если оно не пустое. В противном случае документ был создан, и порождать версию нет смысла.

Заметим, что в выражении on conflict переменные OLD и NEW доступны с версии 18. Для младших версий мы бы переписали запрос так, чтобы OLD был подзапросом:

with
OLD as (
    select * from applications
    where id = $1
)

Теперь проверим наш код. Для начала вставим простейший документ {"foo": "1"}. Оператор вернул INSERT 0 0, что означает, что вставка в историческую таблицу не состоялась. Это ожидаемое поведение, потому что для нового документа версия не создается.

execute update_application_throttled(
    '00000000-0000-0000-0000-000010123123'::uuid,
    $$
{
    "foo": "1"
}
    $$::jsonb
);
-- INSERT 0 0

Обновим тот же документ и увидим INSERT 0 1 – версия создана, потому что в пределах пяти минут не нашлось других версий.

execute update_application_throttled(
    '00000000-0000-0000-0000-000010123123'::uuid,
    $$
{
    "foo": "2"
}
    $$::jsonb
);
-- INSERT 0 1

Если обновить документ еще раз без ожидания, версия создана не будет:

execute update_application_throttled(
    '00000000-0000-0000-0000-000010123123'::uuid,
    $$
{
    "foo": "3"
}
    $$::jsonb
);
-- INSERT 0 0

Проверим таблицы: в application хранится текущий документ {"foo": "3"}, а в history – версия {"foo": "1"}. Версию {"foo": "2"} мы пропустили, потому что с момента {"foo": "1"} прошло меньше пяти минут.

table applications;
┌─[ RECORD 1 ]──────────────────────────────────────┐
│ id         │ 00000000-0000-0000-0000-000010123123 │
│ doc        │ {"foo": "3"}                         │
│ created_at │ 2026-08-18 09:32:46.966243+03        │
│ updated_at │ 2026-08-18 09:33:00.341051+03        │
└────────────┴──────────────────────────────────────┘

table history;
┌─[ RECORD 1 ]──────────────────────────────────────┐
│ id         │ 8e6b2261-76b1-4aa2-8e4f-5771faaf1e8f │
│ pk         │ 00000000-0000-0000-0000-000010123123 │
│ entity     │ applications                         │
│ operation  │ UPDATE                               │
│ doc        │ {"foo": "1"}                         │
│ created_at │ 2026-08-18 09:32:54.304452+03        │
│ user_id    │ <null>                               │
│ comment    │ <null>                               │
└────────────┴──────────────────────────────────────┘

Подождем 5 минут и обновим документ еще раз:

execute update_application_throttled(
    '00000000-0000-0000-0000-000010123123'::uuid,
    $$
{
    "foo": "4"
}
    $$::jsonb
);
-- INSERT 0 1

На этот раз в исторической таблице окажется версия {"foo": "3"}:

table history;
┌─[ RECORD 1 ]──────────────────────────────────────┐
│ id         │ 8e6b2261-76b1-4aa2-8e4f-5771faaf1e8f │
│ pk         │ 00000000-0000-0000-0000-000010123123 │
│ entity     │ applications                         │
│ operation  │ UPDATE                               │
│ doc        │ {"foo": "1"}                         │
│ created_at │ 2026-08-18 09:32:54.304452+03        │
│ user_id    │ <null>                               │
│ comment    │ <null>                               │
├─[ RECORD 2 ]──────────────────────────────────────┤
│ id         │ 5fa063d6-5e43-4cb3-b1ef-8d12d82657fa │
│ pk         │ 00000000-0000-0000-0000-000010123123 │
│ entity     │ applications                         │
│ operation  │ UPDATE                               │
│ doc        │ {"foo": "3"}                         │
│ created_at │ 2026-08-18 09:44:15.368447+03        │
│ user_id    │ <null>                               │
│ comment    │ <null>                               │
└────────────┴──────────────────────────────────────┘

Временной порог (число минут, часов и так далее) можно вынести в параметр или переменную сеанса.

Восстановление версии

Итак, у нас есть все, чтобы создавать версии документов. Однако мы не рассмотрели, как восстанавливать их. Без восстановления версии не имеют смысла, ведь иначе зачем создавать их?

Восстановление может быть устроено по-разному. Наш алгоритм ожидает ключ документа и дату версии. Его шаги следующе:

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

Получаются две перестановки: из главной таблицы в историческую и наоборот. Приведем подготовленный оператор restore_application, выполняющий эти действия. Ключ документа передается первым параметром ($1::uuid), версия – вторым ($2::timestamptz).

prepare restore_application as
with
del_current_doc as (
    delete from applications where id = $1::uuid
    returning *
),
create_version as (
    insert into history(pk, entity, operation, doc, created_at)
    select
        id,
        'applications',
        'RESTORE',
        doc,
        current_timestamp
    from
        del_current_doc
),
delete_version as (
    delete from history
    where
            pk = $1::uuid
        and created_at = $2::timestamptz
    returning *
)
insert into applications (id, doc, updated_at)
select
    id, doc, current_timestamp
from
    delete_version;

Если вызвать оператор для одной из версий, сработают указанные перестановки. Для экономии места мы опустим демонстрацию; предлагаем читателю опробовать ее на документе {"foo": "4"} из прошлого параграфа.

Архивация версий

Не всегда версии документа хранятся неограниченно долго. По истечении срока они признаются неактуальными: к ним все равно нельзя вернуться, потому что система не сможет их обработать. Иногда версии устаревают настолько, что противоречат текущему законодательству. В иных случаях исторические данные удаляют с целью безопасности.

Архивация включает несколько шагов:

выбрать документы старше определенного срока;
записать их в файл, сжать и передать в долгосрочное хранилище;
удалить из базы обработанные документы.

Задача выполняется регулярно, например раз в месяц.

Архивация решается разными способами, в том числе силами Java, Python и других языков. Ниже мы рассмотрим, как сделать это в Postgres без привлечения других технологий. Изучите следующий запрос:

copy (delete from history where created_at < now() - interval '1 year' returning *)
to program 'gzip > /path/to/history.csv.gzip'
with (format csv, header on);

Несмотря на краткость, он выполняет все указанное выше. Во-первых, версии, устаревшие на год, удаляются из таблицы (внутренний запрос DELETE). Данные, что он удалил, возвращаются оператором RETURNING. Выражение COPY приводит записи к формату CSV и передает процессу gzip, а тот сжимает результат в файл.

Вместо to program можно указать to stdout, и тогда данные получит клиент. Уточним, что в терминах Postgres под stdout понимается не стандартный канал Unix, а клиентская сторона. Postgres передает серию сообщений CopyData; клиент принимает их и как-то обрабатывает, например записывает в файл.

Тонкости оператора COPY мы рассмотрели в седьмой главе про отчетность. Обратитесь к ней, если что-то непонятно.

Напомним, что CSV-файлы подлежат сжатию. Даже обычные алгоритмы zip и gzip будут хорошим выбором. Еще большего выигрыша можно добиться, выбрав lz4 (утилита доступна во всех менеджерах пакетов). Алгоритмы LZMA2 и ZPAQ предлагают своего рода компромисс: крайне эффективное сжатие при медленной распаковке. Как правило, именно их выбирают для долгосрочного хранения версий, логов и подобной информации. Распаковка случается редко, а остальное время мы платим за объем.

Для полноты картины приведем процедуру truncate_and_dump_history, которая записывает удаленные версии в файл. Особенность в том, что выражение copy строится функцией format и выполняется оператором execute. Форматирование необходимо, чтобы путь к файлу включал в себя год, месяц и день. Для этого параметр %s внутри пути заменяется значением to_char(now(), 'yyyy_mm_dd').

create or replace procedure truncate_and_dump_history()
language plpgsql as $$
begin
    execute format($sql$
copy (delete from history where created_at < now() - interval '1 year' returning *)
to program 'gzip > /Users/ivan/work/pg-json-book-code/history_%s.csv.gzip' with (format csv, header on);
    $sql$, to_char(now(), 'yyyy_mm_dd'));
end;
$$;

Мы идем на подобные ухищрения, потому что copy не принимает параметров: все значения должны находиться в теле запроса. Процедуру легко расширить так, чтобы срок давности (interval '1 year') передавался параметром, ровно как и директория, куда записывать файл.

Как и в случае отчетами, задачу ставят на расписание при помощи расширения pg_cron. Тело задачи сводится к вызову процедуры:

call truncate_and_dump_history().

Стандарт JSON Patch

Последний вопрос этой главы касается стандарта JSON Patch (не путайте с JSON Path). Прежде чем рассказать, что это такое, рассмотрим, какую задачу мы надеемся решить с его помощью.

Когда мы сохраняем версию документа, то копируем его в историческую таблицу. При этом разница между документами может быть мала: скажем, поле status изменилось с pending на active. Это всего лишь одно поле, однако функция ничего не знает о характере обновления. Ей все равно, изменилось одно поле или десятки – документ копируется целиком.

Мы храним версии документа, но не можем ответить на вопрос, что именно в нем изменилось. Порой это необходимо: клиенты просят, чтобы при просмотре документа в боковом виджете были недавние изменения. Программистам тоже удобно, когда система предлагает быстрый способ сравнить документы. Это полезно при расследовании инцидентов или ошибок операторов. Сравнение документов вручную в программе Kdiff3 и аналогах занимает много времени. Здесь и приходит на помощь JSON Patch.

JSON Patch – это соглашение о том, как описать изменения в JSON-документе. Стандарт доступен на официальном сайте по одноименному адресу. JSON Patch – это даже не язык, а данные: массив объектов с полями op, path, value и некоторые другие. Каждый объект описывает одну операцию над документом, а массив определяет порядок.

Предположим, имеются два документа:

{
  "a": 1,
  "c": [1, 3],
  "d": true
}

{
  "b": 2,
  "c": [1, 2, 3]
}

Какие действия необходимы, чтобы перейти от первого ко второму? Вот как выглядит ответ на языке JSON Patch:

[
    {
        "op": "remove",
        "path": "/d"
    },
    {
        "op": "replace",
        "path": "/c/1",
        "value": 2
    },
    {
        "op": "add",
        "path": "/c/2",
        "value": 3
    },
    {
        "op": "remove",
        "path": "/a"
    },
    {
        "op": "add",
        "path": "/b",
        "value": 2
    }
]

Каждый шаг легко выразить на человеческом языке.

Сначала из документа удаляется поле d (путь /d).
В массиве "c" второй элемент меняется с 3 на 2.
К списку добавляется элемент 3.
Удаляется поле a.
Добавляется поле b со значением 2.

Если применить эти действия к первому документу, получим второй.

Не путайте JSON Patch с JSON Path (англ. patch – “заплатка”, path – “путь”). Это разные стандарты, причем первый описывает данные, а второй – язык. В разговорной речи JSON Patch называют патчем, заплаткой или “дифом” от английского difference – “разница”.

Из описания видно, что JSON Patch довольно прост. Он подразумевает всего шесть операций над документом: add, remove, replace, copy, move, test. Имея исходный документ и список изменений, легко применить их в цикле. Вычисление разницы между документами – напротив, сложная задача, и чуть ниже мы ее рассмотрим.

Замечания заслуживает поле “path” – путь к элементу. С этим полем связан еще один стандарт – Jsonpointer, который определяет, как строится путь к произвольному JSON-элементу. Стандарт имеет код RFC 6901 и может быть прочитан на сайте ietf.org.

Теперь когда мы знакомы с JSON Patch, объясним, как он поможет в версионировании документов. Если пользователи часто смотрят историю изменений, их можно материализовать – хранить в отдельной колонке. Для этого добавим в таблицу history поле patch с типом jsonb:

alter table history
add column patch jsonb null;

Ожидается, что в нем хранится патч – JSON-массив объектов. Если клиент хочет знать, какие изменения произошли в указанной версии, он передает ключ документа и версию. В ответ ему высылают содержимое колонки patch, например:

[
    {"op": "add", "path": "/status", "value": "pending"},
    {"op": "add", "path": "/accounts", "value": [1, 2, 3]},
    {"op": "replace", "path": "/some_field", "value": "foo"}
]

Добавьте к этим данным другие поля из таблицы history: пользователя, который произвел версию, комментарий, дату. У клиента окажется все необходимое, чтобы вывести изменения в удобном виде.

Патчи в приложении

Подумаем теперь, как заполнить колонку patch. Можно сделать это двумя способами: в приложении и в базе данных. Если приложение написано на Python, для работы с патчами понадобится пакет jsonpatch. Установите его командой:

pip3 install jsonpatch

Пользоваться им просто: статичный метод JsonPatch.from_diff принимает две структуры данных и возвращает экземпляр JsonPatch. Приведение его к строке дает патч в виде JSON. Метод apply принимает документ и применяет к нему патч, возвращая новый документ. Этих средств достаточно для нашей работы. Небольшая демонстрация:

import jsonpatch

# declare two documents
doc_old = {
  "a": 1,
  "c": [1, 3],
  "d": True
}

doc_new = {
  "c": [1, 2, 3],
  "b": 2
}

# create a patch object
patch = jsonpatch.JsonPatch.from_diff(doc_old, doc_new)

# get JSON representation of the patch
str(patch)
# [{"op": "remove", "path": "/a"}, {"op": "remove", "path": "/d"}, {"op": "add", "path": "/b", "value": 2}, {"op": "add", "path": "/c/1", "value": 2}]

# Apply the patch to the old document
doc_new2 = patch.apply(doc_old)

# Both new docs are equal
doc_new == doc_new2
# True

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

Django ORM не предлагает сигнала, который принимал бы оба экземпляра модели (условные instance_old и instance_new). Вместо этого регистрируют сигнал pre_save, где instance содержит новый экземпляр модели, а прежний мы получим, обратившись к базе методом .get. При этом учитываем, что экземпляр может быть новым (не заполнено поле .pk) либо прежнего документа почему-то не существует (исключение DoesNotExist). В обоих случаях сигнал прекращает работу. Если все идет по плану, из полей doc обеих моделей вычисляется патч, который сохраняется в таблицу версий.

import jsonpatch
from django.db.models.signals import pre_save
from django.forms.models import model_to_dict

@receiver(pre_save, sender=Application)
def save_patch(sender, instance, **kwargs):

    if not instance.pk:
        return

    try:
        app_old = Application.objects.get(pk=instance.pk)
    except sender.DoesNotExist:
        return

    patch = jsonpatch.JsonPatch.from_diff(app_old.doc, instance.doc)

    History.objects.create(
        pk=instance.id,
        entity='application',
        ...
        patch=patch.to_string()
    )

Еще одно средство Django – класс FieldTracker из пакета Model Utils. Это служебное поле, которое не сохраняется в базе, а только отслеживает изменения других полей. Вот как выглядит с ним модель:

from django.db import models
from model_utils import FieldTracker

class Application(models.Model):
    doc = JSONField(...)
    ...
    tracker = FieldTracker()


app = Application.objects.get(pk=...)
app.doc["extra"] = 123
app.save()

В сигнале pre_save мы получим прежнее значение doc методом previous. За счет этого не понадобится запрос к базе:

@receiver(pre_save, sender=Application)
def save_patch(sender, instance, **kwargs):

    if not instance.pk:
        return

    doc_old = instance.tracker.previous("doc")
    if not doc_old:
        return

    patch = jsonpatch.JsonPatch.from_diff(doc_old, instance.doc)

    History.objects.create(
        pk=instance.id,
        entity='application',
        ...
        patch=patch.to_string()
    )

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

Патчи в базе данных

Рассмотрим другую сторону вопроса: как работать с JSON Patch на уровне базы данных? По умолчанию Postgres не предлагает для этого никаких инструментов. Однако мы умеем работать с патчами на языке Python, а последний поддерживается в Postgres. Отсюда решение: напишем функцию на языке plpython3, которая сделает все необходимое.

Для начала установите пакет jsonpatch в тот интерпретатор, который используется расширением plpython3. Напомним, что одна из частых ошибок в том, что пакет установлен в другой интерпретатор и не находится при запуске кода в Postgres.

Создайте и опробуйте функцию py_make_patch. Она довольно проста: принимает два документа и возвращает разницу:

create or replace function py_make_patch(src jsonb, dst jsonb)
returns jsonb
language plpython3u strict as $$
    import json
    import jsonpatch
    doc_src = json.loads(src)
    doc_dst = json.loads(dst)
    patch = jsonpatch.JsonPatch.from_diff(doc_src, doc_dst)
    return patch.to_string()
$$;

Мы не использовали автоматический вывод типов директивой transform for type jsonb. Дело в том, что приведение класса JsonPatch к jsonb силами Postgres влечет некоторые сложности, в которые мы не будем углубляться. Заинтересованному читателю предлагаем домашнюю работу: добавить в функцию transform for type jsonb и избавиться от вызовов json.loads. Вам понадобится знание о внутреннем устройстве класса JsonPatch и чтение исходного кода.

Проверим функцию на минимальном примере:

select py_make_patch('{"a": 1}'::jsonb, '{"a": 2}'::jsonb) as patch;

┌───────────────────────────────────────────────┐
│                     patch                     │
├───────────────────────────────────────────────┤
│ [{"op": "replace", "path": "/a", "value": 2}] │
└───────────────────────────────────────────────┘

Добавим теперь вторую функцию, которая принимает документ и патч и возвращает новый документ:

create or replace function py_apply_patch(doc jsonb, patch jsonb)
returns jsonb
transform for type jsonb
language plpython3u immutable strict as $$
    import jsonpatch
    patch_obj = jsonpatch.JsonPatch(patch)
    return patch_obj.apply(doc)
$$;

Опробуем ее в действии:

select py_apply_patch(
    $$
{"some_field": "test", "application_id": 100321}
    $$::jsonb,
    $$
[
    {"op": "add", "path": "/status", "value": "pending"},
    {"op": "add", "path": "/accounts", "value": [1, 2, 3]},
    {"op": "replace", "path": "/some_field", "value": "foo"}

]
    $$::jsonb) as doc_new;

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                                           doc_new                                           │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ {"status": "pending", "accounts": [1, 2, 3], "some_field": "foo", "application_id": 100321} │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

Видим, что все три операции применились корректно.

Версии с патчами

Теперь когда Postgres работает с патчами, перепишем версионирование. Вот как выглядит оператор, который создает или обновляет документ; во втором случае создается версия документа с патчем:

prepare update_application as
with
upsert as (
    insert into applications(id, doc)
    values ($1::uuid, $2::jsonb)
    on conflict (id) do update set
    doc = excluded.DOC,
    updated_at = now()
    returning NEW.id, OLD.doc as doc_old, NEW.doc as doc_new
)
insert into history(pk, entity, operation, doc, patch, created_at)
select
    id,
    'applications',
    'UPDATE',
    doc_old,
    py_make_patch(doc_old, doc_new),
    current_timestamp
from
    upsert
where
    doc_old is not null;

Предположим, исходный документ выглядит следующим образом:

{"some_field": "test", "application_id": 100321}

Обновим его и посмотрим на содержимое таблиц:

execute update_application(
    '00000000-0000-0000-0000-000000100321'::uuid,
    $$
{
    "application_id": 100321,
    "status": "pending",
    "some_field": "foo",
    "accounts": [1, 2, 3]
}
    $$::jsonb
);

select
    id, pk, entity, doc,
    jsonb_pretty(patch) as patch
from
    history;

┌─[ RECORD 1 ]──────────────────────────────────────────────┐
│ id     │ dcbb3da3-5f2c-4ae7-861c-5c401c550905             │
│ pk     │ 00000000-0000-0000-0000-000000100321             │
│ entity │ applications                                     │
│ doc    │ {"some_field": "test", "application_id": 100321} │
│ patch  │ [                                               ↵│
│        │     {                                           ↵│
│        │         "op": "add",                            ↵│
│        │         "path": "/status",                      ↵│
│        │         "value": "pending"                      ↵│
│        │     },                                          ↵│
│        │     {                                           ↵│
│        │         "op": "add",                            ↵│
│        │         "path": "/accounts",                    ↵│
│        │         "value": [                              ↵│
│        │             1,                                  ↵│
│        │             2,                                  ↵│
│        │             3                                   ↵│
│        │         ]                                       ↵│
│        │     },                                          ↵│
│        │     {                                           ↵│
│        │         "op": "replace",                        ↵│
│        │         "path": "/some_field",                  ↵│
│        │         "value": "foo"                          ↵│
│        │     }                                           ↵│
│        │ ]                                                │
└────────┴──────────────────────────────────────────────────┘

В колонке patch оказались следующие операции:

{"op": "add", "path": "/status", "value": "pending"}
{"op": "add", "path": "/accounts", "value": [1, 2, 3]}
{"op": "replace", "path": "/some_field", "value": "foo"}

Если применить к версии операции из поля patch, получим текущий документ.

Прием патчей от клиента

На базе JSON Patch можно построить еще одно решение. Если клиент хочет изменить документ, можно принять от него только патч. Его применяют к текущему документу, и дополнительно мы создаем версию. Вычислять патч при этом не нужно, потому что он уже есть. Подход оправдывает себя на крупных документах, которые дорого передавать по сети. Патч практически всегда меньше документа.

Напомним, мы уже написали функцию py_apply_patch, которая принимает документ, патч и возвращает новый документ:

create or replace function py_apply_patch(doc jsonb, patch jsonb)
returns jsonb
transform for type jsonb
language plpython3u immutable strict as $$
    import jsonpatch
    patch_obj = jsonpatch.JsonPatch(patch)
    return patch_obj.apply(doc)
$$;

Добавим оператор patch_application_with_history от двух параметров: ключа документа ($1::uuid) и патча ($2::jsonb). Стадия step_old запоминает документ до того, как мы наложим на него патч. Стадия step_update обновляет документ, задействуя функцию py_apply_patch. В основной части мы записываем версию документа, используя старое значение из step_old и переданный патч.

prepare patch_application_with_history as
with
step_old as (
  select * from applications where id = $1::uuid
),
step_update as (
  update applications set doc = py_apply_patch(doc, $2::jsonb)
  where id = $1::uuid
)
insert into history(pk, entity, operation, doc, patch, created_at)
  select
      step_old.id,
      'applications',
      'UPDATE',
      step_old.doc,
      $2::jsonb,
      current_timestamp
  from
      step_old;

Вызовем оператор для одного из документов:

execute patch_application_with_history(
    '00000000-0000-0000-0000-000000100321'::uuid,
    $$
    [
        {"op": "add", "path": "/comment", "value": "updated using a JSON patch"}
    ]
    $$::jsonb
);

Проверим историю: в ней окажется прошлый документ и патч.

select
    jsonb_pretty(doc) as doc,
    jsonb_pretty(patch) as patch
from
    history
where
    pk = '00000000-0000-0000-0000-000000100321';

┌──────────────────────────────┬───────────────────────────────────────────────┐
│             doc              │                     patch                     │
├──────────────────────────────┼───────────────────────────────────────────────┤
│ {                           ↵│ [                                            ↵│
│     "some_field": "test",   ↵│     {                                        ↵│
│     "application_id": 100321↵│         "op": "add",                         ↵│
│ }                            │         "path": "/comment",                  ↵│
│                              │         "value": "updated using a JSON patch"↵│
│                              │     }                                        ↵│
│                              │ ]                                             │
└──────────────────────────────┴───────────────────────────────────────────────┘

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

Коротко об event-sourcing

Event-sourcing – это подход, когда хранятся не только данные, и но и события, которые эти данные формируют. При этом сущность можно пересобрать, применив события в том же порядке. Последнее особенно важно: события хранятся не просто для истории, они равноценны данным. Сушности, построенные из событий, по-другому называют агрегатами. Говорят, что агрегат равен сумме его событий.

Когда сущность строится из событий, это дает интересные возможности. В любой момент ее можно “переиграть” – собрать с нуля. Если ограничить события датой (например, не позже 2026 года), то получим версию документа в прошлом. В редких случаях событие можно удалить и собрать агрегат без него. События полезны в отладке и по-своему заменяют логи.

Не путайте event-sourcing с версионированием. Хоть мы и рассматриваем их в одной главе, это не одно и то же. Версии хранят полноценные документы, а события описывают отдельные изменения. Версия самодостаточна, а событию требуются вся цепочка. Рассматривайте версии как бекапы, а события – как миграции отдельных документов.

Версии и события не противоречат, а дополняют друг друга. В проекте, где работал автор, использовались оба подхода для разных нужд. Система событий позволяла в любой момент собрать агрегат заново. Этим пользовались, когда определенное событие признавали ошибочным. Версии были необходимы, потому что от них отталкивались некоторые операции, и вычислять версию через события было долго.

Простым примером event-sourcing служит история банковского счета. Когда клиент вносит деньги на счет, мы не просто увеличиваем баланс. Пополнение счета записывается в таблицу операций и хранится вместе с другими фактами пополнения, снятия, переводов, комиссий и других. Таким образом баланс – это сумма всех операций. Баланс материализуют (хранят в отдельном поле), потому что рассчитывать его каждый раз дорого. Однако важно понимать, что совокупность событий важнее результата. Если отдельную операцию признали ошибочной или незаконной, баланс пересчитают.

Еще одно уточнение касается слова “сумма”. Под ним мы имеем в виду результат применения операций. Какие именно действия выполняет событие – зависит от его типа. В случае с банковским счетом баланс нельзя вычислить арифметически, потому что иные события включают процент на остаток или конвертацию валют.

В прошлом параграфе мы научились хранить патч для каждого изменения. Легко заметить, что получился своего рода event-sourcing. Действительно: если взять исходный документ и применить к нему серию патчей, получим текущий (последний) документ. Если результаты отличаются, то имеет место нарушение: либо события теряются, либо кто-то исправил документ в обход нашей системы.

Сбор агрегатов из событий

Рассмотрим, как применить набор патчей к исходному документу. У нас уже достаточный опыт работы с jsonpatch, поэтому приведем минимальные примеры. Если doc – начальный документ, а patches – список патчей, код выглядит так:

import jsonpatch

doc = {}
patches = [
    [{"op": "add", "path": "/a", "value": 1}],
    [{"op": "add", "path": "/b", "value": 2}],
]

for patch in patches:
    p = jsonpatch.JsonPatch(patch)
    doc = p.apply(doc)

print(doc)
# {'a': 1, 'b': 2}

Программисты, знакомые с функциональным программированием, заметят, что это свертка, известная также как fold или reduce. Чтобы выполнить свертку, достаточно функции приращения – такой, что принимает аккумулятор и очередной элемент и возвращает новый аккумулятор. Перепишем код в виде свертки:

import jsonpatch
from functools import reduce

def step_fn(acc, patch):
    p = jsonpatch.JsonPatch(patch)
    return p.apply(acc)

doc = reduce(step_fn, patches, {})

print(doc)
# {'a': 1, 'b': 2}

Мы не случайно упомянули свертку. Дело в том, что агрегатные функции Postgres строятся на том же принципе: им необходим начальный элемент и функция приращения. Зная это, мы напишем агрегатную функцию, которая, если передать ей столбец патчей, применит их один за другим. С ее помощью мы получим документ одним запросом к таблице событий.

Объявим агрегатную функцию json_patch_agg:

create aggregate json_patch_agg (jsonb) (
    sfunc = py_apply_patch,
    stype = jsonb,
    initcond = '{}'
);

Из многих параметров мы указали три:

sfunc (state function): функция приращения. Принимает два параметра, где первый – аккумулятор, который накапливает значение. Второй аргумент функции – очередное значение колонки. Функция возвращает новый аккумулятор.
stype: тип, с которым работает агрегатная функция. В нашем случае это jsonb.
initcond: начальный (пустой) элемент. Используется в качестве аккумулятора при первом вызове функции приращения.

Напомним, что функцию приращения мы уже объявляли – это py_apply_patch. Она принимает документ, патч и возвращает новый документ. Приведем ее здесь для контекста:

create or replace function py_apply_patch(doc jsonb, patch jsonb)
returns jsonb
transform for type jsonb
language plpython3u immutable strict as $$
    import jsonpatch
    patch_obj = jsonpatch.JsonPatch(patch)
    return patch_obj.apply(doc)
$$;

Представим теперь, что некоторая таблица хранит список патчей (событий), упорядоченных по времени или счетчику. Вот как выглядит запрос с агрегацией патчей:

select
    json_patch_agg(patch) as doc
from (values
    (1, '[{"op": "add", "path": "/a", "value": 1}]'::jsonb),
    (2, '[{"op": "add", "path": "/b", "value": 2}]'::jsonb),
    (3, '[{"op": "replace", "path": "/a", "value": 3}]'::jsonb)
) as vals(id, patch);

┌─[ RECORD 1 ]───────────┐
│ doc │ {"a": 3, "b": 2} │
└─────┴──────────────────┘

Конечно, подобный запрос дорог в плане вычислений. Однако с ним мы получим документ мгновенно: не понадобится приложение, его настройка и запуск. Достаточно минимального клиента к базе вроде psql или PGAdmin.

Махинации с патчами

Чем дольше вы работаете с JSON Patch, тем больше откроете трюков и техник. В этом параграфе мы расскажем о двух из них.

Несколько патчей можно свести к одному, банально объединих их. Действительно: если патч p1 содержит операции o1, o2 и o3, а p2 – o4, o5 и o6, то легко получить патч p3 с операциями o1 – o6, и они применятся в том же порядке. Напомним, что в Python списки объединяются оператором + (плюс), а в Postgres – || (палочки). Полученный патч называют супер- или пакетным патчем.

В примере ниже оба патча применяются как один, при этом порядок сохраняется: в итоговом списке числа идут в верной последовательности. Дефис на конце пути "/nums/-" означает несуществующий элемент списка – его конец, куда и добавляются числа.

p1 = [
    {"op": "add", "path": "/nums/-", "value": 1},
    {"op": "add", "path": "/nums/-", "value": 2},
    {"op": "add", "path": "/nums/-", "value": 3},
]

p2 = [
    {"op": "add", "path": "/nums/-", "value": 4},
    {"op": "add", "path": "/nums/-", "value": 5},
    {"op": "add", "path": "/nums/-", "value": 6},
]

doc = {"nums": []}

print(jsonpatch.JsonPatch(p1 + p2).apply(doc))
# {'nums': [1, 2, 3, 4, 5, 6]}

Перенесемся в Postgres. Предположим, имеется таблица событий с колонкой patch. Как получить пакетный патч всех событий? Для этого напишем агрегатную функцию, которая объединяет jsonb-массивы в один:

create aggregate jsonb_concat_agg (jsonb) (
    sfunc = jsonb_concat,
    stype = jsonb,
    initcond = '[]'
);

В результате агрегации получим единый патч:

select
    jsonb_pretty(jsonb_concat_agg(patch)) as doc
from (values
    (1, '[{"op": "add", "path": "/a", "value": 1}]'::jsonb),
    (2, '[{"op": "add", "path": "/b", "value": 2}]'::jsonb),
    (3, '[{"op": "add", "path": "/c", "value": 3}]'::jsonb)
) as vals(id, patch);

┌─[ RECORD 1 ]────────────────┐
│ doc │ [                    ↵│
│     │     {                ↵│
│     │         "op": "add", ↵│
│     │         "path": "/a",↵│
│     │         "value": 1   ↵│
│     │     },               ↵│
│     │     {                ↵│
│     │         "op": "add", ↵│
│     │         "path": "/b",↵│
│     │         "value": 2   ↵│
│     │     },               ↵│
│     │     {                ↵│
│     │         "op": "add", ↵│
│     │         "path": "/c",↵│
│     │         "value": 3   ↵│
│     │     }                ↵│
│     │ ]                     │
└─────┴───────────────────────┘

По умолчанию JSON Patch предлагает шесть типов операций: add, replace и другие. Однажды вы обнаружите, что для комфортной работы их не хватает. Например, чтобы описать пополнение счета, необходима операция приращения (increase):

{"op": "inc", "path": "/amount", "value": 200}

Использование replace для этой цели будет ошибкой. Если до операции на счету было 1000 рублей и клиент добавил 500, патч с replace выглядит так:

[{"op": "replace", "path": "/amount", "value": 1500}]

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

[
    {"op": "replace", "path": "/amount", "value": 1200},
    {"op": "replace", "path": "/amount", "value": 1500}
]

Если удалить первое событие (200 рублей), то после второго на счету снова окажется окажется 1500 рублей, что неверно. Предположим теперь, что события созданы при помощи операции inc:

[
    {"op": "inc", "path": "/amount", "value": 200},
    {"op": "inc", "path": "/amount", "value": 300}
]

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

Библиотеку jsonpatch легко расширить. Встроенные операции унаследованы от класса PatchOperation и содержатся в приватном словаре. Расширение сводится к двум шагам:

на базе PatchOperation определить класс с частным методом apply;
добавить его в словарь операций.

Опишем класс операции:

from jsonpatch import JsonPatch, PatchOperation

class IncrementOperation(PatchOperation):

    def apply(self, obj):
        subobj, part = self.pointer.to_last(obj)
        try:
            val = subobj[part]
        except (KeyError, IndexError):
            raise

        if not isinstance(val, (int, float)):
            raise TypeError(f"Value is not a number: {val}")

        try:
            value = self.operation["value"]
        except KeyError as ex:
            raise InvalidJsonPatch("The operation does not contain a 'value' member")

        subobj[part] += value
        return obj

Большую часть метода apply занимают проверки и внятные сообщения об ошибках. Регистрация несколько неуклюжа: поле JsonPatch.operations – неизменяемый словарь, так что мы замещаем его новым.

ops = JsonPatch.operations | {
    'inc': IncrementOperation
}

JsonPatch.operations = ops

Опробуем новую операцию в действии:

doc = {"amount": 1000}

p = JsonPatch([
    {"op": "inc", "path": "/amount", "value": 200},
    {"op": "add", "path": "/foo", "value": "a"},
    {"op": "inc", "path": "/amount", "value": 300},
    {"op": "add", "path": "/bar", "value": "b"},
])

print(p.apply(doc))
# {'amount': 1500, 'foo': 'a', 'bar': 'b'}

По аналогии пишутся другие операции: это классы и регистрация под уникальным именем. Схожим образом расширяются библиотеки для Java или JavaScript.

Чтобы инкремент был доступен в Postgres, скопируйте файл json_patch_ops.py на сервер. Он должен быть в директории, которую Python просматривает при загрузке модулей. Простое решение в том, чтобы скопировать файл в директорию site-packages или указать к нему путь в переменной PYTHONPATH. Более грамотный подход – оформить код в пакет и устанавливать при помощи pip3. Рассмотрите вариант, чтобы вашу работу включили в официальную библиотеку, например в виде расширения.

Бесконфликтное редактирование

Концепция патчей решает и другие проблемы, связанные с документами. Одна из них касается конфликтов при совместном редактировании. Мы уже упоминали ее в третьей главе (параграф “Обновление”), но на тот момент у нас не хватало знаний. Настало время это исправить.

Предположим, сотрудники Иванов и Петров редактируют один и тот же документ. Наша задача — сделать так, чтобы изменения одного сотрудника не затерли изменения другого. Например, если Иванов изменил поле amount, а Петров — comment, эти правки не конфликтуют друг с другом и можно применить их в любом порядке. Если Петров тоже исправил amount, перед нами классический конфликт.

Наивное решение в том, чтобы при открытии документа пометить его в базе занятым. Для других сотрудников такой документ открывается в режиме чтения. Однако сотрудник может заблокировать документ и уйти на совещание. Все это время документ либо недоступен для правок другим, либо через какое-то время система сбросит блокировку, и локальные изменения потеряются.

Можно заблокировать документ на уровне базы командой select for update. Однако выражение for update требует транзакции, и мы не можем держать ее неограниченно долго.

Желательно, чтобы сотрудник, который отправил amount вторым, получил негативный ответ и новое значение amount, чтобы пересмотреть его. Для этого изменения отслеживают на уровне отдельных полей документа, и JSON Patch выступает помощником.

Техника, что мы рассматриваем, опирается на три версии документа: исходную (А) и две локальных (B и C). Имея эти три версии, легко найти патч для пар (А → В) и (А → С). Далее мы проверяем, есть у патчей общие поля. Если нет, патчи не конфликтуют, и можно применить их в любом порядке. В противном случае мы не только уведомим пользователя о конфликте, но и скажем, какое поле стало его причиной.

Мы привели самое общее решение; у него может быть множество реализаций. В зависимости от условий изменения могут применяться на клиентской части или серверной. Клиент может передавать документ целиком или только патч. Ниже мы рассмотрим вариант с приоритетом на бэкенд (серверную часть).

Решение конфликтов

Итак, Иванов и Петров одновременно открыли документ на редактирование. Изначально документ выглядел как в примере ниже. Назовем его ревизией А:

{
  "id": 100500,
  "version": 1,
  "amount": 100,
  "title": "New document"
}

Иванов исправил поле amount на 110 и нажал “Сохранить”. На сервер ушел документ ревизии B:

{
  "id": 100500,
  "version": 1,
  "amount": 110,
  "title": "New document"
}

Выше мы указываем версию нарастающим число: 1, 2 и так далее. Это небезопасно: ничто не мешает злоумышленнику передать версию 999, и серверный алгоритм сработает с ошибкой. Для версий лучше использовать идентификатор UUID, подобрать который вручную невозможно. В нашем случае мы используем числа только для краткости.

По полю version сервер определяет, что изменения отталкиваются от версии 1. Выполняется проверка: 1 — это текущий документ? Для этого мы читаем версию из таблицы applications. Если в ней записано 1, это значит, что никто не успел внести изменения до нас, и мы вправе сделать это сейчас. Замещение документа происходит в два шага:

документ А (версии 1, исходный) уходит в историческую таблицу;
новый документ В замещает текущий, его версия становится 2.

Изменения Иванова приняты. А что с Петровым? Бедняга просидел весь день на митингах и вернулся к компьютеру в конце дня. Петров нашел силы только на то, чтобы изменить заголовок с “New document” на “My document”. На сервер ушел документ, который мы назовем ревизией C:

{
  "id": 100500,
  "version": 1,
  "amount": 100,
  "title": "My document"
}

Сервер выполнит те же самые действия, что и в прошлый раз. Он прочитает текущий документ и выяснит, что его версия не 1, а 2. Это значит, за время отсутствия Петрова документ изменился. Его нельзя переписать: если сделать текущей версию Петрова, то изменения Иванова (amount 110) пропадут.

Можно сообщить Петрову, что документ изменился, и вынудить его повторить действия, отталкиваясь от последней версии. Однако прежде чем так поступить, подумаем, можно ли решить проблему автоматически.

Вопрос, который мы намереваемся решить, звучит так: действительно ли изменения Иванова и Петрова конфликтуют? Если да, то ничего поделать нельзя, и мы вынуждены делегировать вопрос людям. Пусть Иванов и Петров встретятся лично и решат, чьи изменения важнее. Если же конфликта нет, можно применить изменения каждого сотрудника по отдельности без необходимости их беспокоить.

Легко заметить, что в нашем примере конфликта нет. Иванов исправил поле amount, а Петров — title, поэтому изменения Петрова все-таки можно принять даже с учетом того, что они опираются на устаревший документа. Вот как проверить конфликт программным способом:

найти изменения (патч) между версиями A и B (исходной и Иванова);
то же самое для A и C (исходной и Петрова);
определить, есть ли в патчах элементы с одинаковым полем path.

В нашем случае патчи выглядят следующим образом. От А к В:

[
    {
        "op": "replace",
        "path": "/amount",
        "value": 110
    }
]

От А к С:

[
    {
        "op": "replace",
        "path": "/title",
        "value": "My document"
    }
]

Видим, что пути /amount и /title не пересекаются, поэтому изменения не конфликтуют. Чтобы применить версию Петрова, мы берем последний актуальный документ (версию Иванова) и накладываем на него второй патч (A → C). Результат становится новым текущим документом с версией 3.

Предположим теперь, Петров изменил не только заголовок документа, но и поле amount. Назовем эту ревизию C2:

{
  "id": 100500,
  "version": 1,
  "amount": 115,
  "title": "My document"
}

Патч А → C2 выглядит так:

[
    {
        "op": "replace",
        "path": "/title",
        "value": "My document"
    },
    {
        "op": "replace",
        "path": "/amount",
        "value": 115
    }
]

Очевидно, теперь он пересекается с патчем А → В: в обоих есть элемент с полем /amount. Решить конфликт программа не в состоянии, потому что только авторы знают, какое значение верное. Со стороны сервера будет правильным сделать следующее:

в ответ на запрос Петрова сообщить, что имеются конфликты с последней версией документа;
выслать сам документ;
сообщить набор полей и их значений, которые привели к конфликту. В примере выше это элемент

{
    "op": "replace",
    "path": "/amount",
    "value": 115
}

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

Когда конфликт исправлен (скажем, стороны договорились, что поле amount должно быть вообще 120), Петров высылает документ ревизии D:

{
  "id": 100500,
  "version": 2,
  "amount": 120,
  "title": "My document"
}

Это изменение отталкивается от текущей версии 2. Когда сервер проделает шаги, что мы уже рассмотрели, новый документ заменит прежний, а последний уйдет в таблицу версий.

Интересно, что наш подход работает для множественных изменений. Предположим, пока Петров сидел на совещании, сразу несколько сотрудников изменили документ. В результате текущим стал документ версии 9 (обозначим его F):

{
  "id": 100500,
  "version": 9,
  "amount": 100,
  "category": "risk",
  "email": "john@test.com",
  "title": "Customer #123",
  "history": [
      {
          "event": "edited",
          "user": 92323
       }
  ]
}

Патч от исходного документа к текущему (A → F) выглядит так:

[
    {
        "op": "replace",
        "path": "/title",
        "value": "Customer #123"
    },
    {
        "op": "replace",
        "path": "/version",
        "value": 9
    },
    {
        "op": "add",
        "path": "/category",
        "value": "risk"
    },
    {
        "op": "add",
        "path": "/email",
        "value": "john@test.com"
    },
    {
        "op": "add",
        "path": "/history",
        "value": [
            {
                "event": "edited",
                "user": 92323
            }
        ]
    }
]

Среди измененных полей нет /amount, следовательно патчи A → F и A → C не пересекаются. Изменения Петрова можно по-прежнему применить к последнему документу.

Технические детали

Рассмотрим функцию сравнения двух патчей. Она принимает два jsonb-документа (массивы объектов) и определяет, есть ли в них одинаковые поля path. Функция довольно проста: это пересечение (intersect) двух вызовов jsonb_path_query. Если пересечение не пустое (exists нашел хотя бы одну запись), имел место конфликт.

create or replace function find_conflicts(patch1 jsonb, patch2 jsonb)
returns boolean
language sql immutable strict parallel safe
return exists(
  select jsonb_path_query(patch1, 'strict $[*].path')
  intersect
  select jsonb_path_query(patch2, 'strict $[*].path')
);

Возможно, вам понадобится не просто логический флаг, а сводная информация: какие именно поля затронуты и с какими значениями. Подойдет вторая функцию, которая оперирует таблицами. Каждый патч она приводит к нативной таблице Postgres с полями op, path, value и другими. Далее эти таблицы соединяются оператором JOIN. Если результат не пустой, мы увидим, что именно привело к конфликту. Функция:

create or replace function find_conflicts(patch1 jsonb, patch2 jsonb)
returns table (
    i1 integer,
    op1 text,
    path1 text,
    value1 jsonb,
    from1 text,
    i2 integer,
    op2 text,
    path2 text,
    value2 jsonb,
    from2 text
)
language sql immutable strict parallel safe as $$
with
p1 as (
    select jt.*
    from json_table(patch1, '$[*]' columns(
        i     for ordinality,
        op    text  path '$.op',
        path  text  path '$.path',
        value jsonb path '$.value',
        "from"  jsonb path '$.from'
    )) as jt
),
p2 as (
    select jt.*
    from json_table(patch2, '$[*]' columns(
        i     for ordinality,
        op    text  path '$.op',
        path  text  path '$.path',
        value jsonb path '$.value',
        "from"  jsonb path '$.from'
    )) as jt
)
select *
from p1, p2
where
        p1.op = p2.op
    and p1.path = p2.path
    and p1.value != p2.value;
$$;

Вызовем ее с патчами без конфликтов:

select * from find_conflicts(
$$
[
    {
        "op": "replace",
        "path": "/amount",
        "value": 120
    },
    {
        "op": "add",
        "path": "/comment",
        "value": "edited"
    }
]
$$::jsonb,
$$
[
    {
        "op": "add",
        "path": "/user_ids/3",
        "value": 40
    },
    {
        "op": "replace",
        "path": "/title",
        "value": "Test 2"
    }
]
$$::jsonb
);

┌────┬─────┬───────┬────────┬───────┬────┬─────┬───────┬────────┬───────┐
│ i1 │ op1 │ path1 │ value1 │ from1 │ i2 │ op2 │ path2 │ value2 │ from2 │
├────┼─────┼───────┼────────┼───────┼────┼─────┼───────┼────────┼───────┤
└────┴─────┴───────┴────────┴───────┴────┴─────┴───────┴────────┴───────┘
(0 rows)

А теперь – с конфликтами:

select * from find_conflicts(
$$
[
    {
        "op": "replace",
        "path": "/amount",
        "value": 120
    },
    {
        "op": "add",
        "path": "/comment",
        "value": "edited"
    }
]
$$::jsonb,
$$
[
    {
        "op": "replace",
        "path": "/amount",
        "value": 150
    },
    {
        "op": "replace",
        "path": "/title",
        "value": "Test 2"
    }
]
$$::jsonb
);

┌────┬─────────┬─────────┬────────┬────────┬────┬─────────┬─────────┬────────┬────────┐
│ i1 │   op1   │  path1  │ value1 │ from1  │ i2 │   op2   │  path2  │ value2 │ from2  │
├────┼─────────┼─────────┼────────┼────────┼────┼─────────┼─────────┼────────┼────────┤
│  1 │ replace │ /amount │ 120    │ <null> │  1 │ replace │ /amount │ 150    │ <null> │
└────┴─────────┴─────────┴────────┴────────┴────┴─────────┴─────────┴────────┴────────┘

Из отчета видно, что причиной стало поле /amount, значения сторон B и C – 120 и 150. Отправим эту информацию клиенту; ожидается, что приложение выделит проблемные поля и поможет пользователю их исправить.

На примере JSON Patch мы рассмотрели, как отслеживать изменения в документах с точностью до поля. Не всегда бизнес нуждается в подобной технике, но в редких случаях она снимает множество проблем.

Важно, что алгоритм полностью реализуется силами базы: роль приложения минимальна. Базе требуется только функция, которая по двум документам строит патч. Проще всего делегировать эту задачу расширению plpython3u и пакету jsonpatch. Искушенные читатели могут написать код на на Си и оформить его в расширение Postgres.

На этом мы закончим главу о версионировании документов. Добавим, что хранение версий, их откат и восстановление – та задача, которую трудно перенести на другие проекты. В каждой области свои требования и правовые нормы. Надеемся, мы рассмотрели достаточно техник, чтобы читатель собрал из них свое решение.

Приглашаем читателя к последней главе, где мы закроем нерешенный вопрос с поиском.

Русская речь в фильмах

Sat, 01 Aug 2026 00:00:00 +0000

Иногда русская озвучка бывает, мягко говоря, спорной. Актеры кричат в тех местах, где персонаж шепчет; интонация странная, пропадают акценты, идиомы, игра слов. Так что если вам позволяют условия (знаете язык, партнер(ша) не возражает), потребляйте фильмы и игры в оригинале (или хотя бы ключевые сцены). У этого правила, однако, есть исключение: иногда в оригинале звучит русская речь. В таком исполнении, что хочется не слышать ее ни за какие деньги.

Имеем американского персонажа. Всем он хорош: и силен, и умен, и женщину спас. Одна беда – русского происхождения. И вот на середине фильма всплывает русская мафия, дядюшка или бывшая, с которыми герой изъясняется по-русски. То есть как по-русски: в Гугл-транслейт набивается текст на английском, тот выдает русский транслит. Актер учит его наизусть как абракадабру: “Татиана, как дафно ти юже десь?” Татьяна: “Пивет Джон, две ньидели ка пиехаля”.

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

Когда русский бандит обращается к американцам, проблемы не возникает. Тут даже переигрывают: “лэт мы спык ынглиш фр-р-ром май хар-р-рт”. Плохой персонаж всегда будет с рокочущим “р”. Как обезьянничать, так все мастера. А как насчет нормальной речи?

Много лет назад со мной был случай. Я играл в одну игру, и там на хороших парней (американцев) напали плохие (конечно, русские). Атаку отбили, и одного молодого бандита взяли в плен. А он оплакивает убитую шальной пулей сестру: Наташа, очнись, солнышко, пойдем… и все это – на чистом русском. Ощущение, словно за спиной кто-то говорит. Я аж подскочил на стуле.

Из Википедии и всяких ссылок я узнал, что этот фрагмент – инициатива русскоязычного сотрудника студии. Изначально дорожку записали как есть – транслитом. Вообразите, как звучали слова скорби из уст человека, который не знает языка? Картавые “встаувай, Натащья, ти живуа? Нье умиай!” Все это – в момент смерти? Это даже не кринж, а пиздец, и так делать нельзя.

Разработчик прекрасно это понимал и сделал вот что. Когда все ушли, он записал дорожку на нормальном русском и подменил в ассетах. Никто не заметил, и русская речь ушла в релиз. Позже игру хвалили в том числе и за это: впервые за вечность в игре адекватная речь, а не транслит.

Выходит, что инди-студия смогла, а Голливуд не может? Слабо верится.

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