{"canonical_url":"https://engineer.company/uk/glossary/full-text-search/","content_markdown":"# Повнотекстовий пошук\n\n## Що це таке\n\nПовнотекстовий пошук знаходить документи, що містять слова запиту, у будь-якій\nформі, якої ці слова набули, і вміє ставити найкращі збіги першими. Англійською\nце full-text search, і саме так називаються відповідні розділи документації\nPostgreSQL та SQLite. Документом тут вважають те, що застосунок шукає як одне\nціле: лист, статтю, звернення до підтримки чи заголовок і текст одного рядка\nтаблиці разом.\n\nВід порівняння за шаблоном його відрізняє робота, яку виконують ще до будь-якого\nпорівняння. Спершу текст розбивають на токени: слова, числа, адреси електронної\nпошти та інші класи. Потім кожен токен нормалізують у лексему, тобто форму,\nобрану так, щоб варіанти одного слова збігалися. Великі літери стають малими,\nстемер відтинає закінчення, а стоп-слова, такі часті, що не несуть жодного\nсигналу, відкидаються. Результат зберігають разом із позицією кожної лексеми, і\nзгодом функція ранжування може віддати перевагу документам, де слова запиту\nстоять поруч. Запит проходить той самий шлях, тож пошук за словом «рахунки» і\nдокумент, у якому написано «рахунок», зустрічаються посередині, якщо словник\nзнає мову тексту.\n\nPostgreSQL вбудовує все це в саму базу даних. Тип `tsvector` зберігає документ у\nнормалізованому вигляді, тип `tsquery` зберігає запит, а оператор `@@`\nперевіряє, чи запит збігається з документом. Конфігурація текстового пошуку\nвизначає, як саме відбувається нормалізація: який парсер ділить текст і які\nсловники перетворюють токени на лексеми. Стандартний дистрибутив постачає\nконфігурації для багатьох мов, серед них `english`, `danish`, `norwegian` і\n`swedish`, а команда psql `\\dF` показує встановлені. Української конфігурації\nсеред них у PostgreSQL 18, поточній версії документації, немає, і про це краще\nзнати заздалегідь: нижче показано, як її зібрати. SQLite пропонує ту саму ідею\nчерез розширення FTS5, де індекс тримає віртуальна таблиця, а запити до неї\nроблять оператором `MATCH`.\n\n## Чому це важливо\n\nДокументація PostgreSQL прямо пояснює, чого бракує старшим операторам. `LIKE`,\n`ILIKE` і регулярні вирази не мають лінгвістичної підтримки, тож запит «договір»\nпропускає документ зі словом «договору» чи «договорі», якщо хтось не випише\nкожну форму вручну. В українській це відчутніше, ніж в англійській: слово змінює\nне лише закінчення, а часом і голосну в корені. Ці оператори не ранжують\nрезультати, тож тисяча збігів повертається без корисного порядку. І вони не\nможуть використати звичайний індекс для такого пошуку, тож кожен запит читає\nкожен документ. Шаблон `%мова%` до того ж збігається з «умова» і «самовар», а це\nвже шум, а не повнота.\n\nЛюди вводять слова в поле пошуку й чекають документів про ці слова. В архіві\nдоговорів, службі підтримки чи каталозі товарів повнотекстовий пошук відділяє\nполе пошуку, якому довіряють, від поля, яким перестають користуватися після\nтретьої марної спроби. Ранжування важить не менше, ніж сам збіг: той, хто шукає\n«прострочена оплата», хоче бачити вгорі лист-нагадування, а не сотню рахунків,\nде слово «оплата» трапляється по разу.\n\nТе, що пошук живе в базі даних, яку ви вже маєте, дає практичну перевагу.\nПошуковий індекс змінюється в тій самій транзакції, що й дані, тож рядок можна\nзнайти, щойно його зафіксовано, а видалений рядок зникає з результатів тієї ж\nмиті. Фільтри за датою, клієнтом чи правами доступу стають звичайними умовами\n`WHERE` поруч із текстовою. Окремий пошуковий сервер уміє більше, але це друга\nсистема, яку треба наповнювати й тримати в узгодженні з першою, і кожен розрив\nміж ними перетворюється на результат, якого бракує, або на такий, що мав би вже\nзникнути.\n\nПовнотекстовий пошук має й межу, яку варто знати з самого початку: він порівнює\nслова, а не зміст. Запит «автомобіль» не приведе до документа про «легковик»,\nякщо словник синонімів не зіставить одне з одним. Векторний пошук, що порівнює\nчислові представлення змісту, закриває саме цей випадок, і два підходи часто\nпоєднують.\n\n## Як це виглядає на практиці\n\nПочнімо з мови. Вбудована конфігурація `simple` зводить слова до нижнього\nрегістру, але закінчень не відтинає, тож «договір» і «договору» залишаються для\nнеї двома різними лексемами. Задокументований шлях до кращого результату —\nсловник Hunspell, підключений через шаблон `ispell`. Файлів Ispell PostgreSQL не\nпостачає, тому словник беруть окремо: файли `.aff` і `.dic` перейменовують на\n`.affix` і `.dict`, за потреби перекодовують в UTF-8 і кладуть у каталог\n`tsearch_data` всередині `$SHAREDIR`, шлях до якого показує\n`pg_config --sharedir`. Після цього конфігурацію можна оголосити:\n\n```sql\nCREATE TEXT SEARCH DICTIONARY ukrainian_hunspell (\n    TEMPLATE = ispell, DictFile = uk_ua, AffFile = uk_ua\n);\n\nCREATE TEXT SEARCH CONFIGURATION ukrainian (COPY = pg_catalog.simple);\n\nALTER TEXT SEARCH CONFIGURATION ukrainian\n    ALTER MAPPING FOR word, hword, hword_part\n    WITH ukrainian_hunspell, simple;\n```\n\n`uk_ua` тут — базова назва файлів `uk_ua.dict` і `uk_ua.affix`, яку ви обираєте\nсамі, коли перейменовуєте їх. Типи токенів `word`, `hword` і `hword_part`\nохоплюють слова з літер поза ASCII, зокрема кирилицю, разом зі словами через\nдефіс і їхніми частинами. Порядок словників має значення. Документація\nпопереджає, що словник Ispell зазвичай знає обмежений набір слів, тож за ним має\nстояти ширший, а словник `simple` у типовому режимі приймає кожен токен і тому\nкорисний лише в кінці списку. Так слово, якого немає в Hunspell, принаймні\nпотрапить до індексу в нижньому регістрі. Перевірити результат допомагають\n`ts_lexize('ukrainian_hunspell', 'договору')`, що показує лексеми одного слова,\nі `ts_debug('ukrainian', 'текст')`, що показує, як конфігурація розбирає цілий\nрядок.\n\nДалі таблиця документів із заголовком, текстом і місцем, звідки кожен документ\nузявся. Збережений згенерований стовпець оновлює пошукову форму під час кожного\nвставлення й оновлення, а індекс GIN робить пошук швидким:\n\n```sql\nCREATE TABLE documents (\n    id         bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,\n    title      text,\n    body       text,\n    source     text NOT NULL,\n    search_vec tsvector GENERATED ALWAYS AS (\n                   setweight(to_tsvector('ukrainian', coalesce(title, '')), 'A')\n                || setweight(to_tsvector('ukrainian', coalesce(body, '')), 'D')\n               ) STORED\n);\n\nCREATE INDEX documents_search_idx ON documents USING GIN (search_vec);\n```\n\nТут працюють три деталі. Конфігурацію названо явно, `'ukrainian'`, а не залишено\nна `default_text_search_config` сеансу: саме форму `to_tsvector` із двома\nаргументами PostgreSQL може зберігати й індексувати. `coalesce` перетворює\nвідсутній заголовок чи текст на порожній рядок, бо один NULL інакше зробив би\nNULL-ом увесь документ. А `setweight` позначає кожну лексему за місцем\nпоходження: A для заголовка, D для тексту. Якщо не вказати інакше, функції\nранжування беруть для D, C, B і A ваги `{0.1, 0.2, 0.4, 1.0}`, тож слово запиту\nв заголовку важить удесятеро більше, ніж те саме слово в тексті.\n\nДля текстового пошуку документація рекомендує індекс GIN: це інвертований індекс\nз окремим записом для кожної лексеми й стисненим списком рядків, які її містять.\nGiST теж підходить, але зберігає інформацію з втратами, тому для відсіювання\nхибних збігів треба перевіряти рядок таблиці.\n\nЗапит бере слова так, як їх увів користувач:\n\n```sql\nSELECT id, title, source,\n       ts_rank_cd(search_vec, query) AS rank\nFROM   documents,\n       websearch_to_tsquery('ukrainian',\n                            'неоплачений рахунок -чернетка') AS query\nWHERE  search_vec @@ query\nORDER  BY rank DESC\nLIMIT  10;\n```\n\n`websearch_to_tsquery` читає введення так, як його читає поле пошуку в браузері.\nЗвичайні слова мають трапитися всі, у будь-якій формі, яку словник зводить до\nоднієї лексеми, текст у подвійних лапках має трапитися як фраза, слово «or»\nпропонує альтернативу, а мінус перед словом виключає його, тож цей запит\nвідкидає кожен документ, де згадано чернетку. Функція ніколи не повертає\nсинтаксичної помилки, тому вона безпечна для сирого введення. `ts_rank_cd`\nранжує за щільністю покриття, методом зі статті Кларка, Кормака й Тудоупа 1999\nроку, що також винагороджує слова запиту, які стоять поруч. Сусідня функція\n`ts_rank` рахує, як часто слова трапляються. Обидві приймають прапорець\nнормалізації: 1, наприклад, ділить ранг на одиницю плюс логарифм довжини\nдокумента, щоб довгий документ не вигравав лише тому, що він довгий.\n\nТа сама потреба проходить крізь\n[роботу компанії з даними для ШІ-агентів](/uk/ai-data/). Сторінка описує, як\nстарі PDF, скани й поштові архіви перетворюються на текст, у якому можна шукати,\nз посиланням на джерело, щоб їх можна було знайти, а не лише зберігати. Стовпець\n`source` у таблиці вище виконує саме це завдання: збіг вартий більшого, коли\nчитач може відкрити оригінал.\n\nSQLite доходить до подібного результату з меншими церемоніями. Віртуальну\nтаблицю, оголошену як `CREATE VIRTUAL TABLE notes USING fts5(title, body)`,\nзапитують умовою `WHERE notes MATCH 'рахунок NOT чернетка'`, а\n`ORDER BY bm25(notes)` ставить найкращі збіги першими: FTS5 повертає кращі збіги\nяк менші числа, тож звичайний порядок за зростанням і є правильним. Типовий\nтокенізатор `unicode61` зводить кирилицю до нижнього регістру, але не стемить,\nтож «договір», «договору» і «договорі» для нього три різні терміни. Токенізатор\n`porter`, що додає стемінг, за документацією призначений лише для англійської.\nДля українського тексту в SQLite практичніший токенізатор `trigram`: він\nіндексує кожну послідовність із трьох символів, тож запит `MATCH 'догов'`\nзнаходить усі три форми незалежно від регістру. Ціна — більший індекс, а\nпідрядок з одного чи двох символів, за документацією, рядків не повертає.\n\n## Де виникають проблеми\n\n**Індекс, якого запит не торкається.** Індекс за виразом, побудований на\n`to_tsvector('ukrainian', body)`, обслуговує лише запити, що повторюють саме цей\nвираз. Запит, записаний як `to_tsvector(body)`, покладається на типову\nконфігурацію сеансу й читає всю таблицю. Зберігайте вектор у згенерованому\nстовпці, як вище, і звертайтеся до стовпця: тоді запит не може розійтися з\nіндексом.\n\n**Один NULL, що ховає документ.** `to_tsvector(NULL)` повертає NULL, а\nконкатенація відсутнього заголовка (NULL) з текстом теж дає NULL, тож рядок без\nзаголовка мовчки випадає з кожного пошуку. Обгортайте кожне поле в `coalesce`.\n\n**Сире введення в `to_tsquery`.** `to_tsquery` чекає власного синтаксису\nоператорів і прощає менше, ніж інші функції перетворення, тож користувач, що\nввів незакриту дужку чи зайвий амперсанд, отримує сторінку з помилкою.\nПередавайте введений текст через `websearch_to_tsquery` або через\n`plainto_tsquery`, коли оператори не потрібні зовсім.\n\n**Не та мова.** Текст однією мовою, проіндексований конфігурацією для іншої,\nстемлять чужі правила й фільтрують чужі стоп-слова, тож половина форм так і не\nзустрічається. Обирайте конфігурацію за мовою тексту. Колекція кількома мовами\nможе зберігати назву конфігурації в окремому стовпці й індексувати\n`to_tsvector(config_name, body)`, якщо запити звертаються до того самого\nстовпця.\n\n**Словник змінився, а сеанси про це не знають.** Сеанс читає файли словника лише\nраз, коли вперше його використовує, тож після оновлення `uk_ua.dict` чи файлу\nсинонімів відкриті з'єднання й далі працюють зі старою версією. Виконайте\n`ALTER TEXT SEARCH DICTIONARY` для цього словника; документація допускає навіть\nформальну команду, що не змінює параметрів, і сеанси перечитають файли.\nПам'ятайте й про вже збережені вектори: їх обчислено старим словником, тож якщо\nзміна стосується того, до якої лексеми зводиться слово, старі рядки треба\nперезаписати, інакше вони не зустрінуться з новими запитами.\n\n**Апостроф, що розрізає слово.** У словах «об'єкт», «м'ясо» чи «зв'язок»\nапостроф належить слову, але токенізатори часто вважають його розділовим знаком.\nSQLite FTS5 з `unicode61` ділить «об'єкт» на «об» і «єкт», коли апостроф набрано\nяк `'` чи `’`, і тримає слово цілим лише з `ʼ` (U+02BC), який Unicode відносить\nдо літер. Документ, набраний з `ʼ`, і запит із `'` так і не зустрінуться. Парсер\nPostgreSQL визначає, що є літерою, за налаштуванням локалі `lc_ctype`, тож\nперевірте свою базу через `ts_debug`. Зводьте всі апострофи до одного символу\nоднією функцією і в тексті перед індексацією, і в запиті.\n\n**Ранжування кожного збігу.** Ранжування читає `tsvector` кожного рядка, що\nзбігся, і документація попереджає, що це може впиратися у введення-виведення й\nпрацювати повільно. Запит з одного слова, що збігається з половиною таблиці,\nзмушує базу ранжувати половину таблиці, перш ніж `LIMIT` залишить десять рядків.\nЗвужуйте кандидатів звичайними умовами, як-от діапазоном дат чи клієнтом, і\nтримайте вектор збереженим, щоб його не обчислювали заново для кожного рядка.\n\n**Ранг, показаний як відсоток.** Функції ранжування не бачать колекції загалом,\nтож ранг неможливо чесно перетворити на «релевантність 87%». Прапорець\nнормалізації 32 стискає ранги в проміжок від нуля до одиниці, але документація\nназиває це косметичною зміною. Використовуйте ранг, щоб упорядкувати результати,\nі ні для чого більше.\n\n**Підсвічування, що несе розмітку.** `ts_headline` повертає уривок із\nпозначеними словами запиту, а саме цього й потребує сторінка результатів. Проте\nPostgreSQL попереджає, що її вивід не гарантовано безпечний для прямого\nвставлення у вебсторінку. Документ, що містить HTML, може занести на сторінку\nскрипт. Прибирайте розмітку з вхідного тексту або пропускайте вивід через\nHTML-санітайзер. Функція працює з оригінальним текстом, а не з вектором, тож\nвикликайте її лише для рядків на сторінці, після `LIMIT`, а не для кожного\nзбігу.\n\n**Документи, завеликі для одного вектора.** `tsvector` має бути меншим за 1 МБ і\nзберігає не більше 256 позицій на лексему. Ціла книга чи річний архів протоколів\nв одному рядку впирається в обидва обмеження. Діліть довгі документи на розділи\nчи сторінки: це ще й дає кожному результату точніше місце, на яке він вказує.\n\n**Фрагменти й артикули.** Повнотекстовий пошук порівнює цілі лексеми, тож запит\n«рах» рахунків не знаходить, а артикул на кшталт `AB-1042-X` парсер може розбити\nна частини. Тримайте звичайний індекс на стовпцях, за якими шукають точне\nзначення, а в SQLite для пошуку підрядків беріть токенізатор `trigram`.\n\n**Індекс SQLite, що розходиться зі своєю таблицею.** Таблиця FTS5, оголошена з\n`content=`, читає текст з іншої таблиці, і документація залишає узгодженість\nобох на користувача. Коли вони розходяться, запити повертають рядки, що ніби\nсуперечать одне одному. Створіть тригери на вставлення, оновлення й видалення,\nякі показує документація, у тій самій міграції, що й віртуальну таблицю.\n\n## Що почитати далі\n\n- [Introduction to full text search](https://www.postgresql.org/docs/current/textsearch-intro.html)\n  — визначення документів, токенів, лексем і конфігурацій у PostgreSQL і\n  пояснення, чого бракує `LIKE` та регулярним виразам.\n- [Tables and Indexes](https://www.postgresql.org/docs/current/textsearch-tables.html)\n  — пошук у таблиці, індекс за виразом проти збереженого згенерованого стовпця і\n  чому конфігурацію треба називати явно.\n- [Controlling Text Search](https://www.postgresql.org/docs/current/textsearch-controls.html)\n  — ваги, `websearch_to_tsquery`, `ts_rank` і `ts_rank_cd`, прапорці\n  нормалізації та застереження щодо `ts_headline`.\n- [Dictionaries](https://www.postgresql.org/docs/current/textsearch-dictionaries.html)\n  — шаблони словників, Ispell і Hunspell, де лежать файли словників і коли сеанс\n  їх перечитує.\n- [Limitations](https://www.postgresql.org/docs/current/textsearch-limitations.html)\n  — обмеження розміру лексем, векторів, позицій і запитів.\n- [SQLite FTS5 Extension](https://www.sqlite.org/fts5.html) — віртуальні\n  таблиці, оператор `MATCH`, токенізатори `unicode61`, `porter` і `trigram`,\n  `bm25()` і таблиці із зовнішнім вмістом.\n\n\u003chttps://engineer.company/uk/glossary/full-text-search/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Що таке повнотекстовий пошук: лексеми, GIN-індекси й ранжування в PostgreSQL, словник для української, SQLite FTS5 і де пошук ламається.","formats":{"gemtext":"https://engineer.company/uk/glossary/full-text-search/index.gmi","gopher":"https://engineer.company/uk/glossary/full-text-search/gophermap","html":"https://engineer.company/uk/glossary/full-text-search/","json":"https://engineer.company/uk/glossary/full-text-search/index.json","markdown":"https://engineer.company/uk/glossary/full-text-search/index.md","pdf":"https://engineer.company/uk/glossary/full-text-search/index.pdf"},"kind":"page","language":"uk","title":"Що таке повнотекстовий пошук?","url":"https://engineer.company/uk/glossary/full-text-search/","version":1}