CONTAINS (Transact-SQL)

Mis à jour : 14 avril 2006

Prédicat utilisé pour effectuer une recherche dans des colonnes contenant des données de type caractère. Il peut s'agir de correspondances exactes ou floues (moins précises) de mots ou d'expressions, de mots à proximité les uns des autres, ou encore de correspondances pondérées.

Dans SQL Server 2005, vous pouvez utiliser des noms en quatre parties dans les prédicats de texte intégral CONTAINS ou FREETEXT pour exécuter des requêtes sur des serveurs liés.

CONTAINS peut rechercher :

• un mot ou une expression ;
• le préfixe d'un mot ou d'une expression ;
• un mot proche d'un autre mot ;
• un mot dérivant d'un autre mot par inflexion (par exemple, le radical « part » a généré par inflexion les formes dérivées partir, départ, partant ou partie) ;
• un mot synonyme d'un autre mot d'après le dictionnaire des synonymes (par exemple, le mot métal peut avoir des synonymes tels que aluminium et acier).

Conventions de la syntaxe de Transact-SQL

Syntaxe

CONTAINS
      ( { column_name | (column_list) | * } 
          , '< contains_search_condition >'     
   [ , LANGUAGE language_term ]
      ) 
< 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 ] 
        ) 
< AND > ::= 
     { AND | & }
< AND NOT > ::= 
     { AND NOT | & !}
< OR > ::= 
     { OR | | }

Arguments

• column_name
  Nom de la colonne ou des colonnes incluses dans l'index de texte intégral. Les colonnes de type char, varchar, nchar, nvarchar, text, ntext, image, xml et varbinary(max) représentent des colonnes valides pour la 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 sélectionnée pour une recherche de texte intégral doivent être utilisées pour la condition spécifiée de recherche contains. Les colonnes de la clause CONTAINS doivent provenir d'une même table. 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 dans laquelle l'utilisateur émet la requête. Si la colonne contient plusieurs documents stockés sous forme d'objets binaires de grande taille (BLOB), la langue utilisée pour indexer le contenu même du document est déterminée par l'identifiant de langue (LCID) du document. Par conséquent, une même colonne peut stocker plusieurs langues. Le paramètre LANGUAGE permet aux utilisateurs de spécifier la langue dans laquelle ils effectuent la recherche, améliorant ainsi la probabilité d'une correspondance correcte.

  Ce paramètre est optionnel et peut être spécifié sous forme de chaîne, de nombre entier ou de valeur hexadécimale correspondant à l'identifiant 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 indiquée, la langue de 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. 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 DBCS (jeu de caractères codés sur deux octets), SQL Server la convertit au format 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 de langage neutre, indiquez 0x0 pour language_term.

• <contains_search_condition>
  Spécifie le texte à rechercher dans column_name et les conditions à satisfaire pour une correspondance.

  L'argument contains_search_condition est de type nvarchar. Une conversion implicite se produit lorsqu'un autre type de données character est utilisé comme entrée. Dans l'exemple suivant, la variable @SearchWord, à laquelle est attribuée la valeur varchar(30), provoque une conversion implicite dans le prédicat CONTAINS.

  USE AdventureWorks;
  GO
  DECLARE @SearchWord varchar(30)
  SET @SearchWord ='performance'
  SELECT Description 
  FROM Production.ProductDescription 
  WHERE CONTAINS(Description, @SearchWord);
  

  Étant donné que la détection des paramètres ne fonctionne pas lors de la conversion, utilisez nvarchar afin d'obtenir de meilleures performances. Dans l'exemple, déclarez @SearchWord en tant que nvarchar(30).

  USE AdventureWorks;
  GO
  DECLARE @SearchWord nvarchar(30)
  SET @SearchWord = N'performance'
  SELECT Description 
  FROM Production.ProductDescription 
  WHERE CONTAINS(Description, @SearchWord);
  

  Vous pouvez également utiliser l'indicateur de requête OPTIMIZE FOR lorsqu'un plan non optimal est généré.

• word
  Chaîne de caractères sans espaces ni ponctuation.

• phrase
  Un ou plusieurs mots séparés par des espaces.

  Remarque :
  Certaines langues, notamment certaines langues asiatiques, peuvent contenir des expressions composées d'un ou de plusieurs mots non séparés par des espaces.

• <simple_term>
  Spécifie une correspondance pour un mot ou une expression exacts. Exemples de termes simples autorisés : « lieu dit », « lieudit » et « Microsoft SQL Server ». Les phrases doivent être incluses entre des guillemets doubles (""). Les mots d'une expression doivent apparaître dans l'ordre spécifié dans <contains_search_condition>, tels qu'ils sont dans la colonne de la base de données. La recherche de caractères dans un mot ou une expression ne distingue pas la casse. Dans des colonnes définies pour une indexation de texte intégral, les mots vides (par exemple, un, et ou le) ne sont pas stockés dans l'index de texte intégral. Si un mot vide est utilisé dans la recherche d'un mot unique, SQL Server retourne un message d'erreur indiquant que la requête contient uniquement des mots vides. SQL Server contient une liste standard des mots vides dans le répertoire \Mssql\Binn\FTERef de chaque instance de SQL Server.

  La ponctuation est ignorée. Par conséquent, CONTAINS(testing, "computer failure") renverra la ligne ayant la valeur « Où est mon ordinateur (computer) ? Il est en panne (Failure). » Pour plus d'informations sur le comportement de la coupure des mots, consultez Séparateurs de mots et identificateurs de racines.

