Ivan Grishaev's blog

Is AI Profitable Yet?

Sun, 05 Jul 2026 00:00:00 +0000

Еще один сайт-страничка называется Is AI Profitable Yet?. За указанным заголовком следует лаконичное No, а ниже – фирмы вроде Гугла, Амазона и так далее. Напротив каждой указано, сколько денег они потратили на эй-ай и сколько заработали.

Автор утверждает, что информация взята из официальных источников. В подвале есть выпадашка с надписью Sources & References, и если ее нажать, откроются ссылки. Разумеется, я их не проверял и не ручаюсь за достоверность. Сайт я рассматривают только как интересную инфографику.

Особая ситуация с Nvidia. Эти ребята – единственные, у кого зеленый столбик опережает красный, причем с двойным запасом. Nvidia, конечно, молодцы. У них даже не звездный час, а звездные 15 последних лет. Сначала был майнинг, потом машинное обучение, потом голосовые модели, а сейчас еще агенты — при этом не исключая старые добрые игры, рендер, VR. Все это растет экспоненциально, строители не успевают заливать бетон под датацентры.

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

Поживем – увидим.

Как работать?

Sun, 05 Jul 2026 00:00:00 +0000

У меня простой вопрос: как вообще работать? Я о том, что если следить за всеми потоками информации, то весь день я просижу в корпоративных мессаджере и почте. Редактор и терминал я ни разу не открою.

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

Еще звонки: дейли, демо, ретро, планнинг, постмортем, тимбилдинг и так далее. Еще календаль. Еще ревью. При этом личные обязанности вроде отвоза-забора детей никто не отменял.

Эта заметка не о том, чтобы собрать советы а-ля “настрой почту” и “отключи уведомления”. Все это я применяю и готов написать сотню подобных советов. Я говорю о другом: никто не учит нас находить время для работы. Скажем, мне накидали три митинга, а кто научит тому, чтобы поработать между ними?

Я научился, а кто-то нет. Или я думаю, что научился, а сам протупил час на ровном месте.

Полтора часа неотрывного кодинга – что-то из области фантастики. Чаще всего это случается, когда у заказчика праздник (и становится моим личным праздником).

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

Don't paste the AI, please

Sun, 05 Jul 2026 00:00:00 +0000

Нашел забавный сайт-страничку: Don’t paste the AI, please. В наличии несколько переводов и редакций (вежливая, грубая). Вспомнил, что похожая мысль лежала в черновиках, но я все откладывал. Что ж, хоть кто-то и успел вперед меня, все равно публикую.

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

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

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

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

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

В общем, сохраните ссылку и кидайте ее ребятам, у которых беда с элементарной этикой.

UPD аналоги:

Stop Citing AI

Глава 6. Язык JSON Path

Fri, 03 Jul 2026 00:00:00 +0000

Главы

Введение в документы
Базовые возможности JSON
JSON в таблицах
Индексирование JSON
Ограничения в документах
Язык путей JSONPath
Отчеты и функции
Функции на языке Python
Версионирование и архивация документов
Релевантный поиск

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

Прежде чем пускаться в технические детали, расскажем о стандарте JSON Path и о том, какие проблемы он решает.

Последние два десятилетия формат JSON популярен во всех сферах айти. Это привело к тому, что многие базы данных поддерживают его в той или иной мере. Слово “поддерживает” означает, что база не только хранит JSON, но и предлагает средства, чтобы извлечь его подмножество или обновить без передачи всего документа. В Postgres поддержка JSON особенно сильна; в последние годы такие же возможности появились в SQLite, MySQL и SQL Server.

Каждая база предлагает свои операторы и функции для работы с JSON. За прошедшие пять глав читатель убедился, как много их в Postgres. Однако практика показывает, что запомнить их все невозможно, особенно если вы работаете с разными базами данных.

По мере того, как в каждую СУБД добавляли JSON, стало ясно: многие действия можно выразить с помощью декларативного языка или пути. Например, чтобы получить часть документа, система принимает выражение, где описан путь и параметры фильтрации. Нас не интересует, как именно обрабатывается путь; в идеале результат одинаков на всех платформах.

Описанное выше напоминает XPath – язык путей XML. Формат XML, хоть и уступил в популярности JSON, все еще встречается на многих платформах. Причина, по которой появился язык XPath, была та же: привести частные решения к общему знаменателю. Удобно, когда одно и то же выражение XPath работает и в Python, и в Javascript, и в базе данных.

Формат JSON, хоть и отличается от XML, имеет с ним нечто общее – путь. Приведем один и тот же документ в двух форматах:

<?xml version="1.0" encoding="UTF-8"?>
<users>
  <user id="101" age="33">Ivan Petrov</user>
  <user id="135" age="52">Andrey Ivanov</user>
  <user id="399" age="41">Anna Smirnova</user>
</users>

{
  "users": [
    {
      "id": 101,
      "age": 33,
      "name": "Ivan Petrov"
    },
    {
      "id": 135,
      "age": 52,
      "name": "Andrey Ivanov"
    },
    {
      "id": 399,
      "age": 41,
      "name": "Anna Smirnova"
    }
  ]
}

Чтобы добраться до значения “Ivan Petrov” в XML, укажем следующий путь XPath:

/users/user[1]/text()

На языке JSON Path выглядит иначе:

$.users[0].name

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

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

users.0.id   101
users.0.age  33
users.0.name Ivan Petrov

users.1.id   135
users.1.age  41
users.1.name Andrey Ivanov

users.2.id   399
users.2.age  41
users.2.name Anna Smirnova

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

Идея JSON Path в том, чтобы на любой платформе путь к элементу выглядел одинаково. В настоящий момент пути JSON работают в Postgres, Microsoft SQL Server, Oracle, а также документных базах вроде OpenSearch. У каждой реализации свои особенности, однако в целом они похожи.

В случае с Postgres у языка JSON Path есть прародитель под названием Jsquery. Просим читателя не путать его с библиотекой jQuery для JavaScript: разница во второй букве s. Jsquery решает ту же задачу: упрощенно описывает путь к элементам, которые нужно извлечь. Изначально Jsquery спонсировался фирмой Wargaming в период активной работы над Глобальной Картой. Это пошаговая игра с обширным состоянием, которое включает сведения о кланах, игроках, технике, положении фишек на карте и многое другое. Состояние игры хранилось в виде JSON в базе данных. Приходилось часто запрашивать его подмножество: какие игроки остались в игре, какие локации захвачены, какие свободны и так далее. Чтобы не выгружать документ целиком, в Wargaming пользовались расширением Jsquery, разработанным в PostgresPro.

Сегодня это расширение встроено в поставку PostgresPro; в обычном Postgres его устанавливают отдельно. Далее по тексту мы обсуждаем только классический JSON Path, потому что он доступен в Postgres по умолчанию. Разобравшись с JSON Path, читатель без труда освоит Jsquery.

Знакомство с JSON Path

Для дальнейших экспериментов подготовим таблицу demo с документом из примера выше:

create table demo(doc jsonb not null);

insert into demo values ($$
{
  "users": [
    {
      "id": 101,
      "age": 33,
      "name": "Ivan Petrov"
    },
    {
      "id": 135,
      "age": 52,
      "name": "Andrey Ivanov"
    },
    {
      "id": 399,
      "age": 41,
      "name": "Anna Smirnova"
    }
  ]
}
$$::jsonb);

Чтобы получить имя первого пользователя, выполним запрос:

select
    jsonb_path_query_first(doc, '$.users.name') as node
from demo;

┌───────────────┐
│     node      │
├───────────────┤
│ "Ivan Petrov" │
└───────────────┘

Разберемся, что здесь происходит. Знак доллара в пути означает ссылку на вершину документа. Каждый следующий уровень отделяется точкой. Лексемы между точками совпадают с именами ключей. Если ключ содержит только символы a-z, A-Z, цифры и подчеркивание, их указывают как есть. В противному случае лексемы экранируют – обрамляют двойными кавычками. Например, в языках семейства Lisp приняты ключи с дефисами: вместо user_id пишут user-id. Подобные ключи записываются так: $.user."user-id". Ключ user не нуждается в кавычках, однако их наличие не будет ошибкой.

Оговоримся, что путь $.users.name охватывает имена всех пользователей, однако функция jsonb_path_query_first выбирает только первый из них (что отражает суффикс _first). Возможны другие подходы, когда элементы возвращаются в виде массива jsonb. Такой результат производит функция jsonb_path_query_array:

select
    jsonb_path_query_array(doc, '$.users.name') as node
from demo;

┌───────────────────────────────────────────────────┐
│                       node                        │
├───────────────────────────────────────────────────┤
│ ["Ivan Petrov", "Andrey Ivanov", "Anna Smirnova"] │
└───────────────────────────────────────────────────┘

Функция jsonb_path_query возвращает таблицу с одним столбцом jsonb; ее можно соединить с другой таблицей, выбрать из нее данные как из подзапроса и так далее. С другими функциями семейства jsonb_path_ читатель ознакомится в документации.

select
    jsonb_path_query(doc, '$.users.name') as node
from demo;

┌─────────────────┐
│      node       │
├─────────────────┤
│ "Ivan Petrov"   │
│ "Andrey Ivanov" │
│ "Anna Smirnova" │
└─────────────────┘

Виды путей

Одна из особенностей JSON Path в следующем: путь к элементу может быть строгим или нет. В английском языке для этого используют термины strict и lax. Последнее переводится как “расслабленный” или “вялый”. Будем называть такой путь нестрогим. Тип пути указывают в самом начале. Это строгий путь:

strict $.path.to.node

, а это нет:

lax $.path.to.node

По умолчанию путь считается нестрогим (lax).

Разница между ними в том, что происходит, когда путь выходит за границы документа. Предположим, по ошибке мы составили путь, которого нет в документе. Пусть это будет $.hello.test. Если задать ему тип strict, при попытке извлечь элемент получим ошибку:

select
    jsonb_path_query(doc, 'strict $.hello.test') as node
from demo;

-- ERROR:  JSON object does not contain key "hello"

Если же пусть нестрогий (lax), поиск элемента окончится, как только мы вышли за границы документа. При этом ошибки не будет, и функция вернет null. Уточним – именно стандартный NULL, а не null-значение JSON:

select
    jsonb_path_query(doc, 'lax $.hello.test') as node
from demo;

-- null

Синтаксис field[index] указывает на элемент массива, при этом index должен быть неотрицательным числом. Отрицательные индексы вроде -1 для доступа с конца массива не работают. Звездочка на месте индекса означает все элементы массива; подобный путь описывает уже не один, а множество элементов.

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

select
    jsonb_path_query(doc, 'strict $.users[*].id') as node
from demo;

┌──────┐
│ node │
├──────┤
│ 101  │
│ 135  │
│ 399  │
└──────┘

Аналогичный результат вернет нестрогий путь lax $.users.id или просто $.users.id. В некоторых случаях строгость бывает важна, и ниже мы рассмотрим, когда именно.

Раскрытие массивов

Как видно из последнего примера, нестрогие пути автоматически раскрывают массивы. Вместо users[*] мы указали users; Postgres определил, что это массив и применил следующее поле id ко всем элементам. Запись удобна краткостью: не нужно явно указывать, где объекты, а где массивы. Объекты и массивы могут чередоваться произвольно с одним исключением: нелья, чтобы два массива следовали один за другим. Другими словами, нестрогий путь не работает с массивом массивов. Приведем слегка надуманный пример, где строгий путь сработает:

select jsonb_path_query($$
{
  "matrix": [
    [{"id": 1}, {"id": 2}, {"id": 3}],
    [{"id": 4}, {"id": 5}, {"id": 6}],
    [{"id": 7}, {"id": 8}, {"id": 9}]
  ]
}
$$, 'strict $.matrix[*][*].id') as x;

┌───┐
│ x │
├───┤
│ 1 │
│ 2 │
│ 3 │
│ 4 │
│ 5 │
│ 6 │
│ 7 │
│ 8 │
│ 9 │
└───┘

, а нестрогий – нет:

select jsonb_path_query($$
{
  "matrix": [
    [{"id": 1}, {"id": 2}, {"id": 3}],
    [{"id": 4}, {"id": 5}, {"id": 6}],
    [{"id": 7}, {"id": 8}, {"id": 9}]
  ]
}
$$, 'lax $.matrix.id') as x;

-- (0 rows)

Отметим, что массив массивов – в целом не очень удобная структура данных. Она подходит разве что для числовых матриц; в остальных случаях ее заменяют на массив объектов.

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

Индекс с поддержкой путей

В главе 4 мы говорили об индексации всего json-документа. Напомним, мы использовали индекс GIN с опцией jsonb_ops (если ее опустить, она применится по умолчанию):

create index if not exists
idx_applications_doc_gin_jsonb_ops
on applications using gin
(doc jsonb_ops);

После этого оператор вхождения @> подхватывал индекс, что мы и видели в плане запроса.

Если указать в свойствах индекса jsonb_path_ops, он строится слегка по-иному. Наиболее важное отличие в том, что новый индекс поддерживает операторы @? и @@. Эти операторы принимают пути JSON, чтобы проверить их наличие или сравнить значение документа с переданным. Удалим прошлый индекс и построим новый:

drop index if exists idx_applications_doc_gin_jsonb_ops;

create index if not exists
idx_applications_doc_gin_jsonb_path_ops
on applications using gin
(doc jsonb_path_ops);

Оператор @? проверяет, есть ли в документе указанный путь. Результат будет истиной или ложью. Путь существует, если найдется хотя бы один элемент, который ему подходит (напомним, путь может описывать несколько элементов). Чтобы это продемонстрировать, добавим к произвольной заявке вложенное поле:

update applications
set doc['foo']['bar']['baz'] = to_jsonb(123)
where id = '00000000-0000-0000-0000-000000000070';

Если искать документы по новому пути, именно эту заявку мы и получим:

select id from applications
where doc @? 'lax $.foo.bar.baz'
limit 10;

┌─[ RECORD 1 ]──────────────────────────────┐
│ id │ 00000000-0000-0000-0000-000000000070 │
└────┴──────────────────────────────────────┘

Оператор @@ действует схожим образом, но принимает не путь, а предикат. В нем путь сравнивается с каким-то значением. Типичный пример – найти документ, где вложенное значение равно заданному. План подтверждает, что новый индекс используется:

explain analyze
select id from applications
where doc @@ 'lax $.departments.users.email == "user_65@test.com" '
limit 10;

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                         QUERY PLAN                                                                          │
├─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=90.20..126.64 rows=10 width=16) (actual time=1.703..1.747 rows=10 loops=1)                                                                     │
│   ->  Bitmap Heap Scan on applications  (cost=90.20..36325.58 rows=9943 width=16) (actual time=1.702..1.744 rows=10 loops=1)                                │
│         Recheck Cond: (doc @@ '($."departments"."users"."email" == "user_65@test.com")'::jsonpath)                                                          │
│         Heap Blocks: exact=10                                                                                                                               │
│         ->  Bitmap Index Scan on idx_applications_doc_gin_jsonb_path_ops  (cost=0.00..87.71 rows=9943 width=0) (actual time=0.901..0.902 rows=3000 loops=1) │
│               Index Cond: (doc @@ '($."departments"."users"."email" == "user_65@test.com")'::jsonpath)                                                      │
│ Planning Time: 0.113 ms                                                                                                                                     │
│ Execution Time: 1.770 ms                                                                                                                                    │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

select id from applications
where doc @@ 'lax $.created_by.name == "User 0999"'
limit 10;

select id from applications
where doc @@ 'lax $.application_id == 1513 '
limit 10;

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

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

select id from applications
where doc @@ '$.created_by.id == $.departments.users.id'
limit 10;

Автор признает, что операторы @? и @@ легко перепутать и получить странные результаты. Остается только запомнить: @@ принимает путь с предикатом (равно, больше, меньше и так далее), а @? – обычный путь, возможно с подзапросом. О подзапросах мы поговорим ближе к концу главы.

Методы и операторы JSON Path

Кроме операторов, JSON Path предлагает несколько удобных функций. Большинство из них выглядит как методы, потому что вызываются из последнего элемента пути через точку. Например, метод .size() вернет число элементов массива. С его помощью находят массивы, чей размер превышает заданный.

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

update applications
set doc['departments'][1]['users'][2] = $$
{
  "id": "00000000-0000-0000-0000-000000009999",
  "name": "User 9999",
  "role": "manager",
  "email": "user_9999@test.com"
}
$$::jsonb
where id = '00000000-0000-0000-0000-000000000065';

