CONTAINSTABLE (Transact-SQL)

Article
08/20/2013

Retourne une table composée de zéros, d'une ou de plusieurs ligne(s) pour les colonnes contenant 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. CONTAINSTABLE est utilisé dans la clause FROM d'une instruction Transact-SQL SELECT et référencé comme tout nom de table standard. Il effectue une recherche en texte intégral SQL Server sur les colonnes indexées de recherche en texte intégral qui contiennent des types de données basés sur des caractères.

CONTAINSTABLE est utile pour les mêmes types de correspondance que le prédicat CONTAINS et utilise les mêmes conditions de recherche que CONTAINS.

Toutefois, contrairement à CONTAINS, les requêtes utilisant CONTAINSTABLE retournent une valeur de classement de pertinence (RANK) et une clé de texte intégral (KEY) pour chaque ligne.

[!REMARQUE]

Pour plus d'informations sur les formes de recherches en texte intégral prises en charge par SQL Server, consultez Exécuter une requête avec une recherche en texte intégral.

Icône Lien de rubrique Conventions de la 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> 
    | <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 ] 
    )

Arguments

table
Nom d'une table qui a été indexée en texte intégral. 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. column_list doit être mise entre parenthèses. Une seule et même langue doit être utilisée dans toutes les colonnes de column_list, sauf si language_term est spécifié.
*
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. Si language_term n'est pas précisé, la langue de toutes les colonnes de la table doit être la même.
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 vous spécifiez language_term, 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 LANGUAGE language_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. La valeur hexadécimale ne doit pas dépasser huit caractères, y compris les zéros non significatifs.

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 si aucune ressource correspondant à cette langue n'est installée, SQL Server retourne une erreur. Pour utiliser des ressources linguistiques neutres, 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 associé à d'autres paramètres, la requête peut renvoyer moins de lignes que le nombre de lignes correspondant effectivement à tous les prédicats. top_n_by_rank vous permet d'augmenter les performances des requêtes en rappelant uniquement les résultats 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 retournées en premier dans la table ;
dans la liste de sélection, pour indiquer la valeur de classement affectée à chaque ligne.

Autorisations

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

Exemples

A.Retour de valeurs de classement

L'exemple suivant recherche tous les noms de produits contenant les mots « frame », « wheel » ou « tire ». Une pondération différente est affectée à chacun des mots. Le degré de correspondance (valeur de classement) est indiqué pour chaque ligne retournée correspondant à ces critères de recherche. Les lignes ayant le degré de correspondance le plus élevé sont retournées en premier.

USE AdventureWorks2012
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

B.Retour de valeurs de classement supérieures à une valeur spécifiée

L'exemple suivant utilise NEAR pour rechercher « bracket » et « reflector » à proximité l'un de l'autre dans la colonne Production.Document de la base de données AdventureWorks2008. Seules les lignes dont la valeur de classement est supérieure ou égale à 50 sont retournées.

USE AdventureWorks2012
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

[!REMARQUE]

Si une requête de texte intégral ne spécifie pas d'entier comme distance maximale, un document qui contient uniquement des correspondances dont l'espacement est supérieur à 100 termes logiques ne satisfera pas les exigences requises par NEAR, et son classement sera de 0.

C.Retour des 5 meilleurs résultats à l'aide de top_n_by_rank

L'exemple suivant retourne la description des 5 premiers produits dont la colonne Description contient les mots « aluminum » à proximité du mot « light » ou « lightweight ».

USE AdventureWorks2012
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

D.Utilisation de l'argument LANGUAGE

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

USE AdventureWorks2012
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

[!REMARQUE]

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

Voir aussi