CONTAINSTABLE (Transact-SQL)

Renvoie une table composée de zéros, d'une ou de plusieurs ligne(s) pour les colonnes contenant des données de type caractère pour des correspondances exactes ou floues (moins précises) de mots simples ou d'expressions, la proximité de mots à une certaine distance les uns des autres ou des correspondances pondérées. La fonction CONTAINSTABLE peut uniquement être référencée dans la clause FROM d'une instruction SELECT comme tout nom de table standard.

Les requêtes utilisant CONTAINSTABLE définissent des requêtes de texte intégral de type « contains » qui renvoient une valeur de classement de pertinence (RANK) et une clé de texte intégral (KEY) pour chaque ligne. La fonction CONTAINSTABLE utilise les mêmes conditions de recherche que le prédicat CONTAINS.

Conventions de syntaxe Transact-SQL

Syntaxe

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 > 
    | < 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 ] ) 
< proximity_term > ::= 
     { < simple_term > | < prefix_term > } 
     { { NEAR | ~ } { < simple_term > | < prefix_term > } } [ ...n ] 
< weighted_term > ::= 
     ISABOUT
        ( { { 
  < simple_term > 
  | < prefix_term > 
  | < generation_term > 
  | < proximity_term > 
  } 
   [ WEIGHT ( weight_value ) ] 
   } [ ,...n ] 
        )

Arguments

• table
  Nom d'une table marquée pour être indexée en texte intégral. L'argument table peut être un nom d'objet de base de données composé d'une, deux, trois ou quatre parties. Lors de l'interrogation d'une vue, une seule table de base indexée en texte intégral peut être impliquée.

  table ne peut spécifier un nom de serveur ni être utilisé dans des requêtes exécutées sur des serveurs liés.

• column_name
  Nom d'une ou de plusieurs colonnes indexées pour la recherche en texte intégral. Les colonnes peuvent être de type char, varchar, nchar, nvarchar, text, ntext, image, xml, varbinary ou varbinary(max).

• column_list
  Indique que plusieurs colonnes, délimitées par des virgules, peuvent être spécifiées. L'argument column_list doit être mis entre parenthèses. À moins que la valeur de language_term soit définie, une seule et même langue doit être utilisée dans toutes les colonnes de column_list.

• *
  Spécifie que toutes les colonnes indexées en texte intégral de table doivent être utilisées pour la recherche de la condition de recherche donnée. À moins que la valeur de language_term soit définie, une seule et même langue doit être utilisée dans toutes les colonnes de la table.

• LANGUAGE language_term
  Langue dont les ressources sont utilisées pour l'analyse lexicale, la recherche de radical, les consultations de dictionnaire des synonymes et la suppression de mots parasites (ou mots vides) dans le cadre de la requête. Ce paramètre est facultatif et peut être spécifié sous la forme d'une chaîne, d'un entier ou d'une valeur hexadécimale correspondant à l'identificateur de paramètres régionaux (LCID) d'une langue. Si l'argument language_term est spécifié, la langue qu'il représente est appliquée à tous les éléments de la condition de recherche. Si aucune valeur n'est définie, la langue de texte intégral de la colonne est utilisée.

  Si des documents de langues différentes sont stockés ensemble en tant qu'objets blob dans une colonne unique, l'identificateur de paramètres régionaux (LCID) d'un document donné détermine la langue utilisée pour l'indexation de son contenu. Lors de l'interrogation d'une telle colonne, la spécification de LANGUAGElanguage_term permet d'augmenter la probabilité d'une correspondance correcte.

  Lorsqu'il est spécifié comme chaîne, l'argument language_term correspond à la valeur de la colonne alias dans la vue de compatibilité sys.syslanguages. La chaîne doit être placée entre guillemets simples, comme dans la chaîne 'language_term'. Lorsqu'il est spécifié comme entier, l'argument language_term est alors le LCID actif identifiant la langue. Quand il est spécifié comme valeur hexadécimale, l'argument language_term est 0x suivi de la valeur hexadécimale du LCID. Cette valeur hexadécimale ainsi définie ne doit pas dépasser huit chiffres, zéros non significatifs compris.

  Si la valeur est au format de jeu de caractères codés sur deux octets (DBCS), MicrosoftSQL Server la convertit en Unicode.

  Si la langue spécifiée n'est pas valide ou s'il n'existe aucune ressource installée correspondant à cette langue, SQL Server retourne une erreur. Pour utiliser des ressources de langage neutre, indiquez 0x0 pour language_term.

