Функции и операторы текстового поиска

В Таблице 41, Таблице 42 и Таблице 43 собраны функции и операторы, предоставляемые для полнотекстового поиска. Подробное описание механизма текстового поиска в QHB см. в главе Полнотекстовый поиск.

Таблица 41. Операторы текстового поиска

Оператор
	Описание Пример(ы)
tsvector @@ tsquery → boolean tsquery @@ tsvector → boolean
	Аргумент типа tsvector соответствует аргументу типа tsquery? (Эти аргументы можно передавать в любом порядке.) `to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat') → t`
text @@ tsquery → boolean
	Текстовая строка, преобразованная после неявного вызова функции to_tsvector(), соответствует tsquery? `'fat cats ate rats' @@ to_tsquery('cat & rat') → t`
tsvector @@@ tsquery → boolean tsquery @@@ tsvector → boolean
	Это устаревший синоним для `@@`. `to_tsvector('fat cats ate rats') @@@ to_tsquery('cat & rat') → t`
tsvector \|\| tsvector → tsvector
	Конкатенирует два значения tsvector. Если в обоих аргументах содержатся позиции лексем, позиции второго аргумента корректируются соответствующим образом. `'a:1 b:2'::tsvector \|\| 'c:1 d:2 b:3'::tsvector → 'a':1 'b':2,5 'c':3 'd':4`
tsquery && tsquery → tsquery
	Выполняет логическую операцию И с двумя значениями tsquery, создавая запрос, который соответствует документам, соответствующим обоим входным запросам. `'fat \| rat'::tsquery && 'cat'::tsquery → ( 'fat' \| 'rat' ) & 'cat'`
tsquery \|\| tsquery → tsquery
	Выполняет логическую операцию ИЛИ с двумя значениями tsquery, создавая запрос, который соответствует документам, соответствующим любому из входных запросов. `'fat \| rat'::tsquery \|\| 'cat'::tsquery → 'fat' \| 'rat' \| 'cat'`
!! tsquery → tsquery
	Выполняет логическую операцию НЕ со значением tsquery, создавая запрос, который соответствует документам, не соответствующим входному запросу. `!! 'cat'::tsquery → !'cat'`
tsquery <-> tsquery → tsquery
	Конструирует фразовый запрос, который будет соответствовать документам, если два входных запроса соответствуют идущим подряд лексемам. `to_tsquery('fat') <-> to_tsquery('rat') → 'fat' <-> 'rat'`
tsquery @> tsquery → boolean
	Первый аргумент типа tsquery содержит второй? (Здесь учитывается только факт нахождения всех лексем одного запроса в другом, а объединение операторов игнорируется.) `'cat'::tsquery @> 'cat & rat'::tsquery → f`
tsquery <@ tsquery → boolean
	Первый аргумент типа tsquery содержится во втором? (Здесь учитывается только факт нахождения всех лексем одного запроса в другом, а объединение операторов игнорируется.) `'cat'::tsquery <@ 'cat & rat'::tsquery → t` `'cat'::tsquery <@ '!cat & rat'::tsquery → t`

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

Таблица 42. Функции текстового поиска

Функция
	Описание Пример(ы)
array_to_tsvector ( text[] ) → tsvector
	Преобразует массив лексем в формат tsvector. Заданные строки используются как есть без дополнительной обработки. `array_to_tsvector('{fat,cat,rat}'::text[]) → 'cat' 'fat' 'rat'`
get_current_ts_config ( ) → regconfig
	Возвращает OID текущей конфигурации текстового поиска по умолчанию (заданной параметром default_text_search_config). `get_current_ts_config() → english`
length ( tsvector ) → integer
	Возвращает количество лексем в заданном значении tsvector. `length('fat:2,4 cat:3 rat:5A'::tsvector) → 3`
numnode ( tsquery ) → integer
	Возвращает количество лексем и операторов в заданном значении tsquery. `numnode('(fat & rat) \| cat'::tsquery) → 5`
