Индексы и аннотации

Лента анны — запрос WHERE author_id = ? ORDER BY created_at DESC на таблице постов, которых через полгода жизни группы go-ninja будут десятки тысяч. Без индекса база читает таблицу целиком — полнотабличный скан, сортирует строки в памяти, отбрасывает чужие; в плане запроса, который покажет EXPLAIN, это будет Seq Scan плюс Sort, и время растёт линейно с числом постов. С индексом по паре author_id + created_at она идёт по упорядоченному дереву: находит начало диапазона автора и читает строки уже в нужном порядке — точечный поиск вместо скана, сортировка не нужна вовсе. Та же история с поиском по email из девятого урока: селективность колонки решает — email почти уникален, и индекс на нём превращает запрос в одно спуск по дереву, тогда как индекс на deleted_at, где почти все значения одинаковые, почти бесполезен. Но индекс не бесплатен: каждый Create из восьмого урока и каждый Update из тринадцатого обслуживает все индексы таблицы — пишет не только строку, но и дерево каждого индекса; плюс место на диске и лишний шанс планировщика выбрать неудачный план. Отсюда рабочее правило: индекс появляется от запроса, который его ищет, а не «на всякий случай». Заметьте: счётчик posts_count из тринадцатого урока — колонка, а не индекс; он экономит Count, но ленту всё равно разворачивать деревом.

Индексы объявляются в схеме — рядом с полями, рёбрами, хуками семнадцатого урока и политикой девятнадцатого, — методом func (T) Indexes() []ent.Index. Пакет ent/schema даёт builder index. index.Fields("created_at") — индекс по колонке поля; имена внутри — имена полей схемы, как они объявлены в Fields(), не имена колонок базы. index.Edges("author") — индекс по колонке внешнего ключа, которую ребро author создало ещё в пятом уроке: в таблице постов это author_id, и лента «посты автора» ищет именно её. Цепочка index.Edges("author").Fields("created_at") — составной индекс сразу по author_id и created_at. Метод Unique() превращает индекс в ограничение уникальности: поле email с field.Unique() из третьего урока уже создало уникальный индекс на одной колонке, а index.Fields("name", "website").Unique() — новый уровень: уникальна вся пара. Метод StorageKey задаёт имя индекса в базе — posts_created_idx вместо сгенерированного по умолчанию; это подарок ревью миграций из пятнадцатого урока, о котором подробнее в финале. Всё объявленное в Indexes() генератор из седьмого урока переносит в код, а миграции — в DDL: схема остаётся единственным источником правды о базе.

Составной индекс — это книга, отсортированная по двум признакам сразу: сначала по первой колонке, внутри неё по второй. Отсюда главное правило составных индексов — левый префикс: индекс (author_id, created_at) обслуживает WHERE author_id = ?, WHERE author_id = ? AND created_at > ? и WHERE author_id = ? ORDER BY created_at DESC, но запрос WHERE created_at > ? без условия на author_id не сможет взять его как основной путь: деревья отсортированы по author_id, а время внутри — искать придётся по всем веткам. Поэтому порядок объявления — не вкус, а решение: колонка равенства — первой, диапазон и сортировка — за ней. Лента анны просит именно (author_id, created_at): зафиксировали автора — и внутри его строк время уже упорядочено, ключсет-пагинация двенадцатого урока с CreatedAtLT и IDGT скачет по дереву, не трогая чужие посты. Если бы лента была глобальной — «все посты подряд по времени» — порядок развернулся бы: (created_at, id). Составных индексов на таблицу не напасёшься на каждый запрос: три-четыре осмысленных покрывают десятки запросов через левый префикс, а каждый лишний индекс тормозит мутации из тринадцатого урока. Проверяйте планы в EXPLAIN: попал ли запрос в префикс, виден ли ваш индекс.

Уникальность в ent живёт на двух этажах, и путать их нельзя. field.Unique() — уникальность одной колонки: email из третьего урока, slug поста, телефон; индекс на такой колонке создаётся автоматически. index.Fields(...).Unique() — уникальность комбинации: пара (name, website) уникальна целиком — два «анна» с разными сайтами проходят, повторение пары запрещено. Комбинация с рёбрами даёт прикладной паттерн «одно на владельца»: index.Edges("author").Fields("kind").Unique() запрещает автору иметь два поста одного вида — уникальность в границах владельца, а не всей таблицы. И нюанс, который ловит всех: SQL-уникальность не распространяется на NULL. Строка с NULL не равна другой строке с NULL — даже при одинаковом остальном; значит, Optional-колонка из четвёртого урока внутри уникальной пары — дыра в ограничении: сколько угодно строк (name, NULL) пройдут проверку. Лечится строго: колонки пары должны быть NOT NULL, либо контроль дубликатов уходит в хук семнадцатого урока, который увидит мутацию до SQL. Ниже — предсказание на этот кейс: прежде чем читать объяснение, попробуйте ответить сами.