• top_n_by_rank
  Spécifie que seules les n correspondances de rang le plus élevé seront retournées par ordre décroissant. Applicable uniquement lorsque la valeur n spécifiée est un entier. Si top_n_by_rank est combiné à d'autres paramètres, la requête peut retourner moins de lignes que le nombre de lignes qui correspondent réellement à tous les prédicats. top_n_by_rank vous permet d'augmenter les performances des requêtes en rappelant uniquement les accès les plus pertinents.

• <contains_search_condition>
  Spécifie le texte à rechercher dans column_name et les conditions à satisfaire pour une correspondance. Pour plus d'informations sur les conditions de recherche, consultez CONTAINS (Transact-SQL).

Notes

Les prédicats et les fonctions de texte intégral s'appliquent à une table unique, ce qui est implicite dans le prédicat FROM. Pour effectuer des recherches sur plusieurs tables, utilisez une table jointe dans votre clause FROM afin de baser votre recherche sur un jeu de résultats qui est le produit de deux tables ou plus.

La table retournée comporte une colonne appelée KEY qui contient des valeurs clés de texte intégral. Chaque table indexée pour une requête de texte intégral comporte une colonne dont les valeurs sont uniques. Les valeurs retournées dans la colonne KEY sont les valeurs clés de texte intégral des lignes qui correspondent aux critères de sélection spécifiés dans la condition de recherche de contenu. La propriété Tablefulltextkeycolumn, obtenue à l'aide de la fonction OBJECTPROPERTYEX, fournit l'identité de cette colonne clé unique. Pour obtenir l'ID de la colonne associée à la clé de texte intégral de l'index de texte intégral, utilisez sys.fulltext_indexes. Pour plus d'informations, consultez sys.fulltext_indexes (Transact-SQL).

Pour obtenir les lignes qui vous intéressent dans la table originale, spécifiez une jointure avec les lignes CONTAINSTABLE. La clause FROM d'une instruction SELECT utilisant la fonction CONTAINSTABLE se présente généralement comme suit :

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]

La table générée par la fonction CONTAINSTABLE comporte une colonne intitulée RANK. Cette colonne RANK contient, pour chaque ligne, une valeur (comprise entre 0 et 1 000) qui indique le degré de correspondance de la ligne avec les critères de sélection. Cette valeur de classement est généralement utilisée de l'une des manières suivantes dans l'instruction SELECT :

• dans la clause ORDER BY, pour que les lignes ayant le degré de correspondance le plus élevé soient retoutnées en premier dans la table ;

• dans la liste de sélection, pour indiquer la valeur de classement affectée à chaque ligne.

CONTAINSTABLE n'est pas reconnu en tant que mot clé si le niveau de compatibilité est inférieur à 70. Pour plus d'informations, consultez sp_dbcmptlevel (Transact-SQL).

Autorisations

Les autorisations d'exécution sont disponibles uniquement pour les utilisateurs bénéficiant des privilèges SELECT appropriés sur la table ou sur les colonnes référencées de la table.

Exemples

A. Retour de valeurs de classement à l'aide de CONTAINSTABLE

L'exemple suivant recherche tous les noms de produits contenant les mots « breads », « fish » ou « beers ». Un poids différent est affecté à chacun des mots. Le degré de correspondance (valeur de classement) est indiqué pour chaque ligne retournée correspondant aux critères de recherche. Les lignes ayant le degré de correspondance le plus élevé sont retournées en premier.