plainto_tsquery ( [ конфигурация regconfig, ] запрос text ) → tsquery
	Преобразует текст в формат tsquery, нормализуя слова согласно указанной или стандартной конфигурации. Все пунктуационные знаки в этой строке при этом игнорируются (она не определяет операторы запроса). Результирующий запрос соответствует документам, содержащим все слова текста, отличные от стоп-слов. `plainto_tsquery('english', 'The Fat Rats') → 'fat' & 'rat'`
phraseto_tsquery ( [ конфигурация regconfig, ] запрос text ) → tsquery
	Преобразует текст в формат tsquery, нормализуя слова согласно указанной или стандартной конфигурации. Все пунктуационные знаки в этой строке при этом игнорируются (она не определяет операторы запроса). Результирующий запрос соответствует фразам, содержащим все слова текста, отличные от стоп-слов. `phraseto_tsquery('english', 'The Fat Rats') → 'fat' <-> 'rat'` `phraseto_tsquery('english', 'The Cat and Rats') → 'cat' <2> 'rat'`
websearch_to_tsquery ( [ конфигурация regconfig, ] запрос text ) → tsquery
	Преобразует текст в формат tsquery, нормализуя слова согласно указанной или стандартной конфигурации. Последовательности слов в кавычках преобразуются в проверки фраз. Слово «or» воспринимается как формирующее оператор ИЛИ, а символ минуса формирует оператор НЕ; другие пунктуационные знаки игнорируются. Это примерно соответствует поведению некоторых распространенных инструментов поиска интернете. `websearch_to_tsquery('english', '"fat rat" or cat dog') → 'fat' <-> 'rat' \| 'cat' & 'dog'`
querytree ( tsquery ) → text
	Создает представление индексируемой части tsquery. Пустой результат или просто T означают, что запрос неиндексируемый. `querytree('foo & ! bar'::tsquery) → 'foo'`
setweight ( вектор tsvector, вес "char" ) → tsvector
	Присваивает вес каждому элементу вектора. `setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A') → 'cat':3A 'fat':2A,4A 'rat':5A`
setweight ( вектор tsvector, вес "char", лексемы text[] ) → tsvector
	Присваивает вес элементам вектора, перечисленным в списке лексем. `setweight('fat:2,4 cat:3 rat:5,6B'::tsvector, 'A', '{cat,rat}') → 'cat':3A 'fat':2,4 'rat':5A,6A`
strip ( tsvector ) → tsvector
	Убирает позиции и веса из значения tsvector. `strip('fat:2,4 cat:3 rat:5A'::tsvector) → 'cat' 'fat' 'rat'`
to_tsquery ( [ конфигурация regconfig, ] запрос text ) → tsquery
	Преобразует текст в формат tsquery, нормализуя слова согласно указанной или стандартной конфигурации. Слова должны соединяться допустимыми операторами типа tsquery. `to_tsquery('english', 'The & Fat & Rats') → 'fat' & 'rat'`
to_tsvector ( [ конфигурация regconfig, ] документ text ) → tsvector
	Преобразует текст в формат tsquery, нормализуя слова согласно указанной или стандартной конфигурации. В результат будет включена информация о позициях слов. `to_tsvector('english', 'The Fat Rats') → 'fat':2 'rat':3`
to_tsvector ( [ конфигурация regconfig, ] документ json ) → tsvector to_tsvector ( [ конфигурация regconfig, ] документ jsonb ) → tsvector
	Преобразует все строковые значения в документе JSON в формат tsvector, нормализуя слова согласно указанной или стандартной конфигурации. Затем результаты конкатенируются в порядке следования в документе, формируя выходное значение. Информация о позициях слов генерируется таким образом, словно между каждой парой строковых значений находится одно стоп-слово. (Учтите, что в случае jsonb «порядок следования в документе» полей объекта JSON зависит от реализации; разница показана в примерах.) `to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::json) → 'dog':5 'fat':2 'rat':3` `to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::jsonb) → 'dog':1 'fat':4 'rat':5`
