FREETEXTTABLE (Transact-SQL)

Article
05/23/2023

S’applique à :SQL Server Azure SQL Database Azure SQL Managed Instance

Fonction utilisée dans la clause FROM d’une instruction Transact-SQL SELECT pour effectuer une recherche en texte intégral SQL Server sur des colonnes indexées de texte intégral contenant des types de données basés sur des caractères. Cette fonction retourne une table de zéro, d’une ou de plusieurs lignes pour les colonnes contenant des valeurs qui correspondent à la signification et pas seulement au libellé exact du texte du freetext_string spécifié. FREETEXTTABLE est référencé comme s'il s'agissait d'un nom de table classique.

FREETEXTTABLE est utile pour les mêmes types de correspondances que FREETEXT (Transact-SQL),

Les requêtes utilisant FREETEXTTABLE retournent une valeur de classement de pertinence (RANK) et une clé de texte intégral (KEY) pour chaque ligne.

Notes

Pour plus d’informations sur les sortes 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.

Conventions de la syntaxe Transact-SQL

Syntaxe

FREETEXTTABLE (table , { column_name | (column_list) | * }   
          , 'freetext_string'   
     [ , LANGUAGE language_term ]   
     [ , top_n_by_rank ] )

Arguments

table
Nom de la table marquée pour les requêtes de texte intégral. la table ou la vuepeut être un nom d’objet de base de données en un, deux ou trois parties. Lors de l'interrogation d'une vue, une seule table de base indexée en texte intégral peut être impliquée.

la table ne peut pas spécifier un nom de serveur et ne peut pas être utilisée dans les requêtes sur des serveurs liés.

column_name
Nom d'une ou de plusieurs colonnes de texte intégral indexées de la table spécifiée dans la clause FROM. 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 mis 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 la chaîne freetext_string à trouver doit être recherchée dans toutes les colonnes répertoriées pour la recherche en texte intégral. Sauf si language_term est spécifié, la langue de toutes les colonnes indexées de texte intégral dans la table doit être la même.

freetext_string
Texte à rechercher dans column_name. Tout texte, y compris des mots, expressions et phrases peuvent être entrés. Des correspondances sont générées si l'un des termes ou les formes de quelque terme que ce soit sont trouvés dans l'index de texte intégral.

Contrairement à la condition de recherche CONTAINS où AND est un mot clé, lorsqu’il est utilisé dans freetext_string le mot « et » est considéré comme un mot sonore, ou mot vide, et sera ignoré.

L'utilisation de WEIGHT, de FORMSOF, de caractères génériques, de NEAR et d'autres syntaxes n'est pas autorisée. La chaîne freetext_string est découpée en mots en vue de la recherche des radicaux et de l’analyse dans le dictionnaire des synonymes.

LANGUAGE language_term
Langue dont les ressources seront utilisées pour l'analyse lexicale, la recherche de radical, l'utilisation du dictionnaire de synonymes et la suppression de mots vides dans 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 une langue est définie avec language_term, elle 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.

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 language language_term peut augmenter la probabilité d’une bonne correspondance.

Quand il est spécifié en tant que chaîne, language_term correspond à la valeur de colonne alias dans l’affichage de compatibilité sys.syslanguages (Transact-SQL). La chaîne doit être placée entre guillemets simples, comme dans 'language_term'. Quand il est spécifié sous la forme d’un entier, language_term est le LCID qui identifie la langue. Quand il est spécifié sous la forme d’une valeur hexadécimale, 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), Microsoft SQL Server la convertit en Unicode.

Si le langage spécifié n’est pas valide ou si aucune ressource correspondant à ce langage 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 ncorrespondances les plus classées, dans l’ordre décroissant, sont retournées. S’applique uniquement lorsqu’une valeur entière, n, est spécifiée. Si top_n_by_rank est associé à d’autres paramètres, la requête peut retourner 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.

Remarques

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.

FREETEXTTABLE utilise les mêmes conditions de recherche que le prédicat FREETEXT.

Comme CONTAINSTABLE, la table retournée comporte des colonnes nommées KEY et RANK, qui sont référencées dans la requête pour obtenir les lignes appropriées et utiliser les valeurs de classement des lignes.

Autorisations

FREETEXTTABLE ne peut être appelée que par les utilisateurs disposant des privilèges SELECT appropriés sur la table spécifiée ou les colonnes référencées de la table.

Exemples

R. Exemple simple

L’exemple suivant crée et remplit une table simple de deux colonnes, répertoriant 3 comtés et les couleurs dans leurs indicateurs. Il crée et remplit un catalogue de texte intégral et un index sur la table. Ensuite, la syntaxe FREETEXTTABLE est illustrée.

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 FREETEXTTABLE (Flags, FlagColors, 'Blue');  
SELECT * FROM FREETEXTTABLE (Flags, FlagColors, 'Yellow');

B. Utilisation de FREETEXT dans un INNER JOIN

L’exemple suivant retourne la description et le classement de tous les produits avec une description qui correspond à la signification de high level of performance.

USE AdventureWorks2022;  
GO  
  
SELECT FT_TBL.Description  
    ,KEY_TBL.RANK  
FROM Production.ProductDescription AS FT_TBL   
    INNER JOIN FREETEXTTABLE(Production.ProductDescription,  
    Description,   
    'high level of performance') AS KEY_TBL  
ON FT_TBL.ProductDescriptionID = KEY_TBL.[KEY]  
ORDER BY RANK DESC;  
GO

C. Spécification de la langue et des correspondances de classement supérieur

L’exemple suivant est identique et montre l’utilisation des LANGUAGE paramètres language_term et top_n_by_rank.

USE AdventureWorks2022;  
GO  
  
SELECT FT_TBL.Description  
    ,KEY_TBL.RANK  
FROM Production.ProductDescription AS FT_TBL   
    INNER JOIN FREETEXTTABLE(Production.ProductDescription,  
    Description,   
    'high level of performance',  
    LANGUAGE N'English', 2) AS KEY_TBL  
ON FT_TBL.ProductDescriptionID = KEY_TBL.[KEY]  
ORDER BY RANK DESC;  
GO