Теперь условие ...users.size() > 2 вернет заявку 65:

select id from applications
where doc['departments'] @@ '$.users.size() > 2 '
limit 10;

┌──────────────────────────────────────┐
│                  id                  │
├──────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000000065 │
└──────────────────────────────────────┘

С сожалением отметим, что .size() работает с массивом, но не объектом. Чтобы узнать размер объекта (число ключей в нем), его приводят к массиву методом .keyvalue(). Каждый его элемент – объект с ключами key, value и id (порядковым номером):

select jsonb_path_query($$
{
  "users": {
    "101": {"name": "Ivan"},
    "123": {"name": "John"},
    "523": {"name": "Johann"}
  }
}
$$::jsonb, '$.users.keyvalue()') as node;

┌───────────────────────────────────────────────────────┐
│                         node                          │
├───────────────────────────────────────────────────────┤
│ {"id": 20, "key": "101", "value": {"name": "Ivan"}}   │
│ {"id": 20, "key": "123", "value": {"name": "John"}}   │
│ {"id": 20, "key": "523", "value": {"name": "Johann"}} │
└───────────────────────────────────────────────────────┘

Итоговый размер объекта мы узнаем цепочкой методов $.users.keyvalue().size().

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

select id from applications
where doc @@ '$.departments.users.name like_regex "^user 12[0-9]{1}$" flag "i"'
limit 10;

┌──────────────────────────────────────┐
│                  id                  │
├──────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000008129 │
│ 00000000-0000-0000-0000-000000009100 │
│ 00000000-0000-0000-0000-000000009101 │
│ 00000000-0000-0000-0000-000000009102 │
│ 00000000-0000-0000-0000-000000009103 │
│ 00000000-0000-0000-0000-000000009104 │
│ 00000000-0000-0000-0000-000000009105 │
│ 00000000-0000-0000-0000-000000009106 │
│ 00000000-0000-0000-0000-000000009107 │
│ 00000000-0000-0000-0000-000000009108 │
└──────────────────────────────────────┘

Флаги регулярного выражения – это подсказки о том, как его интерпретировать. Наиболее полезны из них “i” и “q”. Первый (insensitive) означает, что выражение игнорирует регистр символов. Как правило, регистр действительно не важен: нам интересны все варианты записи (строчными и прописными буквами), поэтому флаг добавляют к выражению. Второй флаг q (quoted) означает, что служебные символы читаются как есть – у них нет особой семантики. Так, с флагом q символы \d означают буквально обратную косую черту и букву d, а не любую цифру. Флаг quoted необходим, когда выражение приходит со стороны и ему нельзя доверять.

Огорчим читателя тем, что оператор like_regex не использует индекс. В общих случаях индекс работает с операторами равенства и сравнения, а именно <, <=, ==, =>, >. Более сложные операторы вроде like_regex, увы, провоцируют линейный обход таблицы. В случае с заявками запрос будет особо долгим, потому что их миллион. Таким образом like_regex не снимает проблему поиска по вхождению строки, которую мы решали при помощи триграммного индекса. Используйте этот оператор только для служебных нужд.

JSON Path поддерживает и другие операторы и методы. Предлагаем читателю ознакомиться с ними в документации.

Пути со звездочками

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

select jsonb_path_query($$
{
  "users": {
    "101": {"name": "Ivan"},
    "123": {"name": "John"},
    "523": {"name": "Johann"}
  }
}
$$::jsonb, '$.users.*.name') as name;

┌──────────┐
│   name   │
├──────────┤
│ "Ivan"   │
│ "John"   │
│ "Johann" │
└──────────┘

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

select jsonb_path_query($$
{
  "users": {
    "101": {"name": "Ivan", "friends": {"991": {"name": "Anna"}, "523": {"name": "Kirill"}}},
    "123": {"name": "John", "friends": {"353": {"name": "Gleb"}, "566": {"name": "Petr"}}},
    "523": {"name": "Johann", "friends": {"834": {"name": "Marina"}, "235": {"name": "Galina"}}}
  }
}
$$::jsonb, '$.users.**.name') as name;

┌──────────┐
│   name   │
├──────────┤
│ "Ivan"   │
│ "Kirill" │
│ "Anna"   │
│ "John"   │
│ "Gleb"   │
│ "Petr"   │
│ "Johann" │
│ "Galina" │
│ "Marina" │
└──────────┘

Двойную звездочку не используют в промышленном коде, потому что подобный поиск дорогой. Кроме того, путь может раскрыть данные, не предназначенные клиентам. Чаще всего двойную звездочку применяют для администрирования. Предположим, кто-то из разработчиков пожаловался, что документ содержит дату в неверном формате: 01-02-2025. Какому документу она принадлежала и в какой его части находилось, разработчик уже не помнит. Вот как выявить проблемный документ:

$.**.created_at == "01-02-2025"

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

$.**.id == "6c92590b-2daa-487f-a50d-434d34185015"

Составление путей в коде

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

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

import json
import re

dеf needs_quoting(lexem):
    return re.search("[^a-zA-Z0-9_]+", lexem)

dеf maybe_quote(lexem):
    if needs_quoting(lexem):
        return '"%s"' % (lexem, )
    else:
        return lexem

dеf json_path(path, op, value):
    return "$.%s %s %s" % (
        ".".join([
            maybe_quote(part) for part in path
        ]),
        op,
        json.dumps(value)
    )

Функция needs_quoting проверяет, нуждается ли элемент пути в экранировании – обрамлении кавычками. Если в элемент содержит символы, отличные от латинских букв, цифр и подчеркивания, то результат положительный. Функция maybe_quote экранирует элемент, если это необходимо (отсюда префикс maybe). Финальная функция json_path принимает список элементов пути, оператор и значение, которое приводится к JSON. Примеры вызова:

print(json_path(["departments", "users", "email"], "==", "test@test.com"))
# $.departments.users.email == "test@test.com"

print(json_path(["test", "full-name", "is-active?"], "==", True))
# $.test."full-name"."is-active?" == true

Мы построили выражение JSON Path, и нужно передать его в запрос. Здесь возможны два варианта. Первый – передать путь параметром как обычную строку:

query = """
  select id, doc from applications
  where doc @@ ?
  limit 100
"""

path = '$.departments.users.email == "user_65@test.com"'

conn.execute(query, params=(path, ))

Этот способ защищает вас от инъекций и манипуляций с кавычками. Недостаток в том, что некоторые системы пишут в логи запросы без параметров. В результате вы увидите только условие where doc @@ ?, а что было на месте вопроса – неизвестно.

Второй способ в том, чтобы внедрить путь прямо в тело SQL. Чтобы обезопасить себя от инъекций, окружите путь тегами вида $xxx$ , где xxx – случайное выражение. Ниже для ясности мы выбрали тег $jsonpath$ . Напомним, что внутри двойных долларов любые символы читаются как есть.

select id, doc from applications
where doc @@ $jsonpath$$.departments.users.email == "user_65@test.com"$jsonpath$
limit 10;

Можно расширить вашу ORM, чтобы код ниже

Applications.objects.filter(doc__atat=(["attrs", "application_id"], "==", 12345))

разворачивался в следующее условие:

where doc @@ '$.attrs.application_id == 12345'

В случае с Django вам поможет следующий шаблон:

from django.db.models import Lookup
from django.db.models import Field

class JsonbAtAt(Lookup):
    lookup_name = "atat"

    dеf as_sql(self, compiler, connection):
        ...
        return "%s @@ %s" % (column, path), params

Field.register_lookup(JsonbAtAt)

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

Подзапросы

Рассмотрим еще одну возможность JSON Path, которую до сих пор избегали – подзапросы. Чтобы материал был понятней, подберем такой документ и требование, которое нельзя выполнить без подзапросов.

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

"departments": [
  {
    "id": "00000000-0000-0000-0000-000000000005",
    "code": "dep_5",
    "name": "Department 5",
    "users": [
      {
        "id": "00000000-0000-0000-0000-000000000055",
        "name": "User 55",
        "role": "support",
        "email": "user_55@test.com"
      },
      {
        "id": "00000000-0000-0000-0000-000000000065",
        "name": "User 65",
        "role": "decision-maker",
        "email": "user_65@test.com"
      }
    ]
  },
  {
    "id": "00000000-0000-0000-0000-000000000015",
    "code": "dep_15",
    "name": "Department 15",
    "users": [
      {
        "id": "00000000-0000-0000-0000-000000000075",
        "name": "User 75",
        "role": "support",
        "email": "user_75@test.com"
      },
      {
        "id": "00000000-0000-0000-0000-000000000035",
        "name": "User 35",
        "role": "decision-maker",
        "email": "user_35@test.com"
      }
    ]
  }
]

Требование в том, чтобы найти документы, над которыми работал пользователь с кодом X в роли Y, например 65 и support.

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

select id from applications
where
    doc @@ '$.departments.users.id == "00000000-0000-0000-0000-000000000065"'
and doc @@ '$.departments.users.role == "support"'
limit 10;

┌──────────────────────────────────────┐
│                  id                  │
├──────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000001045 │
│ 00000000-0000-0000-0000-000000002045 │
│ 00000000-0000-0000-0000-000000003045 │
│ 00000000-0000-0000-0000-000000003055 │
│ 00000000-0000-0000-0000-000000006045 │
│ 00000000-0000-0000-0000-000000007055 │
│ 00000000-0000-0000-0000-000000011065 │
│ 00000000-0000-0000-0000-000000013045 │
│ 00000000-0000-0000-0000-000000016045 │
│ 00000000-0000-0000-0000-000000021055 │
└──────────────────────────────────────┘

Какие-то данные мы получили, однако верны ли они? Изучим первую заявку с номером 1045, точнее ее поле departments. Вот что в ней содержится:

"departments": [
  {
    "id": "00000000-0000-0000-0000-000000000005",
    "code": "dep_5",
    "name": "Department 5",
    "users": [
      {
        "id": "00000000-0000-0000-0000-000000000055",
        "name": "User 55",
        "role": "support",
        "email": "user_55@test.com"
      },
      {
        "id": "00000000-0000-0000-0000-000000000065",
        "name": "User 65",
        "role": "decision-maker",
        "email": "user_65@test.com"
      }
    ]
  }
]

Обратите внимание: у пользователя 65 роль decision-maker, а не support. Роль support, напротив, принадлежит пользователю 55. Почему же заявка попала в результат?

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

doc @@ '$.departments.users.id == "00000000-0000-0000-0000-000000000065"'

Такое значение есть, и оно находится по пути departments[0].users[1].id. Теперь второе условие:

doc @@ '$.departments.users.role == "support"'

Этот путь тоже встречается в документе и равен departments[0].users[0].role. Оба условия были истинны, а остальное очевидно: объединение AND было тоже истинным, поэтому мы получили документ. С точки зрения Postgres ошибок не было; проблема в том, что мы неверно запросили данные.

Сделать это нужно по-другому, в два этапа. На первом шаге составляют минимальный общий путь. Для обоих путей $.departments.users.id и $.departments.users.role он равен $.departments.users.

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

Алгоритм, что мы описали, называется подзапросом JSON Path – не путайте его с подзапросами SQL. Вот как его выразить:

select id from applications
where
    doc @? '$.departments.users ? (@.id == "00000000-0000-0000-0000-000000000065" && @.role == "support")'
limit 10;

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

Также обратите внимание, что для путей с подзапросом используется оператор @?, а не @@. Это весьма неочевидное требование. Дело в том, что @@ служит только для путей с предикатом, а подзапрос предикатом не является, даже если содержит сравнение и другие логические операторы.

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

отфильтровать департаменты по коду;
выбрать их пользователей;
отфильтровать пользователей по номеру и роли.

Путь на языке JSONPath:

select id from applications
where
    doc @? '$.departments[*] ? (@.code == "dep_5") .users ? (@.id == "00000000-0000-0000-0000-000000000065" && @.role == "support")'
limit 10;

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

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                 QUERY PLAN                                                                                  │
├─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=137.69..174.12 rows=10 width=16) (actual time=5.307..5.412 rows=10 loops=1)                                                                                    │
│   ->  Bitmap Heap Scan on applications  (cost=137.69..36533.88 rows=9990 width=16) (actual time=5.303..5.407 rows=10 loops=1)                                               │
│         Recheck Cond: (doc @? '$."departments"[*]?(@."code" == "dep_5")."users"?(@."id" == "00000000-0000-0000-0000-000000000065" && @."role" == "support")'::jsonpath)     │
│         Rows Removed by Index Recheck: 21                                                                                                                                   │
│         Heap Blocks: exact=31                                                                                                                                               │
│         ->  Bitmap Index Scan on idx_applications_doc_gin_jsonb_path_ops  (cost=0.00..135.19 rows=9990 width=0) (actual time=5.199..5.199 rows=470 loops=1)                 │
│               Index Cond: (doc @? '$."departments"[*]?(@."code" == "dep_5")."users"?(@."id" == "00000000-0000-0000-0000-000000000065" && @."role" == "support")'::jsonpath) │
│ Planning Time: 0.170 ms                                                                                                                                                     │
│ Execution Time: 5.830 ms                                                                                                                                                    │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

Итак, мы рассмотрели язык JSON Path и его основные возможности, предикаты, методы, подзапросы. Мы коснулись лишь малой части того, что описано в документации; предлагаем читателю ознакомиться с ней на официальном сайте. С другой стороны, мы заострили внимание на тех неочевидных моментах, которые даже в документации описаны скупо. Автор надеется, что JSON Path поможет вам в работе со сложными документами. В следующей главе мы рассмотрим еще одну технику, основанную на этом языке.

Глава 5. Ограничения в документах

Fri, 12 Jun 2026 00:00:00 +0000

Главы

Введение в документы
Базовые возможности JSON
JSON в таблицах
Индексирование JSON
Ограничения в документах
Язык путей JSONPath
Отчеты и функции
Функции на языке Python
Версионирование и архивация документов
Релевантный поиск

Содержание

Главы
Ограничение CHECK
Ограничение UNIQUE и уникальный индекс
Ограничение FOREIGN KEY (ссылки)
Прочие сведения

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

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

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

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

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

Ограничение CHECK

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

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

drop index if exists idx_applications_application_id;

Код ниже создаст ограничение с типом CHECK:

alter table applications add constraint ctr_doc_application_id_nn
check (doc->'application_id' is not null);

За выражением ...add constraint следует машинное имя ограничения. Убедитесь, что имя хотя бы примерно сообщает о том, что и как оно проверяет. В нашем случае doc и application_id указывают на колонку и поле документа, а часть nn означает not null. За именем следует тип ограничения (CHECK), а дальше – код, специфичный для конкретного типа. По ходу главы мы рассмотрим и другие виды ограничений.

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

insert into applications (doc) values (
  '{"test": "abc"}'
);

-- ERROR:  new row for relation "applications" violates check constraint "ctr_doc_application_id_nn"
-- DETAIL:  Failing row contains (b6edce9d-285f-4df0-9bba-5f65d390608a, {"test": "abc"}, 2026-06-05 17:49:33.757553+03, null).

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

Улучшим нашу проверку так, чтобы она проверяла, что в поле application_id записано именно число. Однако в прошлых экспериментах мы добавили документы, где поле application_id не было числом. Чтобы удалить их, выполните запрос с выражением на языке JSON Path (мы изучим его в следующей главе):

delete from applications
where doc @@ '$.application_id.type() != "number" ';

Удалите прежнее ограничение:

alter table applications
drop constraint ctr_doc_application_id_nn;

и добавьте новое:

alter table applications add constraint ctr_doc_application_id_int
check ((doc->>'application_id')::int is not null);

Теперь при попытке записать документ с неверным номером получим ошибку:

insert into applications (doc) values (
  '{"application_id": "abc"}'
);

-- ERROR: cannot cast jsonb string to type integer

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

Более удачное решение – проверять документ в приложении до записи в базу. Обычно это делают при помощи JSON-схемы. Библиотеки для работы со схемами есть для всех популярных языков. Храните схемы в отдельном репозитории, чтобы ими могли пользоваться клиенты на Python, Java и других языках. Приведем фрагмент схемы нашей заявки:

{
  "type": "object",
  "properties": {
    "id": {"type": "string", "format": "uuid"},
    "status": {"enum": ["active", "deleted", "pending"]},
    "created_at": {"type": "string", "format": "date-time"},
    "application_id": {"type": "integer"},
    "organization": {...},
    ...
  },
  "required": ["id", "status", "created_at", "..."]
}

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

