CONTAINSTABLE (Transact-SQL)

Область применения: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure

Возвращает пустую таблицу или таблицу из одной или нескольких строк. Столбцы этой таблицы содержат символьные данные, точно или нечетко (менее точно) соответствующие отдельным словам и фразам, расстоянию между словами или взвешенным совпадениям. CONTAINSTABLE используется в предложении FROM инструкции Transact-SQL SELECT и ссылается как на обычное имя таблицы. Он выполняет полнотекстовый поиск SQL Server на полнотекстовых индексированных столбцах, содержащих типы данных на основе символов.

CONTAINSTABLE полезна для тех же типов совпадений, что и предикат CONTAINS, и использует те же условия поиска, что и CONTAINS.

В отличие от CONTAINS, запросы с функцией CONTAINSTABLE содержат типизированные полнотекстовые запросы, возвращающие ранжирующие по релевантности значения (RANK) и полнотекстовый ключ (KEY) для каждой строки. Сведения о формах полнотекстового поиска, поддерживаемых SQL Server, см. в статье "Запрос" с полнотекстовой поиском.

Соглашения о синтаксисе Transact-SQL

Синтаксис

  
CONTAINSTABLE   
( table , { column_name | ( column_list ) | * } , ' <contains_search_condition> '   
     [ , LANGUAGE language_term]   
  [ , top_n_by_rank ]   
)   
  
<contains_search_condition> ::=   
    { <simple_term>   
    | <prefix_term>   
    | <generation_term>   
    | <generic_proximity_term>   
    | <custom_proximity_term>   
    |  <weighted_term>   
    }   
    | { ( <contains_search_condition> )   
    { { AND | & } | { AND NOT | &! } | { OR | | } }   
     <contains_search_condition> [ ...n ]   
    }  
  
<simple_term> ::=   
     { word | "phrase" }  
<prefix term> ::=   
     { "word*" | "phrase*" }   
<generation_term> ::=   
     FORMSOF ( { INFLECTIONAL | THESAURUS } , <simple_term> [ ,...n ] )   
  
<generic_proximity_term> ::=   
     { <simple_term> | <prefix_term> } { { { NEAR | ~ }   
     { <simple_term> | <prefix_term> } } [ ...n ] }  
  
<custom_proximity_term> ::=   
  NEAR (   
     {  
        { <simple_term> | <prefix_term> } [ ,...n ]  
     |  
        ( { <simple_term> | <prefix_term> } [ ,...n ] )   
      [, <maximum_distance> [, <match_order> ] ]  
     }  
       )   
  
      <maximum_distance> ::= { integer | MAX }  
      <match_order> ::= { TRUE | FALSE }   
  
<weighted_term> ::=   
     ISABOUT  
    ( { {   
  <simple_term>   
  | <prefix_term>   
  | <generation_term>   
  | <proximity_term>   
  }   
   [ WEIGHT ( weight_value ) ]   
   } [ ,...n ]   
    )  
  

Аргументы

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

таблица не может указывать имя сервера и не может использоваться в запросах к связанным серверам.

column_name
Имя одного или нескольких столбцов с полнотекстовым индексом для поиска. Столбцы должны иметь тип char, varchar, nchar, nvarchar, text, ntext, image, xml, varbinary или varbinary(max).

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

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

LANGUAGE language_term
Язык, ресурсы которого будут использоваться для разбиения слов, стеблирования и тезауруса и шумового слова (или стоп-слов) удаления в рамках запроса. Этот аргумент не является обязательным и может быть строкой, целым числом или шестнадцатеричным значением, соответствующим идентификатору локали (LCID). Если аргумент language_term задан, то соответствующий язык будет применяться ко всем элементам условия поиска. Если значение не указано, то используется язык полнотекстового поиска, заданный для столбца.

Если в одном столбце хранятся документы на различных языках в виде больших двоичных объектов, то идентификатор локали заданного документа определяет, какой язык должен использоваться для индексирования его содержимого. Указание аргумента LANGUAGE**language_term при запросе к такому столбцу может повысить вероятность хорошего соответствия.

При указании в виде строки language_term соответствует значению столбца псевдонима в представлении совместимости sys.syslanguages. Строка должна быть заключена в одиночные кавычки: 'language_term'. Если значением аргумента language_term является целое число, оно представляет собой действительный код языка. Если значение language_term задано в шестнадцатеричной форме, то после символов "0x" должна следовать шестнадцатеричная запись кода языка. Шестнадцатеричное значение не может иметь более восьми знаков, включая начальные нули.

Если значение находится в формате двойного байтового набора символов (DBCS), Microsoft SQL Server преобразует его в Юникод.

Если указанный язык является недопустимым или связанные с ним ресурсы не установлены, SQL Server возвращает сообщение об ошибке. Для использования нейтральных языковых ресурсов следует указать 0x0 в качестве значения аргумента language_term.

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

<contains_search_condition>
Текст, который необходимо найти в столбце column_name, и условия соответствия. Сведения об условиях поиска см. в разделе CONTAINS (Transact-SQL).

Замечания

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

Возвращаемая таблица содержит столбец с именем KEY , содержащий значения полнотекстового ключа. Каждая полнотекстовая индексированная таблица содержит столбец, значения которого гарантированно будут уникальными, а значения, возвращаемые в столбце KEY , являются значениями полнотекстового ключа строк, которые соответствуют критериям выбора, указанным в условии поиска. Свойство TableFulltextKeyColumn , полученное из функции OBJECTPROPERTYEX, предоставляет удостоверение этого уникального ключевого столбца. Чтобы получить идентификатор столбца, связанного с полным текстовым ключом полнотекстового индекса, используйте sys.fulltext_indexes. Дополнительные сведения см. в разделе sys.fulltext_indexes (Transact-SQL).

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