• <prefix_term>
  Précise une correspondance de mots ou d'expressions commençant par le texte spécifié. Placez un terme préfixe entre guillemets doubles ("") et ajoutez un astérisque (*) avant les guillemets doubles fermants afin que tout le texte commençant par le terme simple spécifié avant l'astérisque soit pris en compte. La clause doit être définie de la manière suivante : CONTAINS (column, '"text*"'). L'astérisque correspond à aucun, à un ou à plusieurs caractères (du ou des mots racine dans le mot ou l'expression). Si le texte et l'astérisque ne sont pas délimités par des guillemets doubles, comme dans CONTAINS (column, 'text*'), la recherche de texte intégral considère l'astérisque comme un caractère et recherche les correspondances exactes avec text*. Le moteur de recherche de texte intégral ne trouve aucun mot contenant l'astérisque (*) car la coupure de mots ignore en général ces caractères.

  Lorsque <prefix_term> est une expression, chaque mot qui la compose est considéré comme un préfixe séparé. Ainsi, une recherche spécifiant le préfixe « contrôle des mots* » trouvera les lignes contenant le texte « contrôle des mots clés », « contrôleur des mots », etc.

• <generation_term>
  Précise une correspondance de mots lorsque les termes simples qui s'y trouvent contiennent des variantes du mot initial à rechercher.

• INFLECTIONAL
  Spécifie que la racine dépendante de la langue doit être utilisée sur le terme simple spécifié. Le comportement des racines est défini en fonction des règles de racine de chaque langue spécifique. La langue neutre ne possède pas de racines associées. La langue de la/des colonne(s) interrogée(s) est utilisée pour se reporter aux racines souhaitées. Si language_term est spécifié, les racines correspondant à cette langue sont utilisées.

  Un paramètre <simple_term> donné inclus dans <generation_term> ne peut pas correspondre à la fois aux noms et aux verbes.

• THESAURUS
  Spécifie l'utilisation du dictionnaire des synonymes correspondant à la langue de texte intégral de la colonne ou à la langue spécifiée dans la requête. Les motifs les plus longs de simple_term sont interprétés par rapport au dictionnaire des synonymes et des termes supplémentaires sont créés pour étendre ou pour remplacer le motif d'origine. Si aucune correspondance n'est trouvée pour tout ou partie de simple_term, la partie sans correspondance est traitée en tant que simple_term. Pour plus d'informations sur le dictionnaire des synonymes pour la recherche de texte intégral, consultez Dictionnaire des synonymes.

• <proximity_term>
  Spécifie une correspondance de mots ou d'expressions qui doivent être proches l'un de l'autre. <proximity_term> présente un comportement comparable à l'opérateur AND : les deux requièrent qu'il y ait au moins deux mots ou deux phrases voisins dans la colonne où est effectuée la recherche. Plus les mots de <proximity_term> sont proches, plus la correspondance est précise.

  • NEAR | ~
    Indique que le mot ou l'expression placé à gauche de l'opérateur NEAR ou ~ doit être proche du mot ou de l'expression placé à droite de l'opérateur NEAR ou ~. Plusieurs termes de proximité peuvent être enchaînés. Par exemple :

    a NEAR b NEAR c 
    

    Ceci signifie que le mot ou l'expression a doit être proche du mot ou de l'expression b et que cette dernière doit à son tour être proche du mot ou de l'expression c. Lorsque plusieurs termes de proximité sont enchaînés, ils doivent tous être proches les uns des autres. Par conséquent, dans l'exemple a ~ b ~ c, le mot ou l'expression a doit également être proche du mot ou de l'expression c.

• <weighted_term>
  Précise que les lignes retournées par la requête correspondent à une liste de mots ou d'expressions auxquels une valeur de pondération peut être affectée.

• ISABOUT
  Précise le mot clé <weighted_term>.

  • WEIGHT(weight_value)
    Définit une valeur de pondération qui est un nombre compris entre 0,0 et 1,0. Chaque élément de <weighted_term> peut inclure une valeur weight_value. Le paramètre weight_value permet de modifier l'influence de diverses parties d'une requête sur la valeur de classement affectée à chaque ligne correspondant à la requête. WEIGHT n'a pas d'incidence sur les résultats des requêtes CONTAINS, mais influe sur le classement des requêtes CONTAINSTABLE. Pour plus d'informations, consultez CONTAINSTABLE (Transact-SQL).

    Remarque :
    Le séparateur décimal est toujours un point indépendamment des paramètres régionaux du système d'exploitation.