json_to_tsvector ( [ конфигурация regconfig, ] документ json, фильтр jsonb ) → tsvector jsonb_to_tsvector ( [ конфигурация regconfig, ] документ jsonb, фильтр jsonb ) → tsvector
	Выбирает в документе JSON все элементы, запрошенные фильтром и преобразует каждый в формат tsvector, нормализуя слова согласно указанной или стандартной конфигурации. Затем результаты конкатенируются в порядке следования в документе, формируя выходное значение. Информация о позициях слов генерируется таким образом, словно между каждой парой строковых значений находится одно стоп-слово. (Учтите, что в случае jsonb «порядок следования в документе» полей объекта JSON зависит от реализации.) Аргумент фильтр должен быть массивом jsonb, содержащим ноль и более следующих ключевых слов: "string" (включить все строковые значения), "numeric" (включить все числовые значения), "boolean" (включить все логические значения), "key" (включить все ключи) или "all" (включить всё вышеперечисленное). В особых случаях фильтр также может быть простым значением JSON, представляющим собой одно из этих ключевых слов. `json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]') → '123':5 'fat':2 'rat':3` `json_to_tsvector('english', '{"cat": "The Fat Rats", "dog": 123}'::json, '"all"') → '123':9 'cat':1 'dog':7 'fat':4 'rat':5`
ts_delete ( вектор tsvector, лексема text ) → tsvector
	Удаляет все вхождения лексемы, из вектора. `ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat') → 'cat':3 'rat':5A`
ts_delete ( вектор tsvector, лексемы text[] ) → tsvector
	Удаляет все вхождения перечисленных лексем из вектора. `ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat']) → 'cat':3`
ts_filter ( вектор tsvector, веса "char"[] ) → tsvector
	Выбирает из вектора только элементы с заданными весами. `ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}') → 'cat':3B 'rat':5A`
ts_headline ( [ конфигурация regconfig, ] документ text, запрос tsquery [, параметры text ] ) → text
	Отображает в сокращенной форме соответствующие запросу вхождения в документе, который должен быть просто текстом, а не значением типа tsvector. Перед сопоставлением с запросом слова в этом документе нормализуются согласно конфигурации по умолчанию или заданной. Использование этой функции рассматривается в подразделе Выделение результатов; также там описываются возможные значения параметров. `cat ate the rat.`
ts_headline ( [ конфигурация regconfig, ] документ json, запрос tsquery [, параметры text ] ) → text ts_headline ( [ конфигурация regconfig, ] документ jsonb, запрос tsquery [, параметры text ] ) → text
	Отображает в сокращенной форме соответствующие запросу вхождения, найденные в строковых значениях внутри документа JSON. Подробную информацию см. в подразделе Выделение результатов. `ts_headline('{"cat":"raining cats and dogs"}'::jsonb, 'cat') → {"cat": "raining cats and dogs"}`
ts_rank ( [ веса real[], ] вектор tsvector, запрос tsquery [, нормализация integer ] ) → real
	Вычисляет количественный показатель, демонстрирующий, в какой степени вектор соответствует запросу. Подробную информацию см. в подразделе Ранжирование результатов поиска. `ts_rank(to_tsvector('raining cats and dogs'), 'cat') → 0.06079271`
ts_rank_cd ( [ веса real[], ] вектор tsvector, запрос tsquery [, нормализация integer ] ) → real
	С помощью алгоритма расчета плотности покрытия вычисляет количественный показатель, демонстрирующий, в какой степени вектор соответствует запросу. Подробную информацию см. в подразделе Ранжирование результатов поиска. `ts_rank_cd(to_tsvector('raining cats and dogs'), 'cat') → 0.1`
ts_rewrite ( запрос tsquery, цель tsquery, подстановка tsquery ) → tsquery
	Заменяет в запросе вхождения цели на подстановку. Подробную информацию см. в подразделе Перезапись запросов. `ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo\|bar'::tsquery) → 'b' & ( 'foo' \| 'bar' )`
ts_rewrite ( запрос tsquery, select text ) → tsquery
	Заменяет базовые элементы запроса, получая выборку целевых вхождений и подстановок с помощью команды `SELECT`. Подробную информацию см. в подразделе Перезапись запросов. `SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases') → 'b' & ( 'foo' \| 'bar' )`
