CONTAINSTABLE (Transact-SQL)

Si applica a: SQL Server database SQL di Azure Istanza gestita di SQL di Azure

Restituisce una tabella contenente una o più righe o nessuna riga per le colonne che includono corrispondenze più o meno esatte di singole parole e frasi, della prossimità delle parole a una certa distanza l'una dall'altra o di corrispondenze ponderate. CONTAINSTABLE viene usato nella clausola FROM di un'istruzione Transact-SQL SELECT e viene fatto riferimento come se fosse un nome di tabella normale. Esegue una ricerca full-text di SQL Server in colonne indicizzate full-text contenenti tipi di dati basati su caratteri.

CONTAINSTABLE è utile per gli stessi tipi di corrispondenze del predicato CONTAINS e usa le stesse condizioni di ricerca di CONTAINS.

Tuttavia, a differenza di CONTAINS, le query che utilizzano la funzione CONTAINSTABLE restituiscono un valore di classificazione della pertinenza (RANK) e una chiave full-text (KEY) per ogni riga. Per informazioni sui formati di ricerca full-text supportati da SQL Server, vedere Eseguire query con ricerca full-text.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

  
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 ]   
    )  
  

Argomenti

table
Nome di una tabella indicizzata full-text. table può essere un nome di oggetto di database in una sola, due, tre o quattro parti. L'esecuzione della ricerca in una vista può interessare solo una tabella di base con indicizzazione full-text.

la tabella non può specificare un nome del server e non può essere utilizzata nelle query sui server collegati.

column_name
Nome di una o più colonne indicizzate per la ricerca full-text. La colonna o le colonne possono essere di tipo char, varchar, nchar, nvarchar, text, ntext, image, xml, varbinary r varbinary(max).

column_list
Viene indicato che è possibile specificare più colonne, separate da virgola. column_listdeve essere racchiuso tra parentesi. La lingua di tutte le colonne di column_list deve essere la stessa, a meno che non sia specificato language_term.

*
Specifica che tutte le colonne indicizzate full-text nella tabella devono essere utilizzate per cercare la condizione di ricerca specificata. La lingua di tutte le colonne della tabella deve essere la stessa, a meno che non sia specificato language_term.

LANGUAGE language_term
Lingua la cui risorsa verrà usata per la rimozione di word breaking, stemming e thesaurus e di parole non significative (o parola non significative) come parte della query. Questo parametro è facoltativo e può essere specificato come valore stringa, intero o esadecimale corrispondente all'identificatore delle impostazioni locali (LCID) di una lingua. Se si specifica language_term, la lingua rappresentata dall'argomento verrà applicata a tutti gli elementi della condizione di ricerca. Se non si specifica alcun valore, verrà utilizzata la lingua full-text della colonna.

Se documenti di lingue diverse vengono archiviati insieme come oggetti BLOB in una singola colonna, l'identificatore delle impostazioni locali (LCID) di un documento specifico determina la lingua da utilizzare per indicizzarne il contenuto. Se quando si esegue una query su una colonna di questo tipo si specifica LANGUAGE**language_term, è possibile aumentare la probabilità di una corrispondenza soddisfacente.

Se specificato come stringa, language_term corrisponde al valore della colonna alias nella vista di compatibilità sys.syslanguages . La stringa deve essere racchiusa tra virgolette singole chiuse, come in 'language_term'. Se l'argomento language_term viene specificato come valore intero, corrisponde all'LCID effettivo che identifica la lingua. Se si specifica un valore esadecimale, language_term è 0x seguito dal valore esadecimale di LCID. Il valore esadecimale non deve superare le otto cifre, inclusi gli zeri iniziali.

Se il valore è in formato DBCS (Double-Byte Character Set), verrà convertito in Unicode da Microsoft SQL Server.

Se la lingua specificata non è valida o non sono presenti risorse installate corrispondenti a tale lingua, SQL Server restituisce un errore. Per usare le risorse della lingua neutra, specificare 0x0 per language_term.

top_n_by_rank
Specifica che vengono restituite solo le n corrispondenze classificate più alte, in ordine decrescente. Si applica solo quando viene specificato un valore intero, n. Se il parametro top_n_by_rank viene combinato con altri parametri, la query potrebbe restituire un numero inferiore di righe rispetto al numero di righe effettivamente corrispondenti a tutti i predicati. top_n_by_rank consente di migliorare le prestazioni delle query richiamando solo i riscontri più rilevanti.