• { AND | & } | { AND NOT | &! } | { OR | | }
  Spécifie une opération logique entre deux conditions de recherche de contenu.

  • AND | &
    Indique que les deux conditions de recherche contains doivent être satisfaites pour obtenir une correspondance. Le symbole et commercial (&) peut être utilisé à la place du mot clé AND pour représenter l'opérateur AND.
  • AND NOT | &!
    Indique que la deuxième condition de recherche ne doit pas être satisfaite pour obtenir une correspondance. Le symbole et commercial suivi d'un point d'exclamation (&!) peut être utilisé à la place du mot clé AND NOT pour représenter l'opérateur AND NOT.

  • OR | |
    Indique que l'une des deux conditions de recherche contains doit être satisfaite pour obtenir une correspondance. Le symbole de barre verticale (|) peut être utilisé à la place du mot clé OR pour représenter l'opérateur OR.

    Lorsque <contains_search_condition> comporte des groupes placés entre parenthèses, ces groupes sont évalués en premier. Une fois ces groupes évalués, les règles suivantes sont appliquées lorsque ces opérateurs logiques sont utilisés dans les conditions de recherche de contenu :

    • NOT est appliqué avant AND.
    • NOT peut uniquement être utilisé après AND, comme dans AND NOT. L'opérateur OR NOT n'est pas autorisé. NOT ne peut pas être spécifié avant le premier terme. Par exemple, CONTAINS (mycolumn, 'NOT "phrase_to_search_for" ' ) est incorrect.
    • AND est appliqué avant OR.
    • Les opérateurs booléens de même type (AND, OR) sont associatifs et peuvent donc être utilisés dans un ordre quelconque.
    • n
      Espace réservé indiquant que plusieurs conditions de recherche CONTAINS peuvent être spécifiées, de même que plusieurs termes dans celles-ci.

Notes

CONTAINS 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).

Exemples

A. Utilisation de CONTAINS avec <simple_term<

L'exemple ci-dessous recherche tous les produits qui contiennent le mot "Mountain" et qui coûtent $80.99.

USE AdventureWorks;
GO
SELECT Name, ListPrice
FROM Production.Product
WHERE ListPrice = 80.99
   AND CONTAINS(Name, 'Mountain');
GO

B. Utilisation de CONTAINS et d'une expression dans <simple_term>

L'exemple ci-dessous renvoie tous les produits qui contiennent l'expression "Mountain" ou "Road".

USE AdventureWorks;
GO
SELECT Name
FROM Production.Product
WHERE CONTAINS(Name, ' "Mountain" OR "Road" ')
GO

C. Utilisation de CONTAINS avec <prefix_term>

L'exemple ci-dessous renvoie tous les noms de produits comportant au moins un mot commençant par la chaîne de préfixe dans la colonne Name.

USE AdventureWorks;
GO
SELECT Name
FROM Production.Product
WHERE CONTAINS(Name, ' "Chain*" ');
GO

D. Utilisation de CONTAINS et OR avec <prefix_term>

L'exemple ci-dessous renvoie toutes les descriptions de catégorie contenant les chaînes "chain" ou "full".

USE AdventureWorks;
GO
SELECT Name
FROM Production.Product
WHERE CONTAINS(Name, '"chain*" OR "full*"');
GO

E. Utilisation de CONTAINS avec <proximity_term>

L'exemple suivant renvoie tous les noms de produits contenant le mot « bike » à proximité du mot « performance ».

USE AdventureWorks;
GO
SELECT Description
FROM Production.ProductDescription
WHERE CONTAINS(Description, 'bike NEAR performance');
GO

F. Utilisation de CONTAINS avec <generation_term<

L'exemple ci-dessous recherche tous les produits comportant des formes dérivés du mot « ride » : riding, ridden, etc.

USE AdventureWorks;
GO
SELECT Description
FROM Production.ProductDescription
WHERE CONTAINS(Description, ' FORMSOF (INFLECTIONAL, ride) ');
GO

G. Utilisation de CONTAINS avec <weighted_term>

L'exemple ci-dessous recherche tous les noms de produits contenant les mots « performance », « comfortable » ou « smooth ». Un poids différent est affecté à chacun des mots.

USE AdventureWorks;
GO
SELECT Description
FROM Production.ProductDescription
WHERE CONTAINS(Description, 'ISABOUT (performance weight (.8), 
comfortable weight (.4), smooth weight (.2) )' );
GO

H. Utilisation de CONTAINS avec des variables

L'exemple ci-dessous utilise une variable à la place d'un terme de recherche spécifique.

USE AdventureWorks;
GO
DECLARE @SearchWord nvarchar(30)
SET @SearchWord = N'Performance'
SELECT Description 
FROM Production.ProductDescription 
WHERE CONTAINS(Description, @SearchWord);
GO

Voir aussi

Référence

CONTAINSTABLE (Transact-SQL)
FREETEXT (Transact-SQL)
FREETEXTTABLE (Transact-SQL)
WHERE (Transact-SQL)

Autres ressources

Recherche de texte intégral
Requêtes de recherche de texte intégral

Aide et Informations

Assistance sur SQL Server 2005

Historique des modifications