tsquery_phrase ( запрос1 tsquery, запрос2 tsquery ) → tsquery
	Конструирует фразовый запрос, который ищет вхождения, соответствующие запросу1 и запросу2, в идущих подряд лексемах (аналогично оператору `<->`). `tsquery_phrase(to_tsquery('fat'), to_tsquery('cat')) → 'fat' <-> 'cat'`
tsquery_phrase ( запрос1 tsquery, запрос2 tsquery, расстояние integer ) → tsquery
	Конструирует фразовый запрос, который ищет вхождения, соответствующие запросу1 и запросу2, находящиеся точно на заданном расстоянии (в лексемах) друг от друга. `tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10) → 'fat' <10> 'cat'`
tsvector_to_array ( tsvector ) → text[]
	Преобразует значение типа tsvector в массив лексем. `tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector) → {cat,fat,rat}`
unnest ( tsvector ) → setof record ( лексема text, позиции smallint[], веса text )
	Разворачивает значение tsvector в набор строк, по одной на каждую лексему. `select * from unnest('cat:3 fat:2,4 rat:5A'::tsvector) → lexeme \| positions \| weights --------+-----------+--------- cat \| {3} \| {D} fat \| {2,4} \| {D,D} rat \| {5} \| {A}`

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

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

Таблица 43. Функции отладки текстового поиска

Функция
	Описание Пример(ы)
ts_debug ( [ конфигурация regconfig, ] документ text ) → setof record ( псевдонимы text, описание text, синт_единица text, словари regdictionary[], словарь regdictionary, лексемы text[] )
	Извлекает из документа синтаксические единицы, нормализует их согласно заданной или стандартной конфигурации текстового поиска и возвращает информацию о том, как была обработана каждая из них. Подробную информацию см. в подразделе Тестирование конфигурации. `ts_debug('english', 'The Brightest supernovaes') → (asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...`
ts_lexize ( словарь regdictionary, синт_единица text ) → text[]
	Возвращает массив заменяющих лексем, если входная синтаксическая единица есть в словаре, пустой массив, если синтаксическая единица есть в словаре, но является стоп-словом, или NULL, если это неизвестное слово. Подробную информацию см. в подразделе Тестирование словаря. `ts_lexize('english_stem', 'stars') → {star}`
ts_parse ( имя_анализатора text, документ text ) → setof record ( код_единицы integer, синт_единица text )
	Извлекает синтаксические единицы из документа, используя именованный синтаксический анализатор. Подробную информацию см. в подразделе Тестирование анализатора. `ts_parse('default', 'foo - bar') → (1,foo) ...`
ts_parse ( oid_анализатора oid, документ text ) → setof record ( код_единицы integer, синт_единица text )
	Извлекает синтаксические единицы из документа, используя синтаксический анализатор с указанным OID. Подробную информацию см. в подразделе Тестирование анализатора. `ts_parse(3722, 'foo - bar') → (1,foo) ...`
ts_token_type ( имя_анализатора text ) → setof record ( код_единицы integer, псевдоним text, описание text )
	Возвращает таблицу, описывающую все типы синтаксических единиц, которые может распознать именованный синтаксический анализатор. Подробную информацию см. в подразделе Тестирование анализатора. `ts_token_type('default') → (1,asciiword,"Word, all ASCII") ...`
ts_token_type ( oid_анализатора oid ) → setof record ( код_единицы integer, псевдоним text, описание text )
	Возвращает таблицу, описывающую все типы синтаксических единиц, которые может распознать синтаксический анализатор с указанным OID. Подробную информацию см. в подразделе Тестирование анализатора. `ts_token_type(3722) → (1,asciiword,"Word, all ASCII") ...`
ts_stat ( запрос_sql text [, веса text ] ) → setof record ( слово text, число_док integer, число_вхожд integer )
	Выполняет SQL-запрос, который должен возвращать единственный столбец tsvector, и выдает статистику по каждой отдельной лексеме, содержащейся в данных. Подробную информацию см. в подразделе Сбор статистики по документу. `ts_stat('SELECT vector FROM apod') → (foo,10,15) ...`