CONTAINSTABLE (Transact-SQL)

發行項
08/21/2023

適用於：SQL Server Azure SQL Database Azure SQL 受控執行個體

針對包含精確或模糊（較不精確）的資料行，傳回零、一或多個資料列的資料表，與單一單字和片語的相符專案、彼此距離內單字的鄰近性，或加權相符專案。 CONTAINSTABLE 用於 Transact-SQL SELECT 語句的 FROM 子句中，而且參考它就像是一般資料表名稱一樣。它會對包含字元型資料類型的全文檢索索引資料行執行 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
這是已編制全文檢索索引的資料表名稱。 table 可以是一、二、三部分或四部分資料庫物件名稱。查詢檢視時，只涉及一個全文檢索索引基表。

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，系統就會將它所代表的語言套用至搜尋條件的所有項。如果未指定任何值，就會使用資料行全文檢索語言。

如果不同語言的文件當做二進位大型物件 (BLOB) 一起儲存在單一資料行中，給定文件的地區設定識別碼 (LCID) 會判斷要建立其內容索引所使用的語言。查詢這類資料行時，指定 LANGUAGE**language_term 可能會增加良好比對的機率。

當指定為字串時， language_term 會對應至 sys.syslanguages 相容性檢視中的別名 資料行值。字串必須以單引號括住，如 'language_term'。當指定為整數時，language_term 是用於識別語言的實際 LCID。當指定為十六進位值時，language_term 是 0x，後面接著 LCID 的十六進位值。十六進位值不能超出 8 位數，開頭的零也包括在內。

如果這個值是雙位元組字集 (DBCS) 格式，Microsoft SQL Server 會將其轉換成 Unicode。

如果指定的語言無效，或尚未安裝對應於這個語言的資源，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 資料行中 傳回的值是符合中所指定選取準則之資料列的全文檢索索引鍵值，其中包含搜尋條件。 從 OBJECTPROPERTYEX 函式取得的 TableFulltextKeyColumn 屬性會提供這個唯一索引鍵資料行的識別。若要取得與全文檢索索引之全文檢索索引鍵相關聯的資料行識別碼，請使用 sys.fulltext_indexes 。如需詳細資訊，請參閱 sys.fulltext_indexes （Transact-SQL）。

若要從原始資料表取得您想要的資料列，請指定與 CONTAINSTABLE 資料列的聯結。使用 CONTAINSTABLE 之 SELECT 語句的 FROM 子句的一般形式為：

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 許可權的使用者使用。

範例

A. 簡單範例

下列範例會建立並填入兩個數據行的簡單資料表，其中列出 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. 傳回大於指定值的排名值


適用於：SQL Server 2012 (11.x) 和更新版本。

下列範例使用 NEAR 來搜尋資料表中 Production.Document 彼此接近的「 bracket 」和「 reflector 」。只會傳回排名值為 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

注意

如果全文檢索查詢未將整數指定為最大距離，則只包含間距大於 100 個邏輯詞彙的檔將無法符合 NEAR 需求，且其排名會是 0。

D. 使用top_n_by_rank傳回前 5 個排名結果

下列範例會傳回前 5 個產品的描述，其中 Description 資料行包含「light」或「light」一詞附近的「鋁」字組。

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

E. 指定 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

注意

使用 top_n_by_rank 不需要 LANGUAGE language_term 引數。

另請參閱

使用 RANK 限制搜尋結果
 使用全文檢索搜尋查詢
 建立全文檢索搜尋查詢 (Visual Database Tools)
CONTAINS (Transact-SQL)
使用全文檢索搜尋查詢
 SELECT (Transact-SQL)
FROM (Transact-SQL)