CONTAINSTABLE (Transact-SQL)

Artikel
05/23/2023

Gilt für:SQL Server Azure SQL-Datenbank Azure SQL Managed Instance

Gibt eine Tabelle mit null, einer oder mehreren Zeilen für spalten zurück, die präzise oder fuzzy (weniger präzise) Übereinstimmungen mit einzelnen Wörtern und Ausdrücken, die Nähe von Wörtern innerhalb eines bestimmten Abstands voneinander oder gewichtete Übereinstimmungen enthalten. CONTAINSTABLE wird in der FROM-Klausel einer Transact-SQL SELECT-Anweisung verwendet und wird so referenziert, als wäre es ein regulärer Tabellenname. Es führt eine SQL Server Volltextsuche für volltextindizierte Spalten aus, die zeichenbasierte Datentypen enthalten.

CONTAINSTABLE ist für die gleichen Übereinstimmungen wie das CONTAINS-Prädikat nützlich und verwendet die gleichen Suchbedingungen wie CONTAINS.

Im Gegensatz zu CONTAINS werden bei Abfragen mit CONTAINSTABLE ein Relevanzrangfolgenwert (Relevance Ranking Value, RANK) und ein Volltextschlüssel (KEY) für jede Zeile zurückgeben. Informationen zu den Formen der Volltextsuche, die von SQL Server unterstützt werden, finden Sie unter Abfragen mit Volltextsuche.

Transact-SQL-Syntaxkonventionen

Syntax

  
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 ]   
    )

Argumente

Tabelle
Der Name einer Tabelle, die volltextindiziert wurde. table kann ein 1-, zwei-, drei- oder vierteiliger Datenbankobjektname sein. Bei der Abfrage einer Sicht kann nur eine volltextindizierte Basistabelle verwendet werden.

table kann keinen Servernamen angeben und kann nicht in Abfragen für Verbindungsserver verwendet werden.

column_name
Der Name einer oder mehreren Spalten, die für die Volltextsuche indiziert werden. Die Spalten können vom Typ char, varchar, nchar, nvarchar, text, ntext, image, xml, varbinary oder varbinary(max) sein.

column_list
Gibt an, dass verschiedene, durch Trennzeichen getrennte Spalten angegeben werden können. column_list muss in Klammern stehen. Sofern nicht language_term angegeben ist, muss die Sprache aller Spalten von column_list identisch sein.

*
Gibt an, dass alle volltextindizierten Spalten in der Tabelle verwendet werden sollen, um nach der angegebenen Suchbedingung zu suchen. Sofern language_term nicht angegeben ist, muss die Sprache aller Spalten in der Tabelle identisch sein.

LANGUAGE language_term
Die Sprache, deren Ressourcen für das Entfernen von Wörtern im Rahmen der Abfrage verwendet werden. Dieser Parameter ist optional und kann als Zeichenfolge, ganze Zahl oder Hexadezimalwert entsprechend dem Gebietsschemabezeichner (Locale Identifier – LCID) einer Sprache angegeben werden. Wird language_term angegeben, wird die entsprechende Sprache auf alle Elemente der Suchbedingung angewendet. Wird kein Wert angegeben, wird die Volltextsprache der Spalte verwendet.

Wenn Dokumente anderer Sprachen zusammen als BLOBs (Binary Large Objects) in einer einzelnen Spalte gespeichert werden, legt der Gebietsschemabezeichner (LCID) eines bestimmten Dokuments die zur Indizierung seines Inhalts zu verwendende Sprache fest. Beim Abfragen einer solchen Spalte kann die Angabe von LANGUAGE**language_term die Wahrscheinlichkeit einer hohen Übereinstimmung steigern.

Bei Angabe als Zeichenfolge entspricht language_term dem Aliasspaltenwert in der Sys.syslanguages-Kompatibilitätssicht . Die Zeichenfolge muss in einfache Anführungszeichen gesetzt werden, z.B. 'language_term'. In Form einer ganzen Zahl ist language_term der eigentliche Gebietsschemabezeichner, der die Sprache identifiziert. In Form eines Hexadezimalwerts ist language_term gleich 0x, gefolgt vom Hexadezimalwert des Gebietsschemabezeichners. Der Hexadezimalwert darf acht Ziffern nicht überschreiten, einschließlich führender Nullen.

Wird der Wert im Format Doppelbyte-Zeichensatz (Double-Byte Character Set, DBCS) angegeben, wird er von Microsoft SQL Server in Unicode konvertiert.

Wenn die angegebene Sprache nicht gültig ist oder keine Ressourcen installiert sind, die dieser Sprache entsprechen, gibt SQL Server einen Fehler zurück. Geben Sie 0x0 als language_term an, um neutrale Sprachressourcen zu verwenden.

Top_n_by_rank
Gibt an, dass nur die Übereinstimmungen mit dem höchsten Rang in absteigender Reihenfolge zurückgegeben werden. Gilt nur, wenn ein ganzzahliger Wert ( n) angegeben wird. Wenn top_n_by_rank mit anderen Parametern kombiniert wird, werden von der Abfrage möglicherweise weniger Zeilen zurückgegeben als die Anzahl von Zeilen, die mit allen Prädikaten übereinstimmen. top_n_by_rank können Sie die Abfrageleistung erhöhen, indem Sie nur die relevantesten Treffer abrufen.