Аннотации — способ сказать диалекту то, чего нет в общем словаре index-билдера. Все индексные аннотации живут в пакете entsql и передаются методом Annotations(...). entsql.Desc() и entsql.Asc() задают направление сортировки колонок индекса целиком, а DescColumns и AscColumns — по отдельным колонкам составного индекса; убывающий индекс ленты избавляет планировщик от обратного прохода. entsql.IndexType("hash") выбирает тип индекса для MySQL: hash мгновенен на равенстве, но слеп к диапазонам и сортировке — для лент и ключсета нужен btree, значение по умолчанию. entsql.IndexPrefix(n) — префиксный индекс: индексируются первые n символов длинной строки; для TEXT-колонок MySQL требует его обязательно, без префикса миграция откажет. entsql.IndexWhere(expr) — частичный индекс, главная герой следующего раздела. Имена и типы попадают в DDL миграций и в versioned-файлы Atlas из пятнадцатого урока — потому аннотации и называются аннотациями: они выражают намерение, а мигратор каждого диалекта решает, как его исполнить, и где-то честно разводит руками.

Четырнадцатый урок закончился обещанием: мягкое удаление пишет deleted_at, но живые строки тонут в таблице, где рядом лежат мёртвые, — и никакой обычный индекс это не лечит, потому что дерево в равной мере набито обоими. Интерсептор восемнадцатого урока вшивает DeletedAtIsNil в каждую выборку: SQL каждого запроса содержит WHERE deleted_at IS NULL — но без подходящего индекса условие всё равно работает по скану. Частичный индекс entsql.IndexWhere("deleted_at IS NULL") строит дерево только из живых строк: он меньше по размеру, не деградирует от накопления удалённых записей, а предикат интерсептора совпадает с условием индекса дословно — планировщик берёт его без раздумий. Канонический вид — лента живых постов автора: составной (author_id, created_at), убывающий по времени, с условием deleted_at IS NULL. Поддержка: Postgres и SQLite умеют частичные индексы, MySQL — нет, там остаётся обычный индекс, а условие фильтрует строки на чтении: платите размером дерева, но запрос работает. Заодно ответ на вопрос «почему бы не индексировать deleted_at просто так»: колонка, где почти все значения NULL, малоселективна, и полный индекс на ней почти бесполезен — ценен именно частичный.

Индексы — не единственное, что настраивают аннотации. entsql.Annotation на уровне схемы переопределяет имя таблицы: func (User) Annotations() []schema.Annotation { return []schema.Annotation{ entsql.Annotation{Table: "users"} } } — явная фиксация, которая спасает, когда база старше кода и таблицы зовутся не так, как сгенерирует ent. schema.Annotation — общий интерфейс: любая аннотация реализует Name() string, а мигратор читает только те, что знает. Дальше — миграции, пятнадцатый урок. automigrate сравнивает схему с базой и создаёт недостающие индексы; но у индексов есть свои правила эволюции: переименование колонок в составе индекса или новый порядок — это, чаще всего, drop и create, и в большом проекте без StorageKey вы узнаете об этом по логу миграции, когда уже поздно. Versioned-миграции Atlas фиксируют каждый индекс в SQL-файле, который проходит ревью: именно в этом файле видно, что DescColumns породил DESC в определении, IndexWhere — WHERE deleted_at IS NULL, а IndexPrefix — длину префикса. Разные диалекты дают разный DDL для одних и тех же аннотаций — и это нормально: аннотация выражает намерение, диалект решает, как его исполнить, а где намерение неподдерживаемо — там ревью и ловит проблему, а не продакшен.

Вы умеете вооружать схему: метод Indexes() с index.Fields и index.Edges, уникальные поля и уникальные пары с их NULL-дырой, составные индексы с правилом левого префикса, entsql-аннотации Desc и IndexType, IndexPrefix и IndexWhere, StorageKey для стабильных имён, entsql.Annotation{Table} на уровне схемы — и полная картина миграций из пятнадцатого урока, где каждый индекс виден в DDL. Скорость без порядка — только половина истории: ключсет двенадцатого урока опирается на составной индекс, интерсептор восемнадцатого — на частичный. Дальше — GraphQL-интеграция двадцать первого урока: entgql, автогенерация резолверов и связь графа с внешним API, где каждая связь рождает новые выборки, и держать их будет снова индекс. Домашнее задание ниже заставит индекс показать себя в плане запроса. Полный план из 25 уроков — на странице курса, уникальные поля и валидаторы — в третьем уроке, ключсет-пагинация — в двенадцатом, мягкое удаление — в четырнадцатом, миграции и Atlas — в пятнадцатом, интерсептор живых строк — в восемнадцатом.