Ограничение UNIQUE и уникальный индекс

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

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

create table users_demo(
    id integer primary key,
    full_name text not null,
    email text not null,
    unique(email)
);

Уникальная комбинация полезна в таблицах-мостах; такие таблицы связывают другие сущности, например публикацию и тег. Чтобы не допустить случая, когда у статьи два одинаковых тега, комбинацию post_id и tag_id объявляют уникальной:

create table post_tags(
    post_id integer not null,
    tag_id integer not null,
    created_at timestamptz not null default current_timestamp,
    unique (post_id, tag_id)
);

Если вы забыли часть unique в объявлении таблицы, легко добавить ограничение командой:

alter table post_tags
add constraint ctx_post_id_tag_id_u
unique (post_id, tag_id);

Если мы выполним следующий запрос дважды:

insert into post_tags (post_id, tag_id)
values (100, 10);

то во второй раз получим ошибку уникальности:

ERROR:  duplicate key value violates unique constraint "ctx_post_id_tag_id_u"
DETAIL:  Key (post_id, tag_id)=(100, 10) already exists.

Особенность ограничения UNIQUE в том, что оно принимает столбцы, а не произвольные выражения. Не получится создать уникальное ограничение на поле документа. С точки зрения Postgres это неверный синтаксис:

alter table applications
add constraint ctx_doc_application_id_u
unique (((doc->>'application_id')::int));

-- ERROR:  syntax error at or near "("
-- LINE 3: unique (((doc->>'application_id')::int));

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

Удалите из таблицы applications ограничения, что мы создали ранее. Посмотреть их имена можно командой \d+ applications:

Indexes:
    "applications_pkey" PRIMARY KEY, btree (id)
    ...
Check constraints:
    "ctr_doc_application_id_int" CHECK (((doc ->> 'application_id'::text)::integer) IS NOT NULL)

Затем создайте уникальный индекс командой:

create unique index idx_doc_application_id_u
on applications (((doc->>'application_id')::int));

Свойство unique поддерживает только индекс btree. Применить его к индексам GIN или GIST не получится.

В прошлой главе мы уже создали индекс btree для поля application_id под названием idx_applications_application_id. С новым уникальным индексом в нем нет нужды, поэтому удалите его командой drop index.

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

insert into applications (doc) values (
  '{"application_id": "12345"}'
);

-- ERROR:  duplicate key value violates unique constraint "idx_doc_application_id_u"
-- DETAIL:  Key (((doc ->> 'application_id'::text)::integer))=(12345) already exists.

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

insert into applications (doc) values (
  '{"test": "abc"}'
);

-- INSERT 0 1

Почему Postgres пропускает документы без номера? Дело в том, что когда поля application_id нет, выражение doc ->> 'application_id' возвращает NULL. Уникальный индекс устроен так, что каждый NULL не равен другому NULL. Это общая идиома Postgres: NULL считается неизвестностью, а неизвестности нельзя сравнивать.

На поведение NULL можно повлиять, указав опцию индекса nulls not distinct. Удалите прежний индекс и создайте новый:

drop index idx_doc_application_id_u;

create unique index idx_doc_application_id_u
on applications (((doc->>'application_id')::int))
nulls not distinct;

Теперь индекс трактует значения NULL как равные. Получится добавить только один документ без номера, но не больше:

insert into applications (doc) values (
  '{"test": "abc"}'
);

-- OK

insert into applications (doc) values (
  '{"test": "abc"}'
);

-- ERROR:  duplicate key value violates unique constraint "idx_doc_application_id_u"
-- DETAIL:  Key (((doc->>'application_id'::text)::integer))=(null) already exists.

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

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

Чтобы построить подобный индекс, сперва удалим прошлый:

drop index idx_doc_application_id_u;

Подготовим неизменяемую функцию created_at_year. Она принимает документ и возвращает дату из поля created_at, срезанную на начало года:

create or replace function created_at_year(doc jsonb)
returns timestamptz
language sql immutable strict parallel safe
return date_trunc('year', (doc->>'created_at')::timestamp);

Объявим индекс, уникальный по двум критериям:

create unique index idx_doc_app_id_date_u
on applications (
    ((doc->>'application_id')::int),
    (created_at_year(doc))
);

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

insert into applications (doc) values (
  '{"application_id": "10001111", "created_at": "2026-06-05T15:33:55Z"}'
);

insert into applications (doc) values (
  '{"application_id": "10001111", "created_at": "2027-06-05T15:33:55Z"}'
);

Обе вставки сработали без ошибок. Но если повторить один из запросов, операция не пройдет:

insert into applications (doc) values (
  '{"application_id": "10001111", "created_at": "2026-12-05T15:33:55Z"}'
);

-- ERROR:  duplicate key value violates unique constraint "idx_doc_app_id_date_u"
-- DETAIL:  Key (((doc ->> 'application_id'::text)::integer), get_year(doc))=(10001111, 2026-01-01 00:00:00+03) already exists.

Напомним: даже если индекс составной, можно пользоватся его лидирующими элементами, в нашем случае – критерием ((doc->>'application_id')::int). Это значит, что быстрый поиск по номеру по-прежнему в нашем распоряжении. Возможно, вам понадобится другой доступ: сначала за указанный год, а затем по номеру. В этом случае переставьте компоненты индекса местами.

Уникальный индекс дает еще одну возможность: можно указать его в выражении ON CONFLICT при вставке документа. Напишем запрос UPSERT, который реагирует именно на конфликт номера и года, а не другие ограничения:

insert into applications (doc) values (
  '{"application_id": "10001111", "created_at": "2026-12-05T15:33:55Z"}'
) on conflict (
    ((doc->>'application_id')::int),
    (created_at_year(doc))
)
do nothing;

-- INSERT 0 0

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

Обратите внимание, что мы указали выражение индекса, а не его имя. Форма ON CONFLICT ожидает от нас либо имя уникального столбца, либо выражение, по которому построен уникальный индекс. В результате запрос выглядит громоздко. Если вы строете запросы при помощи ORM, поместите выражение индекса в константу.

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

Ограничение FOREIGN KEY (ссылки)

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

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

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

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

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

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

create table organizations (
    id uuid primary key default uuid_generate_v4(),
    doc jsonb compression lz4 not null,
    created_at timestamptz not null default current_timestamp,
    updated_at timestamptz
);

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

