CONTAINSTABLE (Transact-SQL)

Mis à jour : 17 juillet 2006

Renvoie une table composée de zéro, 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 ê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 la syntaxe de 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 de la table marquée pour la recherche de 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.

• column_name
  Nom de la colonne dans laquelle la recherche est effectuée et qui se trouve dans table. Les colonnes de type char, varchar, nchar, nvarchar, text, ntext, image, xml, binary et varbinary sont valides pour une recherche de texte intégral.

• 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 de la table qui ont été sélectionnées pour une recherche de texte intégral doivent être explorées avec les conditions de recherche de contenu spécifiées. Si la clause FROM comporte plusieurs tables, * doit être qualifié par le nom de la table. À 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 comme éléments de la requête CONTAINS, pour la césure de mots, la lemmatisation, les synonymes et la suppression des mots vides. Ce paramètre est facultatif et peut être défini comme une chaîne, un entier ou 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 du texte intégral de la colonne est utilisée.

  Lorsqu'il est spécifié comme chaîne, l'argument language_term correspond à la valeur de la colonne alias dans la table système 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), Microsoft SQL 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 renvoie 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 renvoyées par ordre décroissant. Applicable uniquement lorsque la valeur n spécifiée est un entier. Si un filtrage supplémentaire est effectué, il est possible que le nombre de résultats retournés soit inférieur à n.

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

Notes

La table renvoyée a 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 renvoyé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 renvoyé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 comme 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. Renvoi 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 renvoyée correspondant aux critères de recherche. Les lignes ayant le degré de correspondance le plus élevé sont renvoyées en premier.

Remarque :
Pour exécuter cet exemple, vous allez devoir installer la base de données Northwind. Pour plus d'informations sur l'installation de la base de données Northwind, consultez Téléchargement des exemples de bases de données Northwind et pubs.

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. Renvoi de valeurs de classement supérieures à la valeur spécifiée à l'aide de CONTAINSTABLE

L'exemple suivant renvoie 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 renvoyées.

Remarque :
Pour exécuter cet exemple, vous allez devoir installer la base de données Northwind. Pour plus d'informations sur l'installation de la base de données Northwind, consultez Téléchargement des exemples de bases de données Northwind et pubs.

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. Renvoi des 10 meilleurs résultats à l'aide de CONTAINSTABLE et de top_n_by_rank

L'exemple suivant renvoie 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 ».

Remarque :
Pour exécuter cet exemple, vous allez devoir installer la base de données Northwind. Pour plus d'informations sur l'installation de la base de données Northwind, consultez Téléchargement des exemples de bases de données Northwind et pubs.

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

Référence

CONTAINS (Transact-SQL)
Fonctions Rowset (Transact-SQL)
SELECT (Transact-SQL)
WHERE (Transact-SQL)

Autres ressources

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

Aide et Informations

Assistance sur SQL Server 2005

Historique des modifications