<contains_search_condition>
Specifica il testo da cercare in column_name e le condizioni della ricerca. Per informazioni sulle condizioni di ricerca, vedere CONTAINS (Transact-SQL).

Osservazioni:

I predicati e le funzioni full-text possono essere utilizzati in una singola tabella, specificata in modo implicito nel predicato FROM. Per cercare in più tabelle, utilizzare una tabella unita in join nella clausola FROM, che consente di eseguire una ricerca in un set di risultati prodotto da due o più tabelle.

La tabella restituita ha una colonna denominata KEY che contiene valori di chiave full-text. Ogni tabella indicizzata full-text ha una colonna i cui valori sono sicuramente univoci e i valori restituiti nella colonna KEY sono i valori chiave full-text delle righe che corrispondono ai criteri di selezione specificati nella condizione di ricerca. La proprietà TableFulltextKeyColumn , ottenuta dalla funzione OBJECTPROPERTYEX, fornisce l'identità di questa colonna chiave univoca. Per ottenere l'ID della colonna associata alla chiave full-text dell'indice full-text, utilizzare sys.fulltext_indexes. Per altre informazioni, vedere sys.fulltext_indexes (Transact-SQL).

Per ottenere le righe desiderate dalla tabella originale, specificare un join per le righe CONTAINSTABLE. La forma tipica della clausola FROM per un'istruzione SELECT che utilizza la funzione CONTAINSTABLE è la seguente:

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 tabella prodotta da CONTAINSTABLE include una colonna denominata RANK. La colonna RANK è un valore compreso tra 0 e 1000 per ogni riga che indica la corrispondenza tra una riga e i criteri di selezione. Questo valore di pertinenza viene normalmente utilizzato nell'istruzione SELECT in uno dei modi seguenti:

• Nella clausola ORDER BY per ottenere le righe a cui sono stati assegnati i valori di pertinenza massimi nelle prime posizioni della tabella.

• Nell'elenco di selezione per visualizzare il valore di pertinenza assegnato a ogni riga.

Autorizzazioni

Le autorizzazioni di esecuzione sono disponibili solo per gli utenti che dispongono dei privilegi appropriati per l'istruzione SELECT nella tabella o nelle colonne della tabella a cui viene fatto riferimento.

Esempi

R. Esempio semplice

Nell'esempio seguente viene creata e popolata una tabella semplice di due colonne, che elenca 3 contee e i colori nei relativi flag. Crea e popola un catalogo full-text e un indice nella tabella. Viene quindi illustrata la sintassi CONTAINSTABLE . In questo esempio viene illustrato come il valore di classificazione aumenta quando il valore di ricerca viene soddisfatto più volte. Nell'ultima query, la Tanzania che contiene sia il verde che il nero hanno un rango superiore rispetto all'Italia che contiene solo uno dei colori sottoposti a query.

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 CONTAINSTABLE (Flags, FlagColors, 'Green') ORDER BY RANK DESC;  
SELECT * FROM CONTAINSTABLE (Flags, FlagColors, 'Green or Black') ORDER BY RANK DESC;  

B. Restituzione di valori di rango

Nell'esempio seguente viene eseguita una ricerca dei nomi di prodotto che includono le parole "frame", "wheel" o "tire". Ogni parola viene ponderata in modo diverso. Per ogni riga restituita corrispondente ai criteri di ricerca, viene illustrata la prossimità relativa (valore di rango assegnato) della corrispondenza. Le righe di rango superiore vengono restituite per prime.

USE AdventureWorks2022;  
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  

C. Restituzione di valori di rango superiori a un valore specificato

Nell'esempio seguente viene utilizzato NEAR per cercare "bracket" e "reflector" vicini nella tabella Production.Document. Vengono restituite solo le righe con un valore di rango pari a 50 o superiore.

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

D. Restituzione dei primi 5 valori con pertinenza maggiore utilizzando top_n_by_rank

Nell'esempio seguente viene restituita la descrizione dei primi 5 prodotti la cui colonna Description include la parola "aluminum" accanto alla parola "light" o "lightweight".

USE AdventureWorks2022;  
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  

GO

E. Utilizzo dell'argomento LANGUAGE

Nell'esempio seguente viene illustrato l'utilizzo dell'argomento LANGUAGE.

USE AdventureWorks2022;  
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  

Vedi anche

Limitare i risultati della ricerca mediante RANK
Eseguire query con ricerca full-text
Creare query di ricerca full-text (Visual Database Tools)
CONTAINS (Transact-SQL)
Eseguire query con ricerca full-text
SELECT (Transact-SQL)
FROM (Transact-SQL)