Files
mtusi2026lab2/student-tests/explain_queries.py
T
kokorindenis 5c193f24f7
Skeleton contracts / contracts (pull_request) Canceled after 0s
lab 2 solution
2026-10-23 17:24:27 +03:00

446 lines
24 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
"""Планы запросов на засеянных данных: индекс, порядок и цена OFFSET.
python student-tests/seed_messages.py # один раз, ~10 000 сообщений
python student-tests/explain_queries.py # все планы
python student-tests/explain_queries.py --only chats # только список чатов
Скрипт проверяет не «индекс существует», а «индекс используется»: он берёт те же
по форме запросы, что отправляет `src/messenger/repository.py`, и смотрит на
`EXPLAIN (ANALYZE, BUFFERS, VERBOSE)`.
Контрпример без индекса выполняется внутри транзакции с `DROP INDEX ... ROLLBACK`,
поэтому схема в базе не меняется. План каждого контрольного запроса снимается
дважды — текстом для отчёта и JSON для вердиктов: psql возвращает план набором
строк, и разложить его на два формата в одном вызове нельзя.
"""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
HERE = Path(__file__).resolve().parent
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
import harness # noqa: E402 (путь добавлен выше)
MESSAGES_INDEX = "ix_messages_chat_id_created_at_id"
CHATS_INDEX = "ix_chat_members_user_id_chat_id"
DEFAULT_PAGE = 200
PLAN_OPTIONS = "ANALYZE, BUFFERS, VERBOSE, FORMAT "
MESSAGE_COLUMNS = ("messages.id, messages.chat_id, messages.sender_id, "
"messages.text, messages.created_at")
CHECKS: list[tuple[bool, str, str]] = []
def say(message: str = "") -> None:
print(message, flush=True)
def section(title: str) -> None:
say()
say("=" * 72)
say(title)
say("=" * 72)
def check(ok: bool, what: str, detail: str = "") -> bool:
CHECKS.append((ok, what, detail))
say(" [%s] %s%s" % ("OK" if ok else "FAIL", what, (" — " + detail) if detail else ""))
return ok
def show_plan(sql: str) -> None:
"""Печатает текстовый план: его читает человек."""
say(" $ %s" % " ".join(sql.split()))
for line in harness.psql("EXPLAIN (%s TEXT) %s" % (PLAN_OPTIONS, sql), timeout=600).splitlines():
say(" " + line.rstrip())
def plan_json(sql: str) -> dict:
"""Возвращает разобранный план: по нему выносятся вердикты."""
return parse_plan(harness.psql("EXPLAIN (%s JSON) %s" % (PLAN_OPTIONS, sql), timeout=600))
def parse_plan(raw: str) -> dict:
"""Вырезает JSON-план из вывода psql.
Внутри транзакции psql печатает ещё и теги команд (BEGIN, SET, ROLLBACK),
поэтому брать весь stdout нельзя.
"""
start, end = raw.find("["), raw.rfind("]")
if start < 0 or end < 0:
raise ValueError("в выводе psql нет JSON-плана: %r" % raw[:200])
return json.loads(raw[start:end + 1])[0]
def nodes(plan: dict) -> list[dict]:
"""Все узлы плана, включая вложенные."""
found = [plan["Plan"]]
index = 0
while index < len(found):
found.extend(found[index].get("Plans", []))
index += 1
return found
def node_types(plan: dict) -> str:
return ", ".join(node["Node Type"] for node in nodes(plan))
def scans(plan: dict, relation: str) -> list[dict]:
"""Узлы, которыми читается указанное отношение.
Вопрос «читается ли таблица целиком» относится к конкретной таблице: в
запросе списка чатов планировщик вправе перебрать маленькую `chats` и всё
равно взять `chat_members` по индексу. Поэтому вердикты выносятся не по
плану целиком, а по узлам одной таблицы.
"""
return [node for node in nodes(plan) if node.get("Relation Name") == relation]
def scan_types(plan: dict, relation: str) -> str:
"""Типы узлов чтения отношения: `Seq Scan` здесь — плохой знак."""
return ", ".join(node["Node Type"] for node in scans(plan, relation)) or "узлов нет"
def rows_touched(plan: dict) -> int:
"""Сколько строк прошло через самый работящий узел плана."""
return max(node.get("Actual Rows", 0) for node in nodes(plan))
def rows_examined(plan: dict, relation: str) -> int:
"""Сколько строк отношение реально просмотрело.
Строки, отброшенные фильтром, тоже прочитаны — в `Actual Rows` они не
попадают, поэтому складываются обе величины.
"""
return sum(node.get("Actual Rows", 0)
+ node.get("Rows Removed by Filter", 0)
+ node.get("Rows Removed by Index Recheck", 0)
for node in scans(plan, relation))
def describe(plan: dict) -> str:
return "execution %.3f ms, shared hit %d, read %d" % (
plan["Execution Time"],
plan["Plan"].get("Shared Hit Blocks", 0),
plan["Plan"].get("Shared Read Blocks", 0),
)
def without_index(index: str, options: str, sql: str) -> str:
"""Один контрольный запрос без индекса; ROLLBACK возвращает схему как была."""
return harness.psql(
"BEGIN; DROP INDEX %s; EXPLAIN (%s %s) %s ROLLBACK;" % (index, PLAN_OPTIONS, options, sql),
timeout=600,
)
def page_position(chat_id: str, offset: int) -> tuple[str, str]:
"""Пара (created_at, id) на указанной позиции: это и есть курсор страницы.
Для поиска пары OFFSET уместен: измеряется не он, а запрос страницы.
"""
created_at, item_id = harness.psql(
"SELECT created_at, id FROM messages WHERE chat_id = '%s' "
"ORDER BY created_at, id OFFSET %d LIMIT 1;" % (chat_id, offset)
).strip().split("|")
return created_at, item_id
def keyset_query(chat_id: str, cursor: tuple[str, str], limit: int) -> str:
"""Тот же запрос, что собирает repository._page для истории чата."""
return (
"SELECT %s FROM messages WHERE chat_id = '%s' "
"AND (created_at, id) > ('%s'::timestamptz, '%s'::uuid) "
"ORDER BY created_at, id LIMIT %d;" % (MESSAGE_COLUMNS, chat_id, cursor[0], cursor[1], limit)
)
def offset_query(chat_id: str, offset: int, limit: int) -> str:
"""Страница «с начала, но пропусти N» — так делать нельзя."""
return (
"SELECT %s FROM messages WHERE chat_id = '%s' "
"ORDER BY created_at, id OFFSET %d LIMIT %d;" % (MESSAGE_COLUMNS, chat_id, offset, limit)
)
def chats_query(user_id: str, limit: int) -> str:
"""Тот же запрос, что собирает repository.list_chats."""
return (
"SELECT chats.id, chats.title, chats.created_at "
"FROM chats JOIN chat_members ON chats.id = chat_members.chat_id "
"WHERE chat_members.user_id = '%s'::uuid "
"ORDER BY chats.created_at, chats.id LIMIT %d;" % (user_id, limit)
)
def history_plans(arguments) -> bool:
"""Разделы 2–4: страница истории чата и её цена без индекса.
False — данных для эксперимента нет; что делать, уже напечатано.
"""
chat_id = arguments.chat_id or harness.psql(
"SELECT chat_id FROM messages GROUP BY chat_id ORDER BY count(*) DESC LIMIT 1;"
).strip()
if not chat_id:
say(" В базе нет сообщений. Сначала запустите seed_messages.py.")
return False
history = int(harness.psql("SELECT count(*) FROM messages WHERE chat_id = '%s';" % chat_id))
say(" чат %s: %d сообщений" % (chat_id, history))
if history < 1000:
say(" На короткой истории планировщик выберет последовательное чтение, и")
say(" эксперимент ничего не покажет. Запустите seed_messages.py.")
return False
position = history - arguments.page_size
cursor = page_position(chat_id, position)
say(" позиция страницы: %d, курсор (created_at, id) = (%s, %s)" % (position, *cursor))
say(" размер messages: %s, индекс %s: %s"
% (harness.psql("SELECT pg_size_pretty(pg_total_relation_size('messages'));").strip(),
MESSAGES_INDEX,
harness.psql("SELECT pg_size_pretty(pg_relation_size('%s'));" % MESSAGES_INDEX).strip()))
duplicates = harness.psql(
"SELECT count(*) FROM (SELECT created_at FROM messages WHERE chat_id = '%s' "
"GROUP BY created_at HAVING count(*) > 1) AS shared;" % chat_id).strip()
say(" моментов времени, которые делят несколько сообщений: %s "
"(порядок обязан разрешать ничью по id)" % duplicates)
section("2. Страница истории по курсору (keyset)")
keyset_sql = keyset_query(chat_id, cursor, arguments.page_size)
show_plan(keyset_sql)
keyset = plan_json(keyset_sql)
check(MESSAGES_INDEX in json.dumps(keyset), "использован именно %s" % MESSAGES_INDEX)
check("Seq Scan" not in node_types(keyset),
"история не читается последовательно", node_types(keyset))
removed = sum(node.get("Rows Removed by Filter", 0) for node in nodes(keyset))
check(removed < 10 * arguments.page_size,
"курсор отсекает строки индексом, а не фильтром",
"Rows Removed by Filter: %d" % removed)
check(rows_touched(keyset) <= 2 * arguments.page_size,
"прочитано не больше двух страниц", "%d строк" % rows_touched(keyset))
say(" %s" % describe(keyset))
if "Sort" in node_types(keyset):
estimate = keyset["Plan"]["Plans"][0].get("Plan Rows", 0)
say(" Планировщик предпочёл bitmap-чтение и сортировку: по его оценке под")
say(" условие попадает %d строк, и отсортировать их дешевле, чем идти по"
% estimate)
say(" индексу. Оценка занижена, но оба плана читают десятки блоков вместо")
say(" всей истории; на плане ниже видно, что порядок тоже даёт индекс.")
else:
say(" Сортировки в плане нет: порядок задаёт индекс.")
section("2б. Тот же запрос, когда bitmap-чтение выключено")
say(" $ BEGIN; SET LOCAL enable_bitmapscan = off; EXPLAIN (...); ROLLBACK;")
for line in harness.psql(
"BEGIN; SET LOCAL enable_bitmapscan = off; EXPLAIN (%s TEXT) %s ROLLBACK;"
% (PLAN_OPTIONS, keyset_sql), timeout=600
).splitlines():
say(" " + line.rstrip())
ordered = parse_plan(harness.psql(
"BEGIN; SET LOCAL enable_bitmapscan = off; EXPLAIN (%s JSON) %s ROLLBACK;"
% (PLAN_OPTIONS, keyset_sql), timeout=600))
check("Index Scan" in node_types(ordered) or "Index Only Scan" in node_types(ordered),
"индекс отдаёт страницу по порядку (Index Scan)", node_types(ordered))
check("Sort" not in node_types(ordered),
"сортировки нет: порядок (created_at, id) даёт индекс", node_types(ordered))
say(" %s" % describe(ordered))
say(" Оба плана читают десятки блоков вместо всей истории: индекс нужен не")
say(" «на всякий случай», а потому что без него страница требует полного чтения.")
section("3. Контрпример: тот же запрос без индекса")
say(" Индекс удаляется и возвращается внутри одной транзакции:")
say(" $ BEGIN; DROP INDEX %s; EXPLAIN (...); ROLLBACK;" % MESSAGES_INDEX)
for line in without_index(MESSAGES_INDEX, "TEXT", keyset_sql).splitlines():
say(" " + line.rstrip())
without = parse_plan(without_index(MESSAGES_INDEX, "JSON", keyset_sql))
check("Seq Scan" in scan_types(without, "messages"),
"без индекса появляется последовательное чтение", scan_types(without, "messages"))
check("Sort" in node_types(without), "без индекса появляется сортировка", node_types(without))
examined = rows_examined(keyset, "messages")
check(rows_examined(without, "messages") >= history,
"без индекса читается вся история чата",
"просмотрено %d строк" % rows_examined(without, "messages"))
check(examined < history // 10,
"с индексом просматривается малая доля истории",
"%d строк против %d" % (examined, history))
check(without["Execution Time"] > keyset["Execution Time"],
"индекс ускоряет страницу", "%.3f ms против %.3f ms"
% (keyset["Execution Time"], without["Execution Time"]))
say(" %s" % describe(without))
say(" ускорение: x%.1f" % (without["Execution Time"] / max(keyset["Execution Time"], 0.001)))
presence = harness.psql(
"SELECT count(*) FROM pg_indexes WHERE indexname = '%s';" % MESSAGES_INDEX).strip()
check(presence == "1", "ROLLBACK вернул схему: индекс на месте (найдено %s)" % presence)
section("4. OFFSET против курсора на той же позиции")
# Курсор указывает на последнюю отданную строку, поэтому её же пропускает
# OFFSET: так обе страницы обязаны вернуть ровно один и тот же набор.
offset_sql = offset_query(chat_id, position + 1, arguments.page_size)
show_plan(offset_sql)
offset = plan_json(offset_sql)
same_rows = harness.psql(keyset_sql).strip() == harness.psql(offset_sql).strip()
check(same_rows, "обе страницы возвращают одни и те же строки")
check(offset["Execution Time"] > keyset["Execution Time"],
"OFFSET медленнее курсора",
"%.3f ms против %.3f ms" % (offset["Execution Time"], keyset["Execution Time"]))
check(rows_touched(offset) >= position,
"OFFSET читает всё, что было до страницы", "%d строк" % rows_touched(offset))
say(" %s" % describe(offset))
say(" Задержка страницы по курсору не зависит от её номера, а OFFSET читает")
say(" всю предысторию заново на каждой странице.")
return True
def seeded_owner() -> str:
"""Владелец засеянного списка чатов — тот же пользователь, что и в длинной истории.
«Пользователя с наибольшим числом чатов» брать нельзя: у засеянного шумового
их 2000 из 3105, и планировщик там законно предпочтёт перебор. Такой
эксперимент показал бы не пользу индекса, а порог его применимости —
он вынесен в раздел 5б.
"""
return harness.psql(
"SELECT chat_members.user_id FROM messages "
"JOIN chat_members ON chat_members.chat_id = messages.chat_id "
"GROUP BY chat_members.user_id "
"ORDER BY count(messages.id) DESC, chat_members.user_id LIMIT 1;"
).strip()
def busiest_user() -> tuple[str, int]:
"""Пользователь с самой большой долей таблицы участников и число его чатов."""
row = harness.psql(
"SELECT user_id, count(*) FROM chat_members GROUP BY user_id "
"ORDER BY count(*) DESC, user_id LIMIT 1;"
).strip()
if not row:
return "", 0
user_id, count = row.split("|")
return user_id, int(count)
def selectivity_note(busiest: tuple[str, int], owner: str, members_total: int) -> None:
"""Раздел 5б: где индекс перестаёт быть выгодным.
Вердиктов здесь нет: план для пользователя с большой долей таблицы зависит
от статистики, и его дело — показать границу, а не подтвердить индекс.
"""
user_id, chats = busiest
section("5б. Справка: пользователь с большой долей таблицы")
if not user_id or user_id == owner:
say(" В данных нет пользователя, который делил бы таблицу участников так,")
say(" чтобы перебор оказался дешевле: индекс выгоден для всех.")
return
say(" %s — участник %d чатов из %d (%d%% таблицы)."
% (user_id, chats, members_total, round(100 * chats / members_total)))
say(" Здесь индекс не нужен, и планировщик его не берёт: перебрать %d строк" % members_total)
say(" дешевле, чем поднимать две тысячи строк по индексу. Это граница")
say(" применимости индекса, а не его дефект: у обычного пользователя чатов")
say(" мало, и индекс рассчитан на него.")
show_plan(chats_query(user_id, DEFAULT_PAGE))
say(" %s" % describe(plan_json(chats_query(user_id, DEFAULT_PAGE))))
def chats_plans(arguments, owner: str, busiest: tuple[str, int]) -> bool:
"""Разделы 5–6: список чатов пользователя и цена отказа от индекса."""
if not owner:
say(" В базе нет участников чатов. Сначала запустите seed_messages.py.")
return False
section("5. Список чатов пользователя")
chats_sql = chats_query(owner, arguments.page_size)
show_plan(chats_sql)
chats = plan_json(chats_sql)
check(CHATS_INDEX in json.dumps(chats), "использован именно %s" % CHATS_INDEX)
check("Seq Scan" not in scan_types(chats, "chat_members"),
"участники читаются по индексу, а не перебором",
scan_types(chats, "chat_members"))
members_total = int(harness.psql("SELECT count(*) FROM chat_members;"))
member_rows = rows_examined(chats, "chat_members")
check(member_rows < members_total,
"просмотрены участники пользователя, а не все строки таблицы",
"%d строк из %d" % (member_rows, members_total))
say(" %s" % describe(chats))
say(" Порядок в этом запросе задаёт таблица chats (created_at живёт в ней),")
say(" поэтому узел Sort ожидаем: индекс отдаёт только чаты пользователя, а")
say(" сортируются его строки, а не вся таблица. Убрать этот Sort можно было")
say(" бы дублированием created_at в chat_members, но это денормализация")
say(" ради сортировки небольшой выборки. Таблицу chats планировщик при этом")
say(" перебирает целиком — здесь это дешевле индекса, и на данных большего")
say(" размера план изменится.")
selectivity_note(busiest, owner, members_total)
section("6. Контрпример: список чатов без индекса")
say(" $ BEGIN; DROP INDEX %s; EXPLAIN (...); ROLLBACK;" % CHATS_INDEX)
for line in without_index(CHATS_INDEX, "TEXT", chats_sql).splitlines():
say(" " + line.rstrip())
chats_without = parse_plan(without_index(CHATS_INDEX, "JSON", chats_sql))
check("Seq Scan" in scan_types(chats_without, "chat_members"),
"без индекса участники перебираются целиком",
scan_types(chats_without, "chat_members"))
check(rows_examined(chats_without, "chat_members") > member_rows,
"индекс сокращает объём чтения",
"%d строк против %d" % (member_rows, rows_examined(chats_without, "chat_members")))
say(" %s" % describe(chats_without))
return True
def summary() -> int:
"""Итог по выполненным проверкам; он же код возврата."""
section("Итог")
for ok, what, detail in CHECKS:
say(" [%s] %s%s" % ("OK" if ok else "FAIL", what, (" — " + detail) if detail else ""))
failed = [what for ok, what, _ in CHECKS if not ok]
say()
say(" проверок: %d, провалено: %d" % (len(CHECKS), len(failed)))
say("РЕЗУЛЬТАТ: %s" % ("PASS" if not failed else "FAIL"))
return 0 if not failed else 1
def main() -> int:
parser = argparse.ArgumentParser(description="Планы запросов лабораторной 2")
parser.add_argument("--only", choices=("all", "messages", "chats"), default="all",
help="какие планы снимать (по умолчанию все)")
parser.add_argument("--chat-id", default="", help="чат с историей (по умолчанию самый длинный)")
parser.add_argument("--page-size", type=int, default=DEFAULT_PAGE)
arguments = parser.parse_args()
section("1. Данные под экспериментом")
say(" всего сообщений: %s" % harness.psql("SELECT count(*) FROM messages;").strip())
say(" всего чатов: %s, участников: %s"
% (harness.psql("SELECT count(*) FROM chats;").strip(),
harness.psql("SELECT count(*) FROM chat_members;").strip()))
owner = ""
busiest = ("", 0)
if arguments.only in ("all", "chats"):
busiest = busiest_user()
owner = seeded_owner() or busiest[0]
if owner:
say(" владелец засеянного списка чатов: %s, чатов у него %s"
% (owner, harness.psql(
"SELECT count(*) FROM chat_members WHERE user_id = '%s';" % owner).strip()))
done = True
if arguments.only in ("all", "messages"):
done = history_plans(arguments)
if done and arguments.only in ("all", "chats"):
done = chats_plans(arguments, owner, busiest)
return summary() if done else 1
if __name__ == "__main__":
try:
raise SystemExit(main())
except SystemExit:
raise
except Exception as error: # noqa: BLE001
say()
say("ОШИБКА: %s: %s" % (type(error).__name__, error))
raise SystemExit(1) from error