delete from applications
where (doc #>> '{organization,id}') is null;

Выберем из заявок уникальные коды организаций:

select distinct doc #>> '{organization,id}' as org_id
from applications
limit 100;

┌──────────────────────────────────────┐
│                org_id                │
├──────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000000000 │
│ 00000000-0000-0000-0000-000000000001 │
│ 00000000-0000-0000-0000-000000000002 │
│ 00000000-0000-0000-0000-000000000003 │
│ 00000000-0000-0000-0000-000000000004 │
│ 00000000-0000-0000-0000-000000000005 │
│ 00000000-0000-0000-0000-000000000006 │
│ 00000000-0000-0000-0000-000000000007 │
│ 00000000-0000-0000-0000-000000000008 │
│ 00000000-0000-0000-0000-000000000009 │
│ 00000000-0000-0000-0000-000000000010 │
│ 00000000-0000-0000-0000-000000000011 │
│ 00000000-0000-0000-0000-000000000012 │

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

select distinct on (doc #>> '{organization,id}')
    (doc #>> '{organization,id}')::uuid as id,
    jsonb_build_object(
        'id',         (doc #>> '{organization,id}'),
        'status',     'active',
        'code',       (doc #>> '{organization,code}'),
        'short_name', (doc #>> '{organization,short_name}')
    ) as doc
from
    applications
limit
    100;

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

┌──────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                  id                  │                                                        doc                                                        │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000000000 │ {"id": "00000000-0000-0000-0000-000000000000", "code": "0", "status": "active", "short_name": "Organization 0"}   │
│ 00000000-0000-0000-0000-000000000001 │ {"id": "00000000-0000-0000-0000-000000000001", "code": "1", "status": "active", "short_name": "Organization 1"}   │
│ 00000000-0000-0000-0000-000000000002 │ {"id": "00000000-0000-0000-0000-000000000002", "code": "2", "status": "active", "short_name": "Organization 2"}   │
│ 00000000-0000-0000-0000-000000000003 │ {"id": "00000000-0000-0000-0000-000000000003", "code": "3", "status": "active", "short_name": "Organization 3"}   │
│ 00000000-0000-0000-0000-000000000004 │ {"id": "00000000-0000-0000-0000-000000000004", "code": "4", "status": "active", "short_name": "Organization 4"}   │
│ 00000000-0000-0000-0000-000000000005 │ {"id": "00000000-0000-0000-0000-000000000005", "code": "5", "status": "active", "short_name": "Organization 5"}   │
│ 00000000-0000-0000-0000-000000000006 │ {"id": "00000000-0000-0000-0000-000000000006", "code": "6", "status": "active", "short_name": "Organization 6"}   │
│ 00000000-0000-0000-0000-000000000007 │ {"id": "00000000-0000-0000-0000-000000000007", "code": "7", "status": "active", "short_name": "Organization 7"}   │
│ 00000000-0000-0000-0000-000000000008 │ {"id": "00000000-0000-0000-0000-000000000008", "code": "8", "status": "active", "short_name": "Organization 8"}   │
│ 00000000-0000-0000-0000-000000000009 │ {"id": "00000000-0000-0000-0000-000000000009", "code": "9", "status": "active", "short_name": "Organization 9"}   │
│ 00000000-0000-0000-0000-000000000010 │ {"id": "00000000-0000-0000-0000-000000000010", "code": "10", "status": "active", "short_name": "Organization 10"} │
│ 00000000-0000-0000-0000-000000000011 │ {"id": "00000000-0000-0000-0000-000000000011", "code": "11", "status": "active", "short_name": "Organization 11"} │
│ 00000000-0000-0000-0000-000000000012 │ {"id": "00000000-0000-0000-0000-000000000012", "code": "12", "status": "active", "short_name": "Organization 12"} │

Предварите запрос командой insert into organizations, удалите limit – и перенос организаций готов. Вот что получилось у автора:

insert into organizations (id, doc)
select distinct on (doc #>> '{organization,id}')
    (doc #>> '{organization,id}')::uuid as id,
    jsonb_build_object(
        'id',         (doc #>> '{organization,id}'),
        'status',     'active',
        'code',       (doc #>> '{organization,code}'),
        'short_name', (doc #>> '{organization,short_name}')
    ) as doc
from
    applications;

Проверьте число организаций – их будет тысяча:

select count(*) from organizations;

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

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

select
    app.id as app_id,
    org.doc->>'code' as org_code,
    org.doc->>'short_name' as org_name
from
    applications app
join
    organizations org
    on (app.doc #>> '{organization,id}')::uuid = org.id
limit
    100;

┌──────────────────────────────────────┬──────────┬──────────────────┐
│                app_id                │ org_code │     org_name     │
├──────────────────────────────────────┼──────────┼──────────────────┤
│ 00000000-0000-0000-0000-000000635585 │ 585      │ Organization 585 │
│ 00000000-0000-0000-0000-000000635586 │ 586      │ Organization 586 │
│ 00000000-0000-0000-0000-000000635587 │ 587      │ Organization 587 │
│ 00000000-0000-0000-0000-000000635588 │ 588      │ Organization 588 │
│ 00000000-0000-0000-0000-000000635589 │ 589      │ Organization 589 │
│ 00000000-0000-0000-0000-000000635590 │ 590      │ Organization 590 │

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

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

Postgres предлагает ограничение FOREIGN KEY – внешний ключ. Оно проверяет, что строка, на которую ссылается поле таблицы, действительно существует. Особенность внешних ключей в том, что они работают только с колонками, а не выражениями. Команда ниже вызовет ошибку синтаксиса, потому что после слов foreign key ожидается колонка или их комбинация, а не выражение:

alter table applications add constraint fk_org_id
foreign key ((doc #>> '{organization,id}')::uuid) references organizations(id);

-- ERROR:  syntax error at or near "("
-- LINE 2: foreign key ((doc #>> '{organization,id}')::uuid) references...

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

Приведем пример: в таблице demo две обычные колонки x и y, а третья sum – вычисляемая, которая складывает x и y. При вставке не нужно беспокоиться о поведении колонки sum – ее согласованность обеспечит Postgres:

create table demo(
    x integer not null default 0,
    y integer not null default 0,
    sum integer generated always as (x + y) stored
);

insert into demo values (1, 2), (3, 4)
returning x, y, sum;

┌───┬───┬─────┐
│ x │ y │ sum │
├───┼───┼─────┤
│ 1 │ 2 │   3 │
│ 3 │ 4 │   7 │
└───┴───┴─────┘

До версии 18 Postgres поддерживал только один вид вычисляемой колонки – хранимый. Выше это свойство задано словом stored. Хранимая колонка вычисляет значение и записывает на диск. При чтении поля sum не происходит обращения к x или y.

С версии 18 доступен второй тип – виртуальный, когда слово stored опущено. Такая колонка не хранит значение, а вычисляет при каждом обращении. Разница подходов очевидна: первый снижает затраты на вычисления, но потребляет диск. Второй не требует диска, но вынуждает Postgres вычислять поле.

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

Независимо от типа – хранимая или виртуальная – вычисляемая колонка доступна только для чтения. Записать в нее данные невозможно.

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

Вычисляемые колонки доступны в индексах и ограничениях. Вынесем поле заявки ((doc #>> '{organization,id}')::uuid) в вычисляемую колонку и наложим на нее ограничение FOREIGN KEY. Первый шаг – подготовка поля:

alter table applications
add column _org_id uuid generated always
as ((doc #>> '{organization,id}')::uuid) stored;

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

Выберем виртуальную колонку в запросе – она ничем не отличается от обычной:

select id, _org_id from applications limit 10;

┌──────────────────────────────────────┬──────────────────────────────────────┐
│                  id                  │               _org_id                │
├──────────────────────────────────────┼──────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000635649 │ 00000000-0000-0000-0000-000000000649 │
│ 00000000-0000-0000-0000-000000635650 │ 00000000-0000-0000-0000-000000000650 │
│ 00000000-0000-0000-0000-000000635651 │ 00000000-0000-0000-0000-000000000651 │
│ 00000000-0000-0000-0000-000000635652 │ 00000000-0000-0000-0000-000000000652 │
│ 00000000-0000-0000-0000-000000635653 │ 00000000-0000-0000-0000-000000000653 │

Наложим ограничение, что колонка ссылается на организацию:

alter table applications add constraint fk_org_id
foreign key (_org_id) references organizations(id);

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

insert into applications (doc) values ($$
  {
    "application_id": 1999111,
    "organization": {
      "id": "967849e5-9c59-4fa2-bc57-0a4a84bbd41c"
    }
  }
$$::jsonb);

-- ERROR:  insert or update on table "applications" violates foreign key constraint "fk_org_id"
-- DETAIL:  Key (_org_id)=(967849e5-9c59-4fa2-bc57-0a4a84bbd41c) is not present in table "organizations".

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

delete from organizations
where id = '00000000-0000-0000-0000-000000000649';

-- ERROR:  update or delete on table "organizations" violates foreign key constraint "fk_org_id" on table "applications"
-- DETAIL:  Key (id)=(00000000-0000-0000-0000-000000000649) is still referenced from table "applications".

В обоих случаях база не выполнила то, что нарушает ограничение.

В теле FOREIGN KEY можно указать реакцию на удаление. Выражение on delete cascade означает, что документы, которые ссылаются на удаляемый, будут тоже удалены. Чтобы проверить это в действии, удалим прошлое ограничение и наложим новое:

alter table applications add constraint fk_org_id
foreign key (_org_id) references organizations(id)
on delete cascade;

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

delete from organizations
where id = '00000000-0000-0000-0000-000000000649';

select id from applications
where (doc #>> '{organization,id}') = '00000000-0000-0000-0000-000000000649';
-- (0 rows)

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

FOREIGN KEY предлагает другой вариант удаления: on delete set null. С ним удаляется только та запись, что мы указали, а ссылкам в других таблицах присваивается NULL. Вспомним, однако, что поле _org_id – вычисляемое, поэтому ему нельзя ничего присвоить. Postgres учитывает этот случай и не позволит создать ограничение:

alter table applications add constraint fk_org_id
foreign key (_org_id) references organizations(id)
on delete set null;

-- ERROR:  invalid ON DELETE action for foreign key constraint containing generated column

Можно решить проблему триггером. Перед удалением организации вызывается функция, которая находит заявки и удаляет в них поле organization. Таким образом DELETE сводится к UPDATE; колонка _org_id будет вычислена повторно и получит значение NULL. Подготовим функцию триггера:

create or replace function fn_applications_org_ref_null()
returns trigger as $$
begin
    update applications
    set doc['organization'] = null
    where (doc #>> '{organization,id}')::uuid = OLD.id;
    return OLD;
end;
$$ language plpgsql;

А вот и сам триггер: он запускает функцию перед удалением организации.

create trigger trg_organizations_before_delete
before delete on organizations
for each row execute function fn_applications_org_ref_null();

Удалим организацию:

delete from organizations
where id = '00000000-0000-0000-0000-000000000651';

Проверим заявку, которая раньше на нее ссылалась. Поля организации пусты, триггер сработал:

select id, _org_id, doc -> 'organization' as org
from applications
where id = '00000000-0000-0000-0000-000000635651';

┌──────────────────────────────────────┬─────────┬──────┐
│                  id                  │ _org_id │ org  │
├──────────────────────────────────────┼─────────┼──────┤
│ 00000000-0000-0000-0000-000000635651 │ <null>  │ null │
└──────────────────────────────────────┴─────────┴──────┘

Прочие сведения

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

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

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

У вычисляемых колонок есть еще одно свойство: индекс по ним работает немного быстрее, чем по выражениям. Как вы помните, индекс btree сопоставляет значение с позицией строки, где оно находится. В редких случаях Postgres проверяет условие повторно, даже если строка найдена. Скажем, мы создали индекс на выражение (((doc #>> '{organization,id}')::uuid)) и выполнили запрос с условием по нему:

select ... where (((doc #>> '{organization,id}')::uuid)) = <UUID>

Чтобы выполнить условие повторно (это случается при нехватке памяти), Postgres читает колонку doc и берет и из нее поле organization→id. Напомним, что при определенном пороге значения jsonb сбрасываются в TOAST-таблицу, где они хранятся в виде фрагментов. Чтобы получить документ, требуется прочитать и соединить все фрагменты. Для больших документов это влечет дисковые операции и время процессора.

Если же индекс создан по полю _org_id, обращение к документу требуется. Тип uuid использует хранение PLAIN (без тостов и сжатия, см. главу 4), поэтому значение находится в основной таблице, а не TOAST. Проверка _org_id = <UUID> выполняется быстрее и потому предпочтительней.

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

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

Глава 4. Индексирование JSON

Mon, 25 May 2026 00:00:00 +0000

Главы

Введение в документы
Базовые возможности JSON
JSON в таблицах
Индексирование JSON
Ограничения в документах
Язык путей JSONPath
Отчеты и функции
Функции на языке Python
Версионирование и архивация документов
Релевантный поиск

Содержание

Главы
Знакомство с EXPLAIN
Простые Btree-индексы
Еще раз о UUID v7
Индексирование полей JSON
Индексирование дат
Коротко о hash-индексе
Статистика индексов
Составные индексы
Поиск по шаблону
Триграммный поиск по многим полям
Коротко о ранжировании
Регулярные выражения
Индексирование документа целиком

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

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

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

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

Индексы встречаются в коде на языках вроде Java или Python. Предположим, есть список пользователей, и нужно искать их по номеру. Чтобы не сканировать список каждый раз, строится словарь вида id->user, и тогда пользователя можно извлечь за константное время. Чтобы построить такой словарь, потребуется один обход. Приведем код на Python:

users = [
    {"id": 101, "name": "Ivan", "age": 14},
    {"id": 202, "name": "John", "age": 34},
    {"id": 303, "name": "Juan", "age": 51},
]

id_to_user = {
    user["id"]: user for user in users
}

user = id_to_user[202]
print(user)
# {'id': 202, 'name': 'John', 'age': 34}

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

id_to_index = {
    user["id"]: i for i, user in enumerate(users)
}

index = id_to_index[202] # 1
user = users[index]
print(user)
# {'id': 202, 'name': 'John', 'age': 34}

Аналогично строятся индексы по другим полям, например имени или электронной почте. В отличие от ID, эти поля не уникальны, поэтому в значениях словаря будет не один элемент, а их список. Ниже индекс name_to_ids показывает, что в системе три пользователя по имени John и кодами 202, 345 и 582.

name_to_ids = {
    'Ivan': [101],
    'John': [202, 345, 582],
}

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

По умолчанию выборка строк устроена линейно. Алгоритм перебирает записи по одной и проверяет, подходит ли она условию WHERE. Если да, запись попадает в итоговую выборку. Чем больше таблица, тем дольше выполняется обход. Ситуация, когда когда запрос проверяет все записи, называется full sequence scan или, на жаргоне специалистов по базам данных, “фул-скан”.

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

Чтобы ускорить поиск в таблице, используют индексы. Реляционные базы чаще всего полагаются на индексы B-tree. Это структура данных, которая связывает значение с номером страницы, где находится строка. Чаще всего значение – колонка, однако может быть и сложным выражением: конкатенацией полей, вызовом функции и так далее.

Индекс B-tree устроен как дерево узлов; в свою очередь узлы делятся на уровни. Если это не самый нижний уровень, узлы хранят значения и ссылки на нижележащие узлы. Нижний уровень, который еще называют листовым, содержит координаты строки – TID, Tuple ID. Эта пара чисел (P, T), где P (page) – номер страницы, а T (tuple) – номер кортежа внутри нее. На схеме ниже показан типичный индекс B-tree:

┌──────────────────────────────────────────────────────────┐
│                           ┌───────────┐                  │
│                           │ Metadata  │                  │
│                           └─────┬─────┘                  │
│                                 │                        │
│ values                    ┌─────▼─────┐                  │
│ lvl 1          ┌──────────│  4 32 64  ├──────────┐       │
│                │          └─────┬─────┘          │       │
│                │                │                │       │
│ values   ┌─────▼─────┐    ┌─────▼─────┐    ┌─────▼─────┐ │
│ lvl 2    │  4 16 25  ◀────▶ 32 43 49  ◀────▶ 64 79 89  │ │
│          └──┬──┬──┬──┘    └──┬──┬──┬──┘    └──┬──┬──┬──┘ │
│             │  │  │          │  │  │          │  │  │    │
│          ┌──▼──▼──▼──┐    ┌──▼──▼──▼──┐    ┌──▼──▼──▼──┐ │
│ page     │104 523 662│    │223 303 315│    │662 824 908│ │
│ tuple    │  5  25  61│    │ 40  23   1│    │ 13  21   7│ │
│          └───────────┘    └───────────┘    └───────────┘ │
└──────────────────────────────────────────────────────────┘

Если требуется найти в таблице строку со значением 25, происходит следующее. Сперва мы оказываемся на первом уровне индекса. Для простоты он содержит всего три значения: 4, 32 и 64, но на практике их гораздо больше. Промышленный индекс содержит два в степени N элементов в одном узле, например 256 или 512, что делает невозможным его реалистичное изображение.

Элементы каждого узла упорядочены. Двоичным поиском находится позиция элемента, за которым следует искомое число. В нашем случае 25 следует за 4; в свою очередь 4 ссылается на левый узел второго уровня. Переходим на этот узел и повторяем алгоритм. Поскольку второй уровень – последний, это гарантирует, что 25 содержится в узле. Так и есть: это третий элемент, и его позицию тоже находят двоичным поиском.

Числу 25 сопоставлена пара: номер страницы (662), где находится искомая строка, и номер строки в этой странице (61). Положение страницы в файле вычислим по номеру: для этого умножим его на 8192 (размер страницы в байтах по умолчанию). Получим смещение в 5.423.104 байта от начала файла. Postgres читает из файла 8 килобайт с найденным смещением – это и есть страница 662.

Страница помещается в буферный кэш; в среднем она содержит 10-50 строк. Чтобы найти среди них нужную, Postgres умножает длину строки (L) на ее номер (61). Длина строки постоянна в рамках таблицы и известна заранее. По полученному смещению Postgres читает L байт, что дает искомую строку.

Это было упрощенное описание Btree-индекса в Postgres; на практике он учитывает множество деталей. Так, узлы листового уровня ссылаются на соседей (горизонтальные стрелки на рисунке выше), чтобы ускорить переход от одного узла к другому во время линейного обхода. Узлы индекса заполняются не полностью, а примерно на 90%, чтобы перестроение дерева случалось реже. Вместе со ссылкой на страницу индекс может хранить дополнительные поля; этот трюк используют для того, чтобы читать данные из индекса без обращения к таблице.

В интернете доступны приложения на Javascript, которые визуализируют устройство Btree. Можно указать размер узла, порог разбиения и другие начальные факторы, после чего добавлять и удалять элементы. При этом на холсте показано дерево узлов с плавными анимациями. Одно из таких приложений доступно по адресу btree.app; предлагаем читателю поработать с ним, чтобы лучше понять устройство Btree.

Индексы бывают разных структур и топологий: кроме btree, Postgres поддерживает hash-индексы, семейство GIN и GiST для типов-коллекций, BRIN для чрезвычайно больших таблиц. Расширение PostGis предлагает пространственные индексы для поиска на плоскости и в пространстве, индексы заполняющей кривой и так далее. Некоторые из них мы рассмотрим в этой и следующих главах. Заинтересованным читателям еще раз порекомендуем книги и документацию компании Postgres Pro, где индексы описаны во всех подробностях.

Знакомство с EXPLAIN

Вспомнив теорию, вернемся к нашему миллиону заявок. Когда мы объявили таблицу applications, для первичного ключа автоматически создался индекс. Каждый раз, когда мы ищем документ по полю id, база обращается к нему. Это легко проверить, предварив запрос командой EXPLAIN. Вот что вернет следующий запрос:

explain
select id, doc from applications
where id = '00000000-0000-0000-0000-000000411999';

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                                       QUERY PLAN                                        │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using applications_pkey on applications  (cost=0.42..8.44 rows=1 width=1729) │
│   Index Cond: (id = '00000000-0000-0000-0000-000000411999'::uuid)                       │
└─────────────────────────────────────────────────────────────────────────────────────────┘

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

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

Если запрос начинается с EXPLAIN, мы получим не данные, которые он бы вернул при обычных обстоятельствах, а план выполнения. План описывает стратегию, которую выбрал сервер, чтобы выполнить запрос. Ключевые его элементы – это таблицы, метод доступа к ним (полное сканирование или при помощи индекса), тип соединения в случае JOIN и многое другое.

План имеет вложенную структуру и в целом повторяет иерархию запроса. Например, если мы выбираем данные из двух подзапросов, в плане будут отдельные узлы для каждого из них, а выше – узел объединения результатов. У каждого узла свои промежуточные показатели; узел выше по иерархии накапливает показатели своих потомков. Приложения вроде PGAdmin показывают план графически.

У команды EXPLAIN могут быть параметры, которые влияют на то, какую информацию мы получим. Чаще всего встречается ANALYZE – с ним команда не только строит план, но и выполняет сам запрос. Без ANALYZE все показатели носят оценочный характер, а с ним – фактический. Мы получим затраты на выполнение каждого узла, количество прочитанных страниц, попадание в буферных кэш и многое другое, в том числе время, потраченное на построение плана и его выполнение.

На тему того, как правильно читать план, написаны многие статьи. Поскольку наша книга посвящена работе с JSON, мы не будем рассматривать EXPLAIN во всех деталях. Перечислим только те моменты, на которых будем заострять внимание. Заинтересованным читателям рекомендуем книги “PostgreSQL 16. Оптимизация запросов” и “PostgreSQL. Профессиональный SQL”, где команда EXPLAIN описана подробно.

Итак, в выводе EXPLAIN ANALYZE нас интересует следующее. Прежде всего это показатель cost, который выражен двумя числами через две точки. В примере выше это cost=0.42..8.44. Cost, что по-английски “стоимость”, описывает затраты на выполнение запроса в абстрактных единицах. Это не секунды и не мегабайты памяти, а условная валюта, в которой сервер оценивает усилия.

Первое число cost означает затраты до момента, пока не поступит первая строка результата. Второе – затраты на получение всех строк. Важно понимать эту разницу. Если мы выберем миллион приложений из базы, второй cost будет высоким, потому что на передачу всех документов уйдет время. Однако первый cost будет мал, потому что отдача данных начнется сразу же. Покажем это на примере:

explain
select id, doc from applications;

┌─────────────────────────────────────────────────────────────────────────┐
│                               QUERY PLAN                                │
├─────────────────────────────────────────────────────────────────────────┤
│ Seq Scan on applications  (cost=0.00..359524.33 rows=965633 width=1729) │
└─────────────────────────────────────────────────────────────────────────┘

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

explain
select id, doc from applications
order by (doc->>'application_id')::int

┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│                                          QUERY PLAN                                          │
├──────────────────────────────────────────────────────────────────────────────────────────────┤
│ Gather Merge  (cost=1000457.74..1094345.26 rows=804694 width=1733)                           │
│   Workers Planned: 2                                                                         │
│   ->  Sort  (cost=999457.72..1000463.59 rows=402347 width=1733)                              │
│         Sort Key: (((doc ->> 'application_id'::text))::integer)                              │
│         ->  Parallel Seq Scan on applications  (cost=0.00..356909.07 rows=402347 width=1733) │
└──────────────────────────────────────────────────────────────────────────────────────────────┘

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

Параметр ANALYZE добавляет в план новый критерий: фактическое время запроса. Это строка Execution Time; в примере ниже она показывает 3.9 миллисекунды:

explain analyze
select id, doc from applications
where id = '00000000-0000-0000-0000-000000411999';

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                            QUERY PLAN                                                             │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using applications_pkey on applications  (cost=0.42..8.44 rows=1 width=1830) (actual time=3.786..3.789 rows=1 loops=1) │
│   Index Cond: (id = '00000000-0000-0000-0000-000000411999'::uuid)                                                                 │
│ Planning Time: 0.179 ms                                                                                                           │
│ Execution Time: 3.906 ms                                                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Чем меньше этот показатель, тем лучше. Трудно обозначить порог, выше которого запрос считается медленным – это зависит от его природы и требований. В идеале запросы вида get-by-id (штучная запись по ключу) укладываются в несколько десятков миллисекунд (10-20), а выборка разумного числа записей по индексу – в несколько сотен (100-300). Однако эти числа условны и могут быть пересмотрены.

У сервера Postgresql есть особенность, которую, возможно, вы замечали. Если выполнить запрос дважды, во второй раз он сработает быстрее. Разница значительна: иной раз она составляет порядок, например: сначала 3 секунды, а затем 300 миллисекунд.

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

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

explain (analyze, buffers)
select id, doc from applications
where id = '00000000-0000-0000-0000-000000411999';

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                            QUERY PLAN                                                             │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using applications_pkey on applications  (cost=0.42..8.44 rows=1 width=1830) (actual time=2.820..2.824 rows=1 loops=1) │
│   Index Cond: (id = '00000000-0000-0000-0000-000000411999'::uuid)                                                                 │
│   Buffers: shared read=4                                                                                                          │
│ Planning Time: 0.750 ms                                                                                                           │
│ Execution Time: 2.957 ms                                                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                            QUERY PLAN                                                             │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using applications_pkey on applications  (cost=0.42..8.44 rows=1 width=1830) (actual time=0.054..0.055 rows=1 loops=1) │
│   Index Cond: (id = '00000000-0000-0000-0000-000000411999'::uuid)                                                                 │
│   Buffers: shared hit=4                                                                                                           │
│ Planning Time: 0.105 ms                                                                                                           │
│ Execution Time: 0.070 ms                                                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Отличие в строках shared read=4 и shared hit=4. Слово “read” означает “прочитано” (с диска), а “hit” (“попадание”) – удачный поиск в буферном кэше. Обратите внимание, что второй запрос отработал в 40 раз быстрее – вот какое ускорение дает буферный кэш.

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

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

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

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

Еще один важный показатель EXPLAIN – метод доступа к таблице. Когда в запросе не участвует индекс, метод равен “Full Scan” – полное сканирование. Этих случаев мы стараемся избежать. Выражение Index Scan означает, что обход совершен с помощью индекса. При этом указано его имя и показатели, например число прочитанных страниц.

Сканирование индекса тоже бывает разным: кроме обычного “Index Scan” встречается “Index Only Scan”. Этот метод означает, что данные взяты из индекса без обращения к диску. Метод Bitmap Index Scan подразумевает два действия: в первый раз строится битовая карта страниц, которые подходят условию. Битовая карта – это массив, где бит с номером N означает какой-то признак, например подходит запись условию или нет. Карт может быть несколько: для условия where field1 = 'abc' and field2 = 'xyz' могут быть построены две отдельных карты. Далее они объединяются битовым AND, и по итоговой карте обходится основная таблица.

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

Мы поверхностно рассмотрели вывод EXPLAIN и что нас в нем интересует. Вернемся к главной теме главы – работе с индексами.

Простые Btree-индексы

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

create index if not exists idx_applications_created_at
on applications
using btree (created_at desc);

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

analyze applications;

Эта команда обновляет статистику: строит гистограмму (распределение) значений и выделяет те, что встречаются часто. Статистика крайне важна для построения плана. Иногда запрос не использует индекс, потому что данные изменились (был крупный UPDATE), а статистика все еще содержит старые показатели. Postgres обновляет статистику по расписанию, но мы вызвали команду явно. Предполагается, что после каждого действия над индексом вы тоже вызываете ANALYZE.

Убедимся, что индекс работает. Для этого выберем 100 последних документов и проверим план. Выражение Index Scan показывает, что мы попали в индекс:

explain
select id, doc from applications
order by created_at desc
limit 100;

┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                     QUERY PLAN                                                     │
├────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=0.42..37.19 rows=100 width=1736)                                                                      │
│   ->  Index Scan using idx_applications_created_at on applications  (cost=0.42..368293.21 rows=1001719 width=1736) │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Вариант с диапазоном: ограничим время создания документа каким-то днем. Для этого служит оператор between, где левое и правое значения – границы:

explain
select id, doc from applications
where created_at between '2025-07-30 00:00:00Z' and '2025-07-30 23:59:59Z'
order by created_at desc;

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                        QUERY PLAN                                                                         │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using idx_applications_created_at on applications  (cost=0.42..10918.55 rows=2711 width=1738)                                                  │
│   Index Cond: ((created_at >= '2025-07-30 03:00:00+03'::timestamp with time zone) AND (created_at <= '2025-07-31 02:59:59+03'::timestamp with time zone)) │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

('2025-07-30'::timestamptz)
('2025-07-30'::timestamptz + interval '1 day' - interval '1 second')

В первом случае мы приводим дату к типу timestamptz, во втором – прибавляем день и вычитаем секунду.

Обратите внимание, что мы создали индекс в режиме по убыванию (слово desc после created_at). Мы выбрали этот способ, потому что чаще всего в работе нужны последние документы. Это упрощает работу сервера: если направления индекса и сортировки запроса совпадают (оба asc или оба desc), индекс обходится в прямом порядке. Если нет, то с конца.

При создании индекса мы указали тип btree. Этого можно было не делать, потому что btree является типом по умолчанию; все же мы оставили его для ясности. Postgresql поддерживает многие виды индексов, каждый со своими особенностями. При создании индекса важно понимать, почему выбран тот или иной тип и какие возможности он предлагает.

Как мы упоминали, индекс btree устроен как сбалансированное дерево узлов. Элементы добавляются в узлы так, чтобы при обходе индекса он выглядит как упорядоченный список. Ключевая особенность btree в том, что он поддерживает операторы <, <=, =, =>, > (для краткости – больше, меньше и равно). Такой индекс находит точное значение, а также значения меньше или больше указанного.

Если для поля создан индекс btree, вот какие возможности он дает в запросах:

поиск по точному значению (оператор =);
сортировка по возрастанию и убыванию (order by ... asc/desc);
поиск по условию “меньше” и “больше” (<, <=, >, =>);
отбор по диапазону (оператор between).

Во всех случаях мы попадем в индекс, если, конечно, нет причин, которые этому препятствуют.

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

Еще раз о UUID v7

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

Первый индекс по id служит для поиска документов по ключу. Предполагается, что ключ нам известен, и мы получаем по нему документ. Для краткости такие запросы называют “get by id”. При этом сортировка документов по ключу не имеет смысла: каждый из них случаен, поэтому строки идут вразнобой.

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

00000000-0000-0000-0000-000000411997
00000000-0000-0000-0000-000000411998
00000000-0000-0000-0000-000000411999

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

f1f0a631-a393-47d6-be8d-e082222a9b9a
d108a560-98a4-4c6a-b63e-d4d4f90cc3f7
b5efc9a5-8d27-44e6-a5d8-d81c519820fa

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

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

Хорошая новость в том, что UUID версии 7 совмещает обе возможности. Это по-прежнему уникальный идентификатор, который указывает на конкретный документ. А поскольку первые его 48 бит – время (число миллисекунд эпохи Unix), идентификатор поддается сортировке: каждый следующий больше предыдущего.

Схематично UUID v7 представлен ниже. Его лидирующая часть – число микросекунд эпохи Unix. Автор произвел три идентификатора, и временная метка каждый раз увеличивалась.

┌─────────────────────┬───────┬───────────────┐
│Unix timestamp, ms   │Seq    │Random part    │
├─────────────────────┼───────┼───────────────┤
│1778344072736        │1      │6AC83E922      │
├─────────────────────┼───────┼───────────────┤
│1778344106125        │3      │7C4C36B36      │
├─────────────────────┼───────┼───────────────┤
│1778344112067        │2      │7A42AC302      │
└─────────────────────┴───────┴───────────────┘

После времени Unix несколько бит выделено под счетчик в рамках одной миллисекунды. Современные компьютеры столь быстры, что производят сотни идентификаторов за одну миллисекунду. Если заполнить оставшиеся биты случайно, теряется упорядоченность – ключевое свойство алгоритма. Чтобы упорядочить идентификаторы, в рамках каждой миллисекунды запускается счетчик. Скажем, если в момент времени 1778344106125 приложение произвело четыре идентификатора, то у последнего в поле seq будет записано число 3 (если считать от нуля). Оставшиеся после счетчика биты заполняются случайно (поле Random part).

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

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

Алгоритм UUID v7 появился в Postgres с версии 18, которая вышла осенью 2025 года. Если вы еще не обновились, возможны следующие варианты:

установите стороннее расширение pg_uuidv7;
создавайте идентификаторы в приложении силами Python, Java и других языков;
напишите функцию на встроенном языке Postgres. Примеры и обсуждение доступны в фрагменте gist по ссылке.

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

create table uuid_v7_demo(
    id uuid not null primary key,
    created_at timestamptz not null
);

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

insert into uuid_v7_demo
select
    uuidv7(interval '-1 day' * x),
    current_timestamp + interval '-1 day' * x
from
    generate_series(1, 9999) as seq(x);

Без параметров функция uuidv7 производит идентификатор с текущим временем. Можно передать интервал (в том числе отрицательный), который играет роль смещения. Запрос производит десять тысяч записей, при этом из created_at вычитается день, два и так далее. То же самое касается ключа: при каждой генерации от текущей метки Unix timestamp отнимается нарастающий интервал. Если выбрать строки по возрастанию ключа, порядок будет согласован с датой создания:

select * from uuid_v7_demo
order by id limit 100;

┌──────────────────────────────────────┬───────────────────────────────┐
│                  id                  │          created_at           │
├──────────────────────────────────────┼───────────────────────────────┤
│ 00d4e887-b56f-7584-9190-d522f266d4bf │ 1998-12-23 20:31:14.630735+03 │
│ 00d4edae-116f-757d-a295-7f89e12c8bda │ 1998-12-24 20:31:14.630735+03 │
│ 00d4f2d4-6d6f-7575-b5d0-621727a083ed │ 1998-12-25 20:31:14.630735+03 │
│ 00d4f7fa-c96f-756c-999d-2c22d558596e │ 1998-12-26 20:31:14.630735+03 │
│ 00d4fd21-256f-7567-8158-5acbfc067301 │ 1998-12-27 20:31:14.630735+03 │
│ 00d50247-816f-755d-8377-c12809f0a1c3 │ 1998-12-28 20:31:14.630735+03 │
│ 00d5076d-dd6f-7550-b939-7c10f9f9ce5f │ 1998-12-29 20:31:14.630735+03 │
│ 00d50c94-396f-754d-bb77-9d663b4f31ea │ 1998-12-30 20:31:14.630735+03 │
│ 00d511ba-956f-7544-a16d-e9c7f8613f04 │ 1998-12-31 20:31:14.630735+03 │
│ 00d516e0-f16f-753e-8a0d-1854d65ae69e │ 1999-01-01 20:31:14.630735+03 │

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

select
    *,
    uuid_extract_timestamp(id) as ts
from uuid_v7_demo
order by id limit 100;

┌──────────────────────────────────────┬───────────────────────────────┬────────────────────────────┐
│                  id                  │          created_at           │             ts             │
├──────────────────────────────────────┼───────────────────────────────┼────────────────────────────┤
│ 00d4e887-b56f-7584-9190-d522f266d4bf │ 1998-12-23 20:31:14.630735+03 │ 1998-12-23 20:31:14.671+03 │
│ 00d4edae-116f-757d-a295-7f89e12c8bda │ 1998-12-24 20:31:14.630735+03 │ 1998-12-24 20:31:14.671+03 │
│ 00d4f2d4-6d6f-7575-b5d0-621727a083ed │ 1998-12-25 20:31:14.630735+03 │ 1998-12-25 20:31:14.671+03 │
│ 00d4f7fa-c96f-756c-999d-2c22d558596e │ 1998-12-26 20:31:14.630735+03 │ 1998-12-26 20:31:14.671+03 │
│ 00d4fd21-256f-7567-8158-5acbfc067301 │ 1998-12-27 20:31:14.630735+03 │ 1998-12-27 20:31:14.671+03 │
│ 00d50247-816f-755d-8377-c12809f0a1c3 │ 1998-12-28 20:31:14.630735+03 │ 1998-12-28 20:31:14.671+03 │
│ 00d5076d-dd6f-7550-b939-7c10f9f9ce5f │ 1998-12-29 20:31:14.630735+03 │ 1998-12-29 20:31:14.671+03 │
│ 00d50c94-396f-754d-bb77-9d663b4f31ea │ 1998-12-30 20:31:14.630735+03 │ 1998-12-30 20:31:14.671+03 │
│ 00d511ba-956f-7544-a16d-e9c7f8613f04 │ 1998-12-31 20:31:14.630735+03 │ 1998-12-31 20:31:14.671+03 │
│ 00d516e0-f16f-753e-8a0d-1854d65ae69e │ 1999-01-01 20:31:14.630735+03 │ 1999-01-01 20:31:14.671+03 │
│ 00d51c07-4d6f-7536-af14-ebc968cfa7b4 │ 1999-01-02 20:31:14.630735+03 │ 1999-01-02 20:31:14.671+03 │

Предположим, требуется выбрать записи за два месяца назад относительно текущего дня. Для этого заключите id в оператор between, где левая граница – ключ с интервалом '-3 months', а второй – '-2 months':

select * from uuid_v7_demo
where id between
    uuidv7(interval '-3 months')
    and
    uuidv7(interval '-2 months')
order by id
limit 100;

┌──────────────────────────────────────┬───────────────────────────────┐
│                  id                  │          created_at           │
├──────────────────────────────────────┼───────────────────────────────┤
│ 019c489b-7949-7d87-aa8f-de9eeb8726e4 │ 2026-02-10 20:31:14.630735+03 │
│ 019c4dc1-d549-7d7c-85f6-ba7201c61a63 │ 2026-02-11 20:31:14.630735+03 │
│ 019c52e8-3149-7d76-b205-897059e6d8ff │ 2026-02-12 20:31:14.630735+03 │
│ 019c580e-8d49-7d68-88d7-e846afc2c5b5 │ 2026-02-13 20:31:14.630735+03 │
│ 019c5d34-e949-7d61-8199-7ce0fed26860 │ 2026-02-14 20:31:14.630735+03 │
│ 019c625b-4549-7d5a-971e-fa0b9a827175 │ 2026-02-15 20:31:14.630735+03 │
│ 019c6781-a149-7d4f-a4f3-3f3ea25bcb2e │ 2026-02-16 20:31:14.630735+03 │
│ 019c6ca7-fd49-7d45-9449-ae8b3c2f8a9f │ 2026-02-17 20:31:14.630735+03 │
│ 019c71ce-5949-7d3f-84a5-f11c99d9e3cf │ 2026-02-18 20:31:14.630735+03 │
│ 019c76f4-b549-7d35-821c-f64da5398f11 │ 2026-02-19 20:31:14.630735+03 │
│ 019c7c1b-1149-7d2c-af1e-2b27042b726f │ 2026-02-20 20:31:14.630735+03 │
│ 019c8141-6d49-7d26-8e6e-a9cab44b4b64 │ 2026-02-21 20:31:14.630735+03 │
│ 019c8667-c949-7d1f-b9f5-7cf09ff6c908 │ 2026-02-22 20:31:14.630735+03 │

Если предварить запрос выражением EXPLAIN ANALYZE, увидим попадание в индекс:

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                    QUERY PLAN                                                                    │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=0.29..54.38 rows=100 width=24) (actual time=16.618..16.744 rows=28.00 loops=1)                                                      │
│   Buffers: shared hit=134                                                                                                                        │
│   ->  Index Scan using uuid_v7_demo_pkey on uuid_v7_demo  (cost=0.29..601.26 rows=1111 width=24) (actual time=16.615..16.737 rows=28.00 loops=1) │
│         Filter: ((id >= uuidv7('-3 mons'::interval)) AND (id <= uuidv7('-2 mons'::interval)))                                                    │
│         Rows Removed by Filter: 9971                                                                                                             │
│         Index Searches: 1                                                                                                                        │
│         Buffers: shared hit=134                                                                                                                  │
│ Planning Time: 0.139 ms                                                                                                                          │
│ Execution Time: 16.767 ms                                                                                                                        │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

Автор надеется, что читатель осведомлен о преимуществах UUID v7 и с радостью применит их. Далее по тексту мы будем пользоваться UUID v4 – случайным и неупорядоченным. Цель этого решения в том, чтобы примеры из книги работали со многими версиями Postgres, а не только 18.

Индексирование полей JSON

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

select id, (doc->>'application_id') as app_id
from applications
limit 10;

┌──────────────────────────────────────┬────────┐
│                  id                  │ app_id │
├──────────────────────────────────────┼────────┤
│ 00000000-0000-0000-0000-000000009985 │ 9985   │
│ 00000000-0000-0000-0000-000000009986 │ 9986   │
│ 00000000-0000-0000-0000-000000009987 │ 9987   │
│ 00000000-0000-0000-0000-000000009988 │ 9988   │
│ 00000000-0000-0000-0000-000000009989 │ 9989   │
│ 00000000-0000-0000-0000-000000009990 │ 9990   │
│ 00000000-0000-0000-0000-000000009991 │ 9991   │
│ 00000000-0000-0000-0000-000000009992 │ 9992   │
│ 00000000-0000-0000-0000-000000009993 │ 9993   │
│ 00000000-0000-0000-0000-000000009994 │ 9994   │
└──────────────────────────────────────┴────────┘

Требуется искать и сортировать документы по номеру. Для этого объявим индекс btree, где поле приводится к числу:

create index if not exists
idx_applications_application_id
on applications using btree
(((doc->>'application_id')::int));

Проверим операции, доступные индексу btree. Прежде всего это поиск по точному значению:

explain
select id, doc from applications
where ((doc->>'application_id')::int) = 550433;

┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              QUERY PLAN                                               │
├───────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using idx_applications_application_id on applications  (cost=0.42..8.44 rows=1 width=1730) │
│   Index Cond: (((doc ->> 'application_id'::text))::integer = 550433)                                  │
└───────────────────────────────────────────────────────────────────────────────────────────────────────┘

Отбор по диапазону с сортировкой:

explain
select id, doc from applications
where ((doc->>'application_id')::int) between 550000 and 550099
order by ((doc->>'application_id')::int) asc;

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                             QUERY PLAN                                                              │
├─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using idx_applications_application_id on applications  (cost=0.42..286.56 rows=94 width=1734)                            │
│   Index Cond: ((((doc ->> 'application_id'::text))::integer >= 550000) AND (((doc ->> 'application_id'::text))::integer <= 550099)) │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

Заметим, что индекс сработает лишь в том случае, когда выражение WHERE точно ему соответствует. В противном случае Postgres решит, что подходящего индекса нет и выполнит полное сканирование.

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

doc #>> '{application_id}'

Напомним, что операторы ->> и #>> возвращают элемент JSON в виде строки. Отличаются они методом доступа к элементу: ->> принимает имя поля, а #>> – их массив для вложенных случаев. И хотя выражения

(doc->>'application_id')::int
(doc #>> '{application_id}')::int

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

explain analyze
select id, doc from applications
where ((doc #>> '{application_id}')::int) = 550099;

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                            QUERY PLAN                                                             │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Gather  (cost=1000.00..259833.33 rows=5000 width=1830) (actual time=268.194..453.280 rows=1 loops=1)                              │
│   Workers Planned: 2                                                                                                              │
│   Workers Launched: 2                                                                                                             │
│   ->  Parallel Seq Scan on applications  (cost=0.00..258333.33 rows=2083 width=1830) (actual time=88.504..146.584 rows=0 loops=3) │
│         Filter: (((doc #>> '{application_id}'::text[]))::integer = 550099)                                                        │
│         Rows Removed by Filter: 333333                                                                                            │
│ Planning Time: 2.099 ms                                                                                                           │
│ Execution Time: 453.380 ms                                                                                                        │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Мы получили тот же документ 550099, но это заняло почти полсекунды и обход всей таблицы.

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

FIELD_APP_ID = SQL.raw("((doc #>> '{application_id}')::int)")

Applications.all().filter(FIELD_APP_ID.eq(1199)).query()

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

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

create index if not exists
idx_applications_application_id_text
on applications using btree
((doc->>'application_id'));

explain analyze
select id, doc
from applications
where (doc->>'application_id') = '550099';

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

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                      QUERY PLAN                                                                      │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using idx_applications_application_id_text on applications  (cost=0.42..8.44 rows=1 width=1830) (actual time=0.060..0.062 rows=1 loops=1) │
│   Index Cond: ((doc ->> 'application_id'::text) = '550099'::text)                                                                                    │
│ Planning Time: 0.196 ms                                                                                                                              │
│ Execution Time: 0.085 ms                                                                                                                             │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

select
    (doc->>'application_id') as doc_id
from
    applications
order by 1
limit 100

┌─────────┐
│ doc_id  │
├─────────┤
│ 1       │
│ 10      │
│ 100     │
│ 1000    │
│ 10000   │
│ 100000  │
│ 1000000 │
│ 100001  │
│ 100002  │
│ 100003  │
│ 100004  │
│ 100005  │
│ 100006  │

Номер 1000000 (миллион) идет перед 100001 (сто тысяч один), потому считается меньше. В отличие от чисел, строки сравниваются посимвольно слева направо. Первые символы обеих строк – единицы; далее сравниваются вторые символы – нули и так далее. На шестой позиции возникает отличие: единица и ноль. Код единицы больше кода нуля, поэтому сравнение завершается в пользу 100001.

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

insert into applications (doc)
values ($${
    "some_field": 42,
    "application_id": "123a456"
}$$::jsonb);

получим ошибку:

ERROR: invalid input syntax for type integer: "123a456"

Если в документе нет поля application_id или оно содержит null, выражение индекса тоже вернет null, и нарушений не будет. Позже мы рассмотрим, как сделать некоторые поля документа обязательными (не NULL) на уровне базы.

Индексирование дат

Документы хранят в себе множество дат. Две из них – создания и последнего изменения – настолько важны, что их выносят в поля таблицы created_at и updated_at. Чтобы искать по ним документы, добавьте обычный btree-индекс. Если в качестве ключа используется UUID версии 7, он уже хранит временную метку, так что индекс по created_at может и не потребоваться.

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

update applications
set doc['approved_at'] = to_json(current_timestamp - (interval '1 year') * random());

Быстрая проверка:

select id, doc['approved_at'] from applications limit 10;

┌──────────────────────────────────────┬────────────────────────────────────┐
│                  id                  │                doc                 │
├──────────────────────────────────────┼────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000009985 │ "2025-10-23T15:59:46.943586+03:00" │
│ 00000000-0000-0000-0000-000000009986 │ "2025-12-17T17:25:57.205986+03:00" │
│ 00000000-0000-0000-0000-000000009987 │ "2025-11-18T21:23:10.137186+03:00" │
│ 00000000-0000-0000-0000-000000009988 │ "2026-01-22T15:32:48.498786+03:00" │
│ 00000000-0000-0000-0000-000000009989 │ "2025-07-20T23:52:08.908386+03:00" │
│ 00000000-0000-0000-0000-000000009990 │ "2025-08-07T10:45:12.690786+03:00" │
│ 00000000-0000-0000-0000-000000009991 │ "2025-12-06T19:23:07.660386+03:00" │
│ 00000000-0000-0000-0000-000000009992 │ "2026-05-04T18:27:36.681186+03:00" │
│ 00000000-0000-0000-0000-000000009993 │ "2025-11-16T02:07:33.791586+03:00" │
│ 00000000-0000-0000-0000-000000009994 │ "2025-11-03T05:24:20.783586+03:00" │
└──────────────────────────────────────┴────────────────────────────────────┘

Требуется найти заявки, одобренные за указанный период. Для этого построим индекс btree, аналогичный application_id. Разница в том, что поле приводится к типу timestamp, а не int:

create index if not exists
idx_applications_approved_at
on applications using btree
(((doc->>'approved_at')::timestamptz at time zone 'utc'));

Увы, Postgres не примет команду из-за ошибки:

functions in index expression must be marked IMMUTABLE

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

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

{ “type”: “object”, “properties”: { “approved_at”: { “type”: “string”, “format”: “date-time” } } }

Спецификация JSON Schema предлагает формат date-time для строки, который гарантирует, что внутри – дата и время в формате ISO.

Поэтому, чтобы заставить Postgres построить индекс, обернем приведение типа в функцию с тегом IMMUTABLE:

create or replace function to_tsz_immutable(text)
  returns timestamptz
  language sql immutable strict parallel safe
return $1::timestamptz;

Уточним: технически возможно написать функцию, которая объявлена неизменяемой, но не является таковой. Postgres никак это не проверяет; ответственность за тег immutable лежит на вас. Если построить индекс с функцией, которая зависит от внешних факторов, вас ждет странное поведение.

Новый индекс не вызовет нареканий:

create index if not exists
idx_applications_approved_at
on applications using btree
(to_tsz_immutable(doc->>'approved_at'));

Выборка за период:

explain analyze
select id from applications
where to_tsz_immutable(doc->>'approved_at') between
    current_timestamp - interval '3 months'
    and
    current_timestamp - interval '1 months'
limit 100;

План:

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                                      QUERY PLAN                                                                                                      │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=0.43..401.63 rows=100 width=16) (actual time=0.080..0.247 rows=100 loops=1)                                                                                                                             │
│   ->  Index Scan using idx_applications_approved_at on applications  (cost=0.43..20060.44 rows=5000 width=16) (actual time=0.078..0.233 rows=100 loops=1)                                                            │
│         Index Cond: ((to_tsz_immutable((doc ->> 'approved_at'::text)) >= (CURRENT_TIMESTAMP - '3 mons'::interval)) AND (to_tsz_immutable((doc ->> 'approved_at'::text)) <= (CURRENT_TIMESTAMP - '1 mon'::interval))) │
│ Planning Time: 0.257 ms                                                                                                                                                                                              │
│ Execution Time: 0.277 ms                                                                                                                                                                                             │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

При работе с ORM поместите выражение to_tsz_immutable(doc->>'approved_at') в константу, чтобы гарантировать попадание в индекс.

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

REINDEX INDEX my_index_name;

Коротко о hash-индексе

Даже если поле нуждается в индексе, он не обязан быть btree. Когда требуется только равенство, а сортировка и диапазоны – нет, подойдет индекс hash. Он устроен как хэш-таблица, где ключи приводятся к числу специальной функцией. Мы не будем изучать устройство хэш-таблиц, потому что они подробно описаны в других материалах. Достаточно понимать, что поиск в них занимает постоянное время O(1). Таблицы не упорядочены, потому что не хранят порядок ключей. Отсюда невозможность обойти значения по убыванию или возрастанию.

Построим hash-индекс для поля organization.short_name с кодом клиента. Нам не нужна сортировка этому полю, потому что коды клиентов не образуют последовательности. В выражении индекса изменится только тип:

create index if not exists
idx_applications_org_short_name_hash
on applications using hash
(((doc #>> '{organization,short_name}')));

Убедимся, что индекс работает:

explain
select id
from applications
where (doc #>> '{organization,short_name}') = 'Organization 543'
limit 100;

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                      QUERY PLAN                                                       │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=0.00..400.15 rows=100 width=16)                                                                          │
│   ->  Index Scan using idx_applications_org_short_name_hash on applications  (cost=0.00..20007.50 rows=5000 width=16) │
│         Index Cond: ((doc #>> '{organization,short_name}'::text[]) = 'Organization 543'::text)                        │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Практика показывает, что для чисел и небольших строк индекс hash оказывается примерно на 10% быстрее. Однако на больших строках индекс замедляется: хэш-функция перебирает символы один за другим, и чем длиннее строка, тем дольше вычисляется хэш. Исследование и замеры вы найдете в блоге компании Cybertec в статье “PostgreSQL hash index performance”.

Статистика индексов

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

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

К счастью, Postgres ведет статистику обращения к индексам. Посмотреть ее можно в представлении pg_stat_user_indexes следующим запросом:

select * from pg_stat_user_indexes
where relname = 'applications'
-- order by last_idx_scan desc nulls last
limit 10;

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

┌──────────────────────────────────────────────────┬──────────┬──────────────┬───────────────┐
│                   indexrelname                   │ idx_scan │ idx_tup_read │ idx_tup_fetch │
├──────────────────────────────────────────────────┼──────────┼──────────────┼───────────────┤
│ applications_pkey                                │        4 │            4 │             4 │
│ idx_applications_created_at                      │        5 │       258830 │             1 │
│ idx_applications_application_id                  │        1 │          100 │           100 │
│ idx_applications_org_short_name_hash             │        6 │         4790 │           790 │
│ idx_applications_status                          │        6 │      1495416 │             0 │
│ idx_applications_status_org_short_name           │        1 │          263 │           263 │
│ idx_applications_application_id_trgm             │        1 │           20 │             0 │
│ idx_applications_application_org_short_code_trgm │        2 │         2000 │             0 │
│ idx_applications_application_trgm_pattern        │        4 │         4138 │             0 │
│ idx_applications_application_id_text             │        2 │            2 │             2 │
└──────────────────────────────────────────────────┴──────────┴──────────────┴───────────────┘

Среди прочих полей нас интересует idx_scan – число обращений к индексу. Очевидно, если индекс не используется, показатель будет низким; сортировка по idx_scan выявит кандидатов на удаление.

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

Полное описание pg_stat_user_indexes вы найдете в документации Postgres.

Составные индексы

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

Предположим, у сущности три поля: A, B и C. Все они покрыты индексом btree. Каждый запрос попадает в свой индекс без нареканий:

select from entity where a = 1;
select from entity where b = 'test';
select from entity where c = true;

Что случится, если добавить условие на два поля одновременно? Или даже на три – как поведет себя запрос?

select from entity
where
        a = 1
    and b = 'test'
    and c = true;

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

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

поле assigned_to равно текущему пользователю;
статус заявки равен active.

Вместе они дают запрос:

select id, doc
from applications
where
        doc->>'assigned_to' = 'ivanov@acme.com'
    and doc->>'status' = 'active';

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

Чтобы приблизить ситуацию к реальности, обновим поля заявок. Будем считать, что в штате не более тысячи сотрудников. Каждое значение assigned_to (назначенный пользователь) будет почтой вида user_xxx@test.com, где xxx – остаток от деления номера заявки на тысячу. Напомним, что номер заявки уникален и находится в диапазоне от единицы до миллиона.

Чуть сложнее поле статуса. На этапе генерации мы получили его случайно из массива:

((array['active', 'pending', 'approved', 'deleted'])[ceil(random() * 4)])

Это не совсем верно: в реальности большинство заявок имеют финальный статус (одобрено или отклонено) и лишь малая часть находится на рассмотрении.

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

65% – заявка сдана в архив;
20% – одобрена;
10% – отклонена;
оставшиеся 5% – в работе.

Код функции:

create or replace function generate_status() returns text
language plpgsql strict parallel safe
as $func$
declare
    r float4;
begin
    r := random();
    case
        when r < 0.65 then return 'archived';  -- 65%
        when r < 0.85 then return 'approved';  -- 20%
        when r < 0.95 then return 'rejected';  -- 10%
        else return 'active';                  --  5%
    end case;
end;
$func$;

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

update applications set
doc['assigned_to'] = to_jsonb(format('user_%s@test.com', (doc->>'application_id')::int % 1000)),
doc['status'] = to_jsonb(generate_status());

Проверим распределение статусов:

select
    to_char(count(id) / 1000000.0, '0.9999') as ratio,
    doc->>'status' as status
from applications
group by 2
order by 1 desc;

┌─────────┬──────────┐
│  ratio  │  status  │
├─────────┼──────────┤
│  0.6498 │ archived │
│  0.2001 │ approved │
│  0.1002 │ rejected │
│  0.0499 │ active   │
└─────────┴──────────┘

Теперь когда оба поля готовы, объявим для каждого btree-индекс:

create index if not exists
idx_applications_status
on applications using btree
((doc->>'status'));

create index if not exists
idx_applications_assigned_to
on applications using btree
((doc->>'assigned_to'));

analyze applications;

Проверим, как поведет себя запрос с условием по двум полям:

explain analyze
select id, doc from applications
where
     (doc->>'status') = 'active'
 and (doc->>'assigned_to') = 'user_999@test.com';

┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                   QUERY PLAN                                                                   │
├────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Bitmap Heap Scan on applications  (cost=407.13..526.75 rows=30 width=1915) (actual time=8.974..9.047 rows=45 loops=1)                          │
│   Recheck Cond: (((doc ->> 'assigned_to'::text) = 'user_999@test.com'::text) AND ((doc ->> 'status'::text) = 'active'::text))                  │
│   Heap Blocks: exact=45                                                                                                                        │
│   ->  BitmapAnd  (cost=407.13..407.13 rows=30 width=0) (actual time=8.938..8.940 rows=0 loops=1)                                               │
│         ->  Bitmap Index Scan on idx_applications_assigned_to  (cost=0.00..8.99 rows=609 width=0) (actual time=0.361..0.361 rows=1000 loops=1) │
│               Index Cond: ((doc ->> 'assigned_to'::text) = 'user_999@test.com'::text)                                                          │
│         ->  Bitmap Index Scan on idx_applications_status  (cost=0.00..397.88 rows=30060 width=0) (actual time=7.956..7.956 rows=49918 loops=1) │
│               Index Cond: ((doc ->> 'status'::text) = 'active'::text)                                                                          │
│ Planning Time: 0.316 ms                                                                                                                        │
│ Execution Time: 9.338 ms                                                                                                                       │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

План говорит, что использовались оба индекса. Сначала Postgres обошел индекс idx_applications_assigned_to и пометил в битовой карте кандидатов по полю assigned_to. Далее составил такую же карту для статуса (индекс idx_applications_status). Обе карты объединяются битовым AND; в ней остались только те единичные биты, что были в двух исходных одновременно. По итоговой карте Postgres выбрал строки и еще раз проверил условия. В выборке оказалось 45 документов. На исполнение ушло 9 миллисекунд – хороший показатель, который, однако, можно улучшить.

Добавим составной индекс на пару полей [статус, пользователь] одновременно:

create index if not exists
idx_applications_status_assigned_to
on applications using btree
((doc->>'status'), (doc->>'assigned_to'));

Выполним анализ таблицы

analyze applications;

и повторим запрос explain analyze. Новый план:

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                       QUERY PLAN                                                                        │
├─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using idx_applications_status_assigned_to on applications  (cost=0.42..185.65 rows=51 width=1915) (actual time=0.139..0.223 rows=45 loops=1) │
│   Index Cond: (((doc ->> 'status'::text) = 'active'::text) AND ((doc ->> 'assigned_to'::text) = 'user_999@test.com'::text))                             │
│ Planning Time: 1.733 ms                                                                                                                                 │
│ Execution Time: 0.270 ms                                                                                                                                │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Запрос занял 0.27 миллисекунды – в сорок раз ниже! Разумеется, от запуска к запуску эта цифра плавает: выдает значения от 0.1 до 0.4. Разница на порядок, однако, сохраняется. Это подтверждает тезис о том, что поиск по составному индексу быстрее, чем два промежуточных поиска с объединением результатов.

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

Если взглянуть на индекс по паре [статус, пользователь], заметно следующее. Чтобы показать пользователю, над какими заявками ему работать, мы указываем статус active. Другие статусы нас не интересуют. Раз так, можно создать индекс по полю assigned_to, но так, чтобы он охватывал только активные заявки. Вот как это сделать:

create index if not exists
idx_applications_assigned_to_active
on applications using btree
((doc->>'assigned_to'))
where (doc->>'status' = 'active');

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

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                       QUERY PLAN                                                                        │
├─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Index Scan using idx_applications_status_assigned_to on applications  (cost=0.42..185.65 rows=51 width=1915) (actual time=0.139..0.223 rows=45 loops=1) │
│   Index Cond: (((doc ->> 'status'::text) = 'active'::text) AND ((doc ->> 'assigned_to'::text) = 'user_999@test.com'::text))                             │
│ Planning Time: 1.733 ms                                                                                                                                 │
│ Execution Time: 0.270 ms                                                                                                                                │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

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

create or replace function generate_credit_type() returns text
language plpgsql strict parallel safe
as $func$
declare
    r float4;
begin
    r := random();
    case
        when r < 0.85 then return 'org';  -- 85%
        else return 'country';            -- 15%
    end case;
end;
$func$;

update applications set
doc['credit_type'] = to_jsonb(generate_credit_type());

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

(doc->>'credit_type') != 'country'

Можно сделать иначе: построить индекс по полю assigned_to, покрывающий только активные заявки с типом 'org':

create index if not exists
idx_applications_active_org_assigned_to
on applications using btree
((doc->>'assigned_to'))
where
    (doc->>'status' = 'active')
and (doc->>'credit_type') = 'org';

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

explain analyze
select id, doc from applications
where
    (doc->>'status') = 'active'
and (doc->>'credit_type') = 'org'
and (doc->>'assigned_to') = 'user_999@test.com'

, то по условиям (doc->>'status') = 'active' и (doc->>'status') = 'active' база определит, что конкретно этому запросу подходит индекс idx_applications_active_org_assigned_to. Он хранит не всю тройку полей, а только пользователей. Такой индекс компактен, и поиск по нему быстрее. При этом никакой фильтрации по статусу и типу заявки не было – мы просто взяли нужный индекс.

У составного индекса тоже есть преимущество. Если он составлен по тройке (A, B, C), то будет работать, даже если известны A и B или даже просто A. Обобщая, можно сказать, что составной индекс работает, если известны его лидирующие компоненты. Ситуция (A, C) не подходит под этот случай, потому что неизвестен компонент B посередине. Такой вариант возможен, но скорее всего Postgres посчитает его дорогим и предпочтет полный обход таблицы.

Проектируя составной индекс, располагайте компоненты так, чтобы покрыть как можно больше сценариев. Если вы фильтруете записи по полям A и B и создали индекс (A, B), это позволит фильтровать в том числе по A. Если же индекс объявлен как (B, A), то условию по A понадобится отдельный индекс. В этом случае проще удалить (B, A) и создать (A, B).

Поиск по шаблону

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

Для этих целей Postgres предлагает операторы like, ilike и ~ (тильда). Первые два проверяют текст на вхождение другого текста, при этом поддерживаются простые шаблоны. Тильда сопоставляет текст с регулярным выражением, которые мощнее шаблонов. Расширение pg_trgm предлагает индексы для этих и других операторов. Ниже мы рассмотрим детали.

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

подчеркивание (_) означает строго один любой символ;
процент (%) означает ноль и более любых символов.

Вот и вся шаблонная система. Приведем несколько примеров:

select '123456789' like '123'

Вернет ложь, потому что это буквальное сравнение, и строки не равны.

select '123456789' like '123%'

Вернет истину, потому что процент поглощает символы 4, 5 и до конца строки.

select '1a3' like '1_3';

Вернет истину, потому что символ “a” удовлетворяет подчеркиванию (любому символу).

Оператор ilike (insensitive like) действует аналогично, но без учета регистра. С цифрами этого не заметно, поэтому приведем пример с электронной почтой. Ниже мы проверяем, какие адреса на домене gmail.com содержат имя john:

select
    email,
    email ilike '%john%@gmail.com' as matches
from (values
    ('JOHN_SMITH@Gmail.com'),
    ('Adam.Smith@GMAIL.com'),
    ('John+Anderson@gmail.com'),
    ('johnson@gmail.com')
) as vals(email);

Результат:

┌─────────────────────────┬─────────┐
│          email          │ matches │
├─────────────────────────┼─────────┤
│ JOHN_SMITH@Gmail.com    │ t       │
│ Adam.Smith@GMAIL.com    │ f       │
│ John+Anderson@gmail.com │ t       │
│ johnson@gmail.com       │ t       │
└─────────────────────────┴─────────┘

Возвращаемся к нашим заявкам. Предположим, о номере заявки мы помним только то, что в нем была комбинация 12345. Чтобы найти все варианты, выполним запрос:

select id from applications
where (doc->>'application_id') like '%12345%'
limit 100;

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

┌──────────────────────────────────────┐
│                  id                  │
├──────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000012345 │
│ 00000000-0000-0000-0000-000000112345 │
│ 00000000-0000-0000-0000-000000123450 │
│ 00000000-0000-0000-0000-000000123451 │
│ 00000000-0000-0000-0000-000000123452 │
│ 00000000-0000-0000-0000-000000123453 │
│ 00000000-0000-0000-0000-000000123454 │
│ 00000000-0000-0000-0000-000000123455 │

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

Нам понадобится расширение pg_trgm; оно встроено в Postgres и считается доверенным. Последнее означает, что его может включить обычный пользователь, а не только администратор. Сочетание trgm означает trigram – триграмма, часть слова из трех букв. Расширение разбивает текст на триграммы и использует их в различных операциях. Так, слово hello становится массивом триграмм как в примере ниже:

{"  h"," he",ell,hel,llo,"lo "}

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

Подключите расширение командой create extension. Достаточно выполнить ее однажды в разрезе базы данных:

create extension if not exists pg_trgm;

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

create index if not exists
idx_applications_application_id_trgm
on applications using gin
((doc->>'application_id') gin_trgm_ops);

Обратите внимание, что тип индекса – не btree, а GIN. Аббревиатура означает Generalized Inverted Index – обобщенный инвертированный индекс. Этот тип применяют в случаях, когда индексируемое значение состоит из элементов. Частный случай GIN – поиск в массивах и триграммах. Переменная gin_trgm_ops задает параметры, специфичные для триграмм.

Кроме GIN, индекс может быть объявлен с типом GiST, что означает Generalized Search Tree (обобщенное дерево поиска). У каждого из этих типов преимущества и недостатки; обобщая, можно сказать, что GIN производительней в чтении, но занимает больше места. GiST, напротив, компактней, но медленней в плане доступа. Также GiST опирается на хэширование элементов, поэтому для решения коллизий выражение индекса может вычисляться дважды.

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

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

explain analyze
select id from applications
where (doc->>'application_id') like '%12345%'
limit 100;

И проверим план:

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                      QUERY PLAN                                                                       │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=32.77..428.27 rows=100 width=16) (actual time=0.629..0.732 rows=20 loops=1)                                                              │
│   ->  Bitmap Heap Scan on applications  (cost=32.77..428.27 rows=100 width=16) (actual time=0.628..0.729 rows=20 loops=1)                             │
│         Recheck Cond: ((doc ->> 'application_id'::text) ~~ '%12345%'::text)                                                                           │
│         Heap Blocks: exact=13                                                                                                                         │
│         ->  Bitmap Index Scan on idx_applications_application_id_trgm  (cost=0.00..32.75 rows=100 width=0) (actual time=0.601..0.601 rows=20 loops=1) │
│               Index Cond: ((doc ->> 'application_id'::text) ~~ '%12345%'::text)                                                                       │
│ Planning Time: 0.646 ms                                                                                                                               │
│ Execution Time: 0.765 ms                                                                                                                              │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Выражение Bitmap Index Scan присутствует, время выполнения – 0.7 миллисекунд. Индекс работает.

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

explain analyze
select id from applications
where (doc->>'application_id') like '%99%'
limit 100;

┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                       QUERY PLAN                                                       │
├────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=0.00..874.50 rows=100 width=16) (actual time=0.096..5.397 rows=100 loops=1)                               │
│   ->  Seq Scan on applications  (cost=0.00..265000.00 rows=30303 width=16) (actual time=0.095..5.387 rows=100 loops=1) │
│         Filter: ((doc ->> 'application_id'::text) ~~ '%99%'::text)                                                     │
│         Rows Removed by Filter: 4378                                                                                   │
│ Planning Time: 0.189 ms                                                                                                │
│ Execution Time: 5.424 ms                                                                                               │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

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

select show_trgm('#alpha!, ?beta=, ;gamma^');

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                                        show_trgm                                        │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ {"  a","  b","  g"," al"," be"," ga",alp,amm,bet,eta,gam,"ha ",lph,"ma ",mma,pha,"ta "} │
└─────────────────────────────────────────────────────────────────────────────────────────┘

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

Если шаблон передал пользователь, проверяйте символы процента и подчеркивания. Операторы (i)like трактуют их особым образом, что может привести к тому, что запрос выдал лишние записи. Если пользователь имел в виду именно подчеркивание или процент, экранируйте их – предварите обратной косой чертой. Например, чтобы проверить текст на вхождение строки “50%”, передайте следующий шаблон:

select 'more than 50% in total' ilike '%50\%%';
-- t

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

Замечания по договору 12352/AB/04

соответствует шаблон

*по договору 12352/??/??

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

По аналогии добавьте триграммные индексы для других полей, например названию фирмы или назначенному сотруднику (organization.short_name, assigned_to). Проверьте план и производительность запросов.

Триграммный поиск по многим полям

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

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

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

Каждое поле формы связано с атрибутом документа. Если клиент заполнил форму как в примере выше и нажал ввод, на сервер уйдет следующий JSON:

{
    "application_id": "12345",
    "org_name": "Acme",
    "created_by": "Maria",
    "comment": "reconciliation"
}

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

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

Мы не знаем заранее, сколько получим критериев поиска. Понадобится библиотека, чтобы построить SQL без риска инъекций со стороны клиента. Проверьте, что клиент отправил хотя бы один критерий поиска. Иначе мы получим либо неверный синтаксис (пустой WHERE), либо запрос без WHERE, который читает всю таблицу.

Есть и другой подход к поиску: предоставить клиентам поле ввода “а-ля Гугл”. Его строка проверяет сразу несколько атрибутов. Это современный подход, и сегодня его воспринимают как должное. Например, если клиент ввел 12345, мы вернем документы, где эта строка встречается в номере, названии клиента, комментарии и других полях.

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

Рассмотрим, как сделать подобный поиск. Наивное решение в том, чтобы составить набор условий вида:

(doc #>> '{path.to.field}') ilike '%12345%'

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

create index if not exists
idx_applications_trgm_path_to_field
on applications using gin
((doc #>> '{path.to.field}') gin_trgm_ops);

Предположим теперь, клиент ввел в поле поиска 12345 и нажал ввод. Сервер построит запрос:

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

План этого запроса велик и не поместится на странице книги. Описать его можно так: четыре узла Bitmap Index Scan, каждый из которых сканирует свой индекс и строит битовую карту. Четыре карты объединяются методом BitmapOr. По ней база обходит таблицу applications и выбирает 20 записей. На ноутбуке автора запрос выполнялся 3 миллисекунды.

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

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

(field1 ilike 'pattern') or (field2 ilike 'pattern') or ...

аналогично следующему:

(field1 || ' ' || field1 || ...) ilike 'pattern'

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

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

Postgres предлагает несколько способов это сделать, в том числе:

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

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

Подготовим выражение, которое объединяет атрибуты документа через пробел. Наивное решение:

(
       (doc #>> '{application_id}') || ' '
    || (doc #>> '{organization,short_name}') || ' '
    || (doc #>> '{created_by,name}') || ' '
    || (doc #>> '{comment}')
)

Недостаток в том, что если в документе нет хотя бы одного поля, конструкция “занулится” – вернет NULL. Для несуществующего поля оператор #>> производит NULL, его соединение со строкой тоже даст NULL и так далее. Это легко проверить:

select 'foo' || null || 'bar' as result;

┌────────┐
│ result │
├────────┤
│ <null> │
└────────┘

Не хотелось терять документ из-за одного неудачного атрибута. Поступим умнее: обернем операторы #>> формой coalesce с пустой строкой — умолчанием для NULL:

(
       coalesce((doc #>> '{application_id}'), '') || ' '
    || coalesce((doc #>> '{organization,short_name}'), '') || ' '
    || coalesce((doc #>> '{created_by,name}'), '') || ' '
    || coalesce((doc #>> '{comment}'), '')
)

Это выражение устойчиво к NULL, но выглядит слишком шумно. Более удачный вариант – взять функцию concat_ws. Она принимает разделитель и произвольные аргументы, которые приводятся к строке; значения NULL при этом игнорируются:

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
((concat_ws(
    ' ',
    (doc #>> '{application_id}'),
    (doc #>> '{organization,short_name}'),
    (doc #>> '{created_by,name}'),
    (doc #>> '{comment}')
)) gin_trgm_ops);

Однако нас ждет ошибка:

ERROR: functions in index expression must be marked IMMUTABLE

Как мы упоминали, в выражении индекса функции должны быть помечены как неизменяемые (immutable). Для concat_ws это требование не выполняется. Почему? Разве соединение строк пробелом носит побочный эффект?

Дело в том, что concat_ws работает в два этапа. Второй из них – соединение текстовых фрагментов разделителем; это действие, конечно, иммутабельно. Первый этап приводит все значения к тексту и передает второму. Типы вроде дат и времени зависят от локали и глобальных настроек, из-за чего приведение их к тексту не считается иммутабельным.

Функция, выполняющая второй этап, называется text_concat_ws. Она написана на языке Си поэтому недоступна без ухищрений. Postgres позволяет создать функцию-обертку, которая сводится к вызову внутренней (internal) функции. В примере ниже функция immutable_concat_ws не имеет тела, а только передает управление функции text_concat_ws:

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

Объявлять подобные обертки может только администратор, поскольку функции на Си, как правило, небезопасны.

Теперь когда у нас есть иммутабельная функция для склейки строк, построим индекс сразу на четыре поля:

create index if not exists
idx_applications_application_trgm_pattern
on applications using gin
((immutable_concat_ws(
    ' ',
    (doc #>> '{application_id}'),
    (doc #>> '{organization,short_name}'),
    (doc #>> '{created_by,name}'),
    (doc #>> '{comment}')
)) gin_trgm_ops);

Проверим поиск документов с новым индексом. Выполним запрос с шаблоном %12345%:

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

В плане окажется один узел Bitmap Index Scan вместо четырех. Время выполнения – 0.6 миллисекунды. Эксперимент подтвердил тезис, что один сложный индекс, составленный под конкретные требования, лучше нескольких.

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

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}')
);

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

select id, application_search_pattern(doc)
from applications
limit 100;

┌──────────────────────────────────────┬────────────────────────────────────────────────────────┐
│                  id                  │               application_search_pattern               │
├──────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000010049 │ 10049 Organization 49 User 0049 Comment number #10049  │
│ 00000000-0000-0000-0000-000000010050 │ 10050 Organization 50 User 0050 Comment number #10050  │
│ 00000000-0000-0000-0000-000000010051 │ 10051 Organization 51 User 0051 Comment number #10051  │
│ 00000000-0000-0000-0000-000000010052 │ 10052 Organization 52 User 0052 Comment number #10052  │

Удалим старый индекс и построим новый, где вызов immutable_concat_ws со множеством полей заменен функцией:

drop index if exists
idx_applications_application_trgm_pattern;

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;

Его план и быстродействие будут такими же, как в случае с конкатенацией. Однако запрос сократился, и выражение application_search_pattern(doc) легче запомнить. Если мы случайно ошиблись в названии функции, то получим ошибку, а не молчаливый full seq scan.

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

Коротко о ранжировании

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

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

Будет удобно, если поиск по слову 123 покажет результаты в следующем порядке:

документ с номером 123;
документ, код организации которой равен 123;
документы, номера которых содержат 123;
документы, коды организаций которых содержат 123.

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

Регулярные выражения

Прежде чем закончить с триграммами, расскажем о еще одной их возможности.

Триграммный индекс поддерживает не только шаблоны, но и регулярные выражения. Предположим, нужно найти документы по какому-то сложному условию, которое нельзя выразить шаблоном. Пусть это будет заявка организации с кодом 313 и набором символов #22313 в комментарии.

Вот как выглядит новый запрос. Вместо (i)like мы использовали оператор ~ (тильду), который сопоставляет строку слева с регулярным выражением справа. Вариант со звездочкой ~* означает то же самое, но без учета регистра. Ниже мы выбрали не документ, а поисковой агрегат, чтобы проверить себя:

select id, application_search_pattern(doc)
from applications
where application_search_pattern(doc) ~ 'Organization 313.+?#22313'
limit 100;

Этому запросу удовлетворяет лишь одна запись в таблице:

┌──────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────┐
│                  id                  │                        application_search_pattern                        │
├──────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────┤
│ 00000000-0000-0000-0000-000000022313 │ 22313 Organization 313 User 0313 Comment number #22313 user_313@test.com │
└──────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────┘

План подтверждает, что мы попали в индекс: в нем присутствует выражение Bitmap Index Scan. Он не такой уж быстрый: время выполнения – почти 70 миллисекунд.

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                          QUERY PLAN                                                                           │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=444.78..890.03 rows=100 width=48) (actual time=69.670..69.904 rows=1 loops=1)                                                                    │
│   ->  Bitmap Heap Scan on applications  (cost=444.78..890.03 rows=100 width=48) (actual time=69.668..69.903 rows=1 loops=1)                                   │
│         Recheck Cond: (application_search_pattern(doc) ~ 'Organization 313.+?#22313'::text)                                                                   │
│         Rows Removed by Index Recheck: 19                                                                                                                     │
│         Heap Blocks: exact=13                                                                                                                                 │
│         ->  Bitmap Index Scan on idx_applications_application_trgm_pattern  (cost=0.00..444.75 rows=100 width=0) (actual time=69.503..69.503 rows=20 loops=1) │
│               Index Cond: (application_search_pattern(doc) ~ 'Organization 313.+?#22313'::text)                                                               │
│ Planning Time: 1.735 ms                                                                                                                                       │
│ Execution Time: 69.949 ms                                                                                                                                     │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

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

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

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

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

Одно из полей заявки называется “departments”. В нем структура из двух уровней: отделы (департаменты), связанные с заявкой, а ниже — сотрудники отделов, которые работали над ней. Приведем фрагмент данных:

"departments": [
    {
        "id": "224899ae-fac7-4555-8a94-f41f3c9ed634",
        "code": "risk",
        "name": "Risk Department",
        "users": [
            {
                "id": "3f798e66-43a3-4d78-b5f9-3c3740b6676b",
                "email": "mironov.p@acme.com",
                "name": "Petr Mironov",
                "role": "manager"
            },
            {
                "id": "9ecef728-a3bb-4a1d-85d7-51dff2401c0b",
                "email": "smith.k@acme.com",
                "name": "Karol Smith",
                "role": "analyst"
            }
        ]
    },
    {
        "id": "7513991b-9951-4bce-ad4a-470ff2d3febf",
        "code": "analytics",
        "name": "Analytics Department",
        "users": [
            {
                "id": "361a08a5-3991-4b2a-9d49-8e4cf77b876b",
                "email": "smirnov.i@acme.com",
                "name": "Igor Smirnov",
                "role": "reader"
            },
            {
                "id": "11da81b9-b125-4a7e-9965-958cc5593a3e",
                "email": "jackson.j@acme.com",
                "name": "John Jackson",
                "role": "support"
            }
        ]
    }
]

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

Предположим, нам поставили задание: найти заявки, над которыми работал пользователь с определенной ролью. Скажем, в примере выше это Karol Smith в роли аналитика. Нужно найти все заявки с подобным условием.

Задание интересно тем, индекс btree нам не поможет. Путь к пользователю Karol Smith следующий:

departments,0,users,1

В отличие от прошлых случаев он включает массивы, точнее номера элементов. Если мы построим индекс btree для этого пути, то охватим лишь часть поля departments: строго первый отдел и второго пользователя. А в другой заявке Karol Smith может быть и вторым, и третьим, и двадцатым пользователем!

Может быть, построить индексы для всех комбинаций отделов и пользователей?

departments,0,users,0
departments,0,users,1
departments,1,users,0
departments,1,users,1
...

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

Чтобы решить проблему, построим индекс GIN для всего поля doc. Вот как он выглядит:

create index if not exists
idx_applications_doc_gin_jsonb_ops
on applications using gin
(doc jsonb_ops);

Когда индекс GIN применяют к jsonb, можно указать опции. По умолчанию это переменная jsonb_ops, и выше мы задали ее явно. Postgres предлагает второй набор названием jsonb_path_ops; в чем его преимущество мы узнаем позже.

Индекс GIN устроен сложнее btree. Он обходит документ и строит множество пар путь -> значение. Например, документ:

{"users": [{"name": "Ivan"},
           {"name": "Huan"}]}

раскладывается на следующие пары:

users.0.name = Ivan
users.1.name = Huan

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

Новый индекс поддерживает несколько операторов, которых не было в btree. Например, с помощью знака вопроса (?) легко проверить, был ли в документе определенный ключ:

select id from applications
where doc ? 'application_id'
limit 10;

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

update applications
set doc['__migrate__'] = to_json(true)
where ...;

update applications
set ...
where doc ? '__migrate__';

Поиск по наличию поля работает быстрее, чем по значению.

Операторы ?| и ?& принимают массив строк. Первый возвращает истину, если документ содержит хотя бы один ключ, а второй – если все. Эти проверки, хоть и требуются редко, полезны в особых случаях, например поиске ошибочно заполненных документов. Запрос ниже вернет заявки, где нет хотя бы одного из перечисленных полей:

select id from applications
where doc ?& '{application_id,status,amounts}'
limit 10;

Наиболее важен оператор @> (правое мороженое) – рекурсивное вхождение одного документа в другой. Напомним, мы изучили его во второй главе, когда только знакомились с JSON. Чтобы найти в недрах departments пользователя user_123 в роли “lead”, составим следующий запрос:

select
    id,
    jsonb_pretty(doc['departments'])
from applications
where doc @> $${
  "departments": [{"users": [{
    "email": "user_123@test.com",
    "role": "lead"
  }]}]
}$$::jsonb
limit 100;

Документ справа от @> является минимальным подмножеством заявки. У обеих сторон есть поле “departments”, и далее их значения проверяются рекурсивно. Алгоритм переходит к массивам, элементам, объектам с полями “users” и так далее.

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

┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                         QUERY PLAN                                                                         │
├────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Limit  (cost=189.50..524.92 rows=100 width=48) (actual time=26.982..28.416 rows=100 loops=1)                                                               │
│   ->  Bitmap Heap Scan on applications  (cost=189.50..33731.03 rows=10000 width=48) (actual time=26.980..28.406 rows=100 loops=1)                          │
│         Recheck Cond: (doc @> '{"departments": [{"users": [{"email": "user_123@test.com"}]}]}'::jsonb)                                                     │
│         Heap Blocks: exact=100                                                                                                                             │
│         ->  Bitmap Index Scan on idx_applications_doc_gin_jsonb_ops  (cost=0.00..187.00 rows=10000 width=0) (actual time=26.623..26.623 rows=3000 loops=1) │
│               Index Cond: (doc @> '{"departments": [{"users": [{"email": "user_123@test.com"}]}]}'::jsonb)                                                 │
│ Planning Time: 91.763 ms                                                                                                                                   │
│ Execution Time: 28.460 ms                                                                                                                                  │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Индекс GIN и “мороженное” решают проблему массивов: можно найти элемент, зная его значение, а не позицию. Это выгодно отличает GIN от btree, который требует явного пути к значению и поэтому несовместим с массивами.

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

SELECT pg_size_pretty(pg_total_relation_size('applications'))
as app_table_size;

┌────────────────┐
│ app_table_size │
├────────────────┤
│ 4877 MB        │
└────────────────┘

SELECT pg_size_pretty(pg_total_relation_size('idx_applications_created_at'))
as created_at_index_size;

┌───────────────────────┐
│ created_at_index_size │
├───────────────────────┤
│ 50 MB                 │
└───────────────────────┘

Хотя таблица и занимает почти пять гигабайт, индекс bree весьма компактный: всего 50 мегабайт, разница два порядка. Если же выполнить запрос для индекса GIN, результат удивит: полтора гигабайта!

SELECT pg_size_pretty(pg_total_relation_size('idx_applications_doc_gin_jsonb_ops'))
as gin_json_index_size;

┌─────────────────────┐
│ gin_json_index_size │
├─────────────────────┤
│ 1492 MB             │
└─────────────────────┘

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

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

create index if not exists
idx_applications_doc_departments_gin_jsonb_ops
on applications using gin
((doc['departments']) jsonb_ops);

Запрос тоже изменится: слева от @> находится не документ, а та часть, что мы индексируем. В свою очередь документу справа не понадобится поле “departments”: это будет массив.

select
    id,
    jsonb_pretty(doc['departments'])
from applications
where doc['departments'] @> $$[
    {"users": [{
        "email": "user_123@test.com",
        "role": "lead"
    }]}
]$$::jsonb
limit 100;

Запрос выполнится быстрее: 22 миллисекунды против 28.5. В очередной раз мы подтвердили тезис, что чем меньше индекс, тем эффективней запрос. Если измерить пространство, получим результат на порядок меньше, чем в случае с полной индексацией:

SELECT pg_size_pretty(pg_total_relation_size('idx_applications_doc_departments_gin_jsonb_ops'))
as gin_json_deps_index_size;

┌──────────────────────────┐
│ gin_json_deps_index_size │
├──────────────────────────┤
│ 237 MB                   │
└──────────────────────────┘

Общее правило таково: индексируйте только ту часть документа, которая действительно того требует. В нашем случае это поле “departments”: в нем встречаются массивы, а те плохо сотрудничают с btree. Для остальных полей обычно хватает btree и триграмм.

Оператор @> возвращает истину или ложь, поэтому не может быть использован для сортировки. Если выборка сортируется, Postgres оценивает, какой из двух вариантов предпочесть. Первый — обойти записи по индексу сортировки и отфильтровать их при помощи @>. Индекс GIN при этом использоваться не будет. Второй вариант — обойти индекс GIN, получить строки и отсортировать их в памяти. Выбор зависит от того, насколько точен индекс GIN. Если в запрос одновременно содержит сортировку и оператор @>, обязательно проверьте план.

Индекс GIN поддерживает еще два оператора: поиск по пути с предикатом @@ и поиск с подзапросом @?. Обе функции крайне мощны и представляют собой вещь в себе. Чтобы познакомиться с ними, нам понадобится язык выражений JSON Path. Это весьма обширная тема, и мы придержим ее для отдельной главы.

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

Вайбкодинг (2)

Sat, 16 May 2026 00:00:00 +0000

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

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

Далее: кто несет отвественность за комментарии? Вот сказала нейросеть заменить один класс на другой. Зато автор считает, что менять ничего не нужно. Как это разрулить? Автор пишет ответочку, ревьюер отправляет ее модели и копирует ответ? Бред же.

При таком раскладе зачем нам вообще ревьюер с моделью? Сделайте кнопку “AI-review” или встройте модель в CI — по крайней мере будет ясно, откуда дровишки.

Помнится, в Южном Парке была забавная серия. Учитель дает детям сочинение; дети никогда его не пишут и получают двойки. Зато теперь у всех — текст А4 от чата джи-пи-ти. Учитель садиться проверять и не может: на 30 сочинений нет никаких сил. Тогда он достает телефон и сканирует сочинения. ГПТ пишет рецензию и ставит оценку. Круг замкнулся, все довольны.

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

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

Пугая кого-то заменой или устранением, подумайте — не придется ли вам пройти раньше своих жертв.

Вайбкодинг (1)

Sat, 16 May 2026 00:00:00 +0000

Вирус под названием “вайбкодинг” дошел и до нас. Начиналось все буднично: файлы AGENTS.md в каждом репозитории; бесконечные обсуждения моделей в чате. У иных разработчиков резко изменился стиль: годами они не писали ни одного комментария, а сегодня у каждой функции докстринг; файлы разбиты на секции вида:

;;;;;;;;;;;;;;;;
;; public API
;;;;;;;;;;;;;;;;

;;;;;;;;;;;;;;;;
;; dev section
;;;;;;;;;;;;;;;;

и так далее.

Некоторые люди занимаются нейросетями всерьез: знают все эти Клоды, запускают модели локально и в облаке. У нас даже проводятся внутренние вебинары на тему моделей.

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

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

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

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

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

Смотрю код другого коллеги: это Питон-скрипт для перекладывания данных между таблицами. Задаю простой вопрос – скрипт работает? Отвечает, что да. В ту же минуту я вижу ошибку в SQL, из-за которой ничего работать не будет. Ради интереса запускаю скрипт на тестовой базе. Происходит вот что:

выскакивает неизвестная ошибка (до SQL даже не дошло)
из-за try/catch управление переходит в блок catch
там используется неинициализированная переменная
скрипт вылетает

То есть в скрипте как минимум три ошибки! Работает он, ага.

При этом низкое качество кода коррелирует с дороговизной оборудования. Всем известно, как выросла цена на память: в интернете все шутки только об этом. Однако теперь коллеги обсуждают покупку Mac Studio со встроенной памятью 128 гигабайт. Стоит он от 5 до 7 тысяч долларов. Купить такую дорогую вещь, чтобы генерить на ней неработающие скрипты?

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

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

О домах

Sat, 16 May 2026 00:00:00 +0000

А какие могут быть выводы? И так все понятно.

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

Дома не должны подпирать стратосферу. Лучшая высота здания – 5-10 этажей и не больше. Такой дом не давит размером, не выделяется на фоне городского пейзажа, не отбрасывает тень. Последнее, кстати, проблема городов вроде Чикаго: на улицах между высоких зданий почти не бывает света. Это сырость, лужи и банальная проступность.

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

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

Мне как человеку искренне непонятно желание жить как можно выше. Зачем? Какая цель? Чтобы ехать в лифте десять минут? Переживать за детей и домашних животных, чтобы не выпали в окно? Если экстраполировать, то будет ли жилье на 450-м этаже лучше, чем на 200-м? А на тысячном?

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

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

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

Когда был в Москве, наблюдал жилые небоскребы по образу того, что в прошлой заметке. Циклопической высоты, этажей этак 70. При этом сквозь открытые окна видны черновые потолки. Квартиры выше 20 этажа не отделаны. Бетонные коробки напоминают пчелиные соты. Вид у домов зловещий.

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

Попросишь потише — бро, это частная собственность.

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

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

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

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

Небоскребы в облаках хороши на картинках, а на деле жить в них никто не хочет. Может быть, работать, да и то под вопросом. Выйти из этой клетки — уже проблема!

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

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

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

Нью-Йоркский небоскреб

Sat, 16 May 2026 00:00:00 +0000

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

Посмотрел одно видео, захотелось пересказать.

В Нью-Йорке построили очень высокий и тонкий небоскреб. Выглядит как карандаш или шприц: высота 435 метров (1428 футов), а ширина сечения сравнима с теннисным кортом. Один этаж – одна квартира. Небоскреб предназначен для жилья, а не офисов. Это апартаменты для богачей, и слова “лакшери”, “worldclass” так и сыплются с экрана.

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

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

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

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

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

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

И вот небоскреб достроили и стали заселять. Центр мира – Америка, Нью-Йорк, Манхэттен. Вид – потрясающий, в ясную погоду простирается на километры. Ты властелин, а мелкие твари копошатся у твоих подошв.

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

Шума добавляет система насосов. Чтобы поднять воду на 400 метров, нужные мощные насосные станции, которые шумят. Да, изоляция звука, все дела. Но полностью скрыть звук от них невозможно.

Лифты. Во-первых, ехать с условного 150 этажа на первый – долго. Во-вторых, смена давления. Со школы мы знаем, что каждые 12 метров давление падает на один миллиметр ртутного столба. 400 метров – 33 миллиметра долой. Немало людей чувствительны к резкой смене высоты из-за давления.

И вот здание стоит пустое. Кто-то, конечно, купил там квартиру, однако в целом оно – призрак. Огромный гвоздь стоимостью словно из золота, который воткнули неизвестно зачем. Очередной урок, что так делать не надо.

Выводы я оставлю на следующую заметку.