USE Northwind;
GO
SELECT FT_TBL.CategoryName, FT_TBL.Description, KEY_TBL.RANK
    FROM Categories AS FT_TBL 
        INNER JOIN CONTAINSTABLE(Categories, Description, 
        'ISABOUT (breads weight (.8), 
        fish weight (.4), beers weight (.2) )' ) AS KEY_TBL
            ON FT_TBL.CategoryID = KEY_TBL.[KEY]
ORDER BY KEY_TBL.RANK DESC;
GO

B. Retour de valeurs de classement supérieures à la valeur spécifiée à l'aide de CONTAINSTABLE

L'exemple suivant retourne la description et le nom de catégorie de toutes les catégories de produits alimentaires dont la colonne Description contient les mots "sweet and savory" à proximité du mot sauces ou du mot candies. Toutes les lignes possédant le nom de catégorie Seafood sont ignorées. Seules les lignes dont la valeur de classement est supérieure ou égale à 2 sont retournées.

USE Northwind;
GO
SELECT FT_TBL.Description, FT_TBL.CategoryName, KEY_TBL.RANK
FROM Categories AS FT_TBL 
    INNER JOIN CONTAINSTABLE (Categories, Description, 
        '("sweet and savory" NEAR sauces) OR
        ("sweet and savory" NEAR candies)'
        ) AS KEY_TBL
        ON FT_TBL.CategoryID = KEY_TBL.[KEY]
WHERE KEY_TBL.RANK > 2
    AND FT_TBL.CategoryName <> 'Seafood'
ORDER BY KEY_TBL.RANK DESC;
GO

C. Retour des 10 meilleurs résultats à l'aide de CONTAINSTABLE et de top_n_by_rank

L'exemple suivant retourne la description et le nom de catégorie des 10 premières catégories de produits alimentaires dont la colonne Description contient les mots « sweet and savory » à proximité du mot « sauces » ou « candies ».

USE Northwind;
SELECT FT_TBL.Description, FT_TBL.CategoryName , KEY_TBL.RANK
FROM Categories AS FT_TBL 
    INNER JOIN CONTAINSTABLE (Categories, Description, 
        '("sweet and savory" NEAR sauces) OR
        ("sweet and savory" NEAR candies)', 10)
        AS KEY_TBL
        ON FT_TBL.CategoryID = KEY_TBL.[KEY]

GO

D. Utilisation de l'argument LANGUAGE

L'exemple suivant illustre l'utilisation de l'argument LANGUAGE.

USE Northwind;
SELECT FT_TBL.Description , FT_TBL.CategoryName , KEY_TBL.RANK
FROM dbo.Categories AS FT_TBL 
    INNER JOIN CONTAINSTABLE (dbo.Categories, Description, 
        '("sweet and savory" NEAR sauces) OR
        ("sweet and savory" NEAR candies)',LANGUAGE N'English', 10) 
        AS KEY_TBL
        ON FT_TBL.CategoryID = KEY_TBL.[KEY];

[!REMARQUE]

L'argument LANGUAGE language_term n'est pas requis pour utiliser top_n_by_rank..

Voir aussi

Tâches

Procédure : créer un catalogue de texte intégral (SQL Server Management Studio)

Procédure : démarrer l'Assistant Indexation de texte intégral (SQL Server Management Studio)

Procédure : créer des requêtes de recherche en texte intégral (Visual Database Tools)

Référence

CREATE FULLTEXT CATALOG (Transact-SQL)

CREATE FULLTEXT INDEX (Transact-SQL)

CONTAINS (Transact-SQL)

Fonctions Rowset (Transact-SQL)

SELECT (Transact-SQL)

WHERE (Transact-SQL)

Concepts

Mise en route avec la recherche en texte intégral

Vue d'ensemble de l'indexation de texte intégral

Vue d'ensemble des fonctions et prédicats de texte intégral

Principes de base des jointures

Exécution de requêtes SQL Server à l'aide de la recherche en texte intégral