SELECT select_list  
FROM table AS FT_TBL INNER JOIN  
   CONTAINSTABLE(table, column, contains_search_condition) AS KEY_TBL  
   ON FT_TBL.unique_key_column = KEY_TBL.[KEY];  

Таблица, созданная CONTAINSTABLE, содержит столбец с именем RANK. Столбец RANK — это значение (от 0 до 1000) для каждой строки, указывающее, насколько хорошо строка соответствовала критериям выбора. Это значение обычно используется в инструкции SELECT следующим образом.

• В предложении ORDER BY для упорядочивания строк таблицы по рангу.

• В списке выборки для определения ранжирующего значения каждой строки.

Разрешения

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

Примеры

А. Простой пример

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

CREATE TABLE Flags (Country nvarchar(30) NOT NULL, FlagColors varchar(200));  
CREATE UNIQUE CLUSTERED INDEX FlagKey ON Flags(Country);  
INSERT Flags VALUES ('France', 'Blue and White and Red');  
INSERT Flags VALUES ('Italy', 'Green and White and Red');  
INSERT Flags VALUES ('Tanzania', 'Green and Yellow and Black and Yellow and Blue');  
SELECT * FROM Flags;  
GO  
  
CREATE FULLTEXT CATALOG TestFTCat;  
CREATE FULLTEXT INDEX ON Flags(FlagColors) KEY INDEX FlagKey ON TestFTCat;  
GO   
  
SELECT * FROM Flags;  
SELECT * FROM CONTAINSTABLE (Flags, FlagColors, 'Green') ORDER BY RANK DESC;  
SELECT * FROM CONTAINSTABLE (Flags, FlagColors, 'Green or Black') ORDER BY RANK DESC;  

B. Получение значений ранга

В следующем примере выполняется поиск всех названий продуктов, содержащих слова «frame», «wheel» или «tire», при этом для каждого слова задается определенный вес. Для каждой строки набора результатов, удовлетворяющей условию поиска, отображается относительная «близость» к совпадению (ранг). Кроме того, строки с более высоким рангом возвращаются первыми.

USE AdventureWorks2022;  
GO  
  
SELECT FT_TBL.Name, KEY_TBL.RANK  
    FROM Production.Product AS FT_TBL   
        INNER JOIN CONTAINSTABLE(Production.Product, Name,   
        'ISABOUT (frame WEIGHT (.8),   
        wheel WEIGHT (.4), tire WEIGHT (.2) )' ) AS KEY_TBL  
            ON FT_TBL.ProductID = KEY_TBL.[KEY]  
ORDER BY KEY_TBL.RANK DESC;  
GO  

C. Получение значений ранга, превышающих указанное значение

В следующем примере используется оператор NEAR для поиска «bracket» и «reflector», находящихся близко друг от друга в столбце таблицы Production.Document. Возвращаются только ранжирующие строки от 50 и выше.

USE AdventureWorks2022  
GO  
  
SELECT DocumentNode, Title, DocumentSummary  
FROM Production.Document AS DocTable   
INNER JOIN CONTAINSTABLE(Production.Document, Document,  
  'NEAR(bracket, reflector)' ) AS KEY_TBL  
  ON DocTable.DocumentNode = KEY_TBL.[KEY]  
WHERE KEY_TBL.RANK > 50  
ORDER BY KEY_TBL.RANK DESC;  
GO  

D. Получение 5 строк с максимальным рангом с помощью функции top_n_by_rank

В следующем примере возвращается описание первых 5 товаров, где столбец Description содержит слово «aluminum» рядом со словом «light» или «lightweight».

USE AdventureWorks2022;  
GO  
  
SELECT FT_TBL.ProductDescriptionID,  
   FT_TBL.Description,   
   KEY_TBL.RANK  
FROM Production.ProductDescription AS FT_TBL INNER JOIN  
   CONTAINSTABLE (Production.ProductDescription,  
      Description,   
      '(light NEAR aluminum) OR  
      (lightweight NEAR aluminum)',  
      5  
   ) AS KEY_TBL  
   ON FT_TBL.ProductDescriptionID = KEY_TBL.[KEY];  
GO  

GO

Е. Указание аргумента LANGUAGE

Следующий пример демонстрирует использование аргумента LANGUAGE.

USE AdventureWorks2022;  
GO  
  
SELECT FT_TBL.ProductDescriptionID,  
   FT_TBL.Description,   
   KEY_TBL.RANK  
FROM Production.ProductDescription AS FT_TBL INNER JOIN  
   CONTAINSTABLE (Production.ProductDescription,  
      Description,   
      '(light NEAR aluminum) OR  
      (lightweight NEAR aluminum)',  
      LANGUAGE N'English',  
      5  
   ) AS KEY_TBL  
   ON FT_TBL.ProductDescriptionID = KEY_TBL.[KEY];  
GO  

См. также

Ограничение количества результатов поиска с помощью RANK
Запросы с полнотекстовым поиском
Создание запросов полнотекстового поиска (визуальные инструменты для баз данных)
CONTAINS (Transact-SQL)
Запросы с полнотекстовым поиском
SELECT (Transact-SQL)
FROM (Transact-SQL)