<contains_search_condition>
Gibt den Suchtext in column_name und die Bedingungen für eine Übereinstimmung an. Informationen zu Suchbedingungen finden Sie unter CONTAINS (Transact-SQL).

Bemerkungen

Volltextprädikate und -funktionen gelten für eine einzelne Tabelle, die im FROM-Prädikat enthalten ist. Um eine Suche in mehreren Tabellen auszuführen, können Sie eine verknüpfte Tabelle in der FROM-Klausel verwenden, um in einem Resultset zu suchen, das aus mindestens zwei Tabellen erstellt wird.

Die zurückgegebene Tabelle enthält eine Spalte mit dem Namen KEY , die Volltextschlüsselwerte enthält. Jede volltextindizierte Tabelle verfügt über eine Spalte, deren Werte garantiert eindeutig sind, und die in der KEY-Spalte zurückgegebenen Werte sind die Volltextschlüsselwerte der Zeilen, die den in der -Suchbedingung angegebenen Auswahlkriterien entsprechen. Die TableFulltextKeyColumn-Eigenschaft , die von der OBJECTPROPERTYEX-Funktion abgerufen wird, stellt die Identität dieser eindeutigen Schlüsselspalte bereit. Verwenden Sie sys.fulltext_indexes, um die ID der Spalte abzurufen, die dem Volltextschlüssel des Volltextindexes zugeordnet ist. Weitere Informationen finden Sie unter sys.fulltext_indexes (Transact-SQL).

Geben Sie einen Join mit den CONTAINSTABLE-Zeilen an, um die gewünschten Zeilen der Originaltabelle zu erhalten. CONTAINSTABLE wird meist in folgender Form in der FROM-Klausel einer SELECT-Anweisung verwendet:

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];

Die von CONTAINSTABLE erstellte Tabelle enthält eine Spalte mit dem Namen RANK. Die RANK-Spalte ist ein Wert (von 0 bis 1000) für jede Zeile, der angibt, wie gut eine Zeile mit den Auswahlkriterien übereinstimmt. Dieser Rangwert wird in der SELECT-Anweisung üblicherweise auf folgende Weise verwendet:

In der ORDER BY-Klausel, um die Zeilen, die in der Rangfolge oben liegen, als erste Zeilen der Tabelle zurückzugeben.
In der Auswahlliste, um den zugeordneten Rangfolgenwert jeder Zeile anzuzeigen.

Berechtigungen

Ausführungsberechtigungen sind nur für Benutzer mit den entsprechenden SELECT-Privilegien für die Tabelle oder die referenzierten Tabellenspalten verfügbar.

Beispiele

A. Einfaches Beispiel

Im folgenden Beispiel wird eine einfache Tabelle mit zwei Spalten erstellt und aufgefüllt, wobei 3 Landkreise und die Farben in ihren Flags aufgelistet sind. Der Erstellt und füllt einen Volltextkatalog und index für die Tabelle auf. Anschließend wird die CONTAINSTABLE-Syntax veranschaulicht. In diesem Beispiel wird veranschaulicht, wie der Rangwert höher wächst, wenn der Suchwert mehrmals erreicht wird. In der letzten Abfrage hat Tansania, das sowohl Grün als auch Schwarz enthält, einen höheren Rang als Italien, das nur eine der abgefragten Farben enthält.

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. Zurückgeben von Rangwerten

Im folgenden Beispiel wird nach allen Produktnamen gesucht, die die Wörter "frame", "whell" oder "tire" enthalten, wobei jedes Wort anders gewichtet wird. Für jede zurückgegebene Zeile, die diesen Suchkriterien entspricht, wird die relative Nähe (Rangfolgewert) der Übereinstimmung angezeigt. Darüber hinaus werden die Zeilen, die die höchste Einstufung erhielten, als Erstes zurückgegeben.

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. Zurückgeben von Rangwerten, die größer sind als ein angegebener Wert


Gilt für: SQL Server 2012 (11.x) und höher.

Im folgenden Beispiel wird in der bracket-Tabelle mit NEAR nach "reflector" in der Nähe von "Production.Document" gesucht. Nur Zeilen mit einem Rangwert von 50 oder höher werden zurückgegeben.

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

Hinweis

Wenn eine Volltextabfrage keine ganze Zahl als maximalen Abstand angibt, entspricht ein Dokument, das nur Treffer enthält, deren Abstand größer als 100 logische Begriffe ist, die NEAR-Anforderungen nicht, und der Rang ist 0.

D: Zurückgeben der obersten 5 Ergebnisse mithilfe von top_n_by_rank

Im folgenden Beispiel wird die Beschreibung der ersten 5 Produkte zurückgegeben, bei denen die Description-Spalte das Wort "aluminium" in der Nähe des Worts "light" oder "lightweight" enthält.

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. Angeben des LANGUAGE-Arguments

Im folgenden Beispiel wird die Verwendung des LANGUAGE-Arguments dargestellt.

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