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 utilizzato 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 di CONTAINS e usa le stesse condizioni di ricerca di CONTAINS.

A differenza di CONTAINS, tuttavia, le query che usano 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

tabella

Nome di una tabella indicizzata full-text. table può essere un nome di oggetto di database in una sola, due, tre o quattro parti. Quando si esegue una query su una vista, è possibile coinvolgere una sola tabella di base indicizzata full-text.

la tabella non può specificare un nome del server e non può essere usata 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 le cui risorse vengono usate per la rimozione di word breaking, stemming e thesaurus e rimozione 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 , il linguaggio rappresentato viene applicato 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. Quando si esegue una query su una colonna di questo tipo, specificare LANGUAGE <language_term> per aumentare la probabilità di una corrispondenza valida.

Se specificato come stringa, language_term corrisponde al valore della alias colonna 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), SQL Server lo converte in Unicode.

Se la lingua specificata non è valida o non sono installate risorse che corrispondono 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.

Osservazioni:

Predicati e funzioni full-text funzionano su una singola tabella, implicita nel FROM predicato. Per eseguire una ricerca in più tabelle, usare una tabella unita in join nella FROM clausola per cercare un set di risultati che rappresenta il prodotto di due o più tabelle.

La tabella restituita contiene 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 KEY colonna sono i valori chiave full-text delle righe che corrispondono ai criteri di selezione specificati nella condizione di ricerca. La TableFulltextKeyColumn proprietà, ottenuta dalla OBJECTPROPERTYEX funzione , fornisce l'identità di questa colonna chiave univoca. Per ottenere l'ID della colonna associata alla chiave full-text dell'indice full-text, usare sys.fulltext_indexes Per altre informazioni, vedere sys.fulltext_indexes.

Per ottenere le righe desiderate dalla tabella originale, specificare un join con le CONTAINSTABLE righe. La forma tipica della FROM clausola per un'istruzione SELECT using CONTAINSTABLE è:

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 RANK colonna è 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 classificazione viene in genere usato in uno dei modi seguenti nell'istruzione SELECT :

ORDER BY Nella clausola per restituire le righe di rango più alto come prime righe della tabella.
Nell'elenco di selezione per visualizzare il valore di pertinenza assegnato a ogni riga.

Autorizzazioni

Le autorizzazioni di esecuzione sono disponibili solo dagli utenti con i privilegi appropriati SELECT per la tabella o le colonne della tabella a cui si fa riferimento.

Esempi

R. Esempio di base

Nell'esempio seguente viene creata e popolata una tabella semplice di due colonne, che elenca tre paesi/aree geografiche e i colori nelle bandiere. Crea e popola un catalogo full-text e un indice nella tabella. Viene quindi illustrata la CONTAINSTABLE sintassi. 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, ha un rango superiore rispetto all'Italia che contiene solo uno dei colori sottoposti a query.

CREATE TABLE Flags
(
    CountryOrRegion NVARCHAR (30) NOT NULL,
    FlagColors VARCHAR (200)
);

CREATE UNIQUE CLUSTERED INDEX FlagKey ON Flags(CountryOrRegion);

INSERT INTO Flags VALUES ('France', 'Blue and White and Red');
INSERT INTO Flags VALUES ('Italy', 'Green and White and Red');
INSERT INTO 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. Restituire i valori di rango

Nell'esempio seguente vengono cercati tutti i nomi di prodotto contenenti le parole frame, wheel, o tiree pesi diversi vengono assegnati a ogni parola. 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. Restituisce valori di rango maggiori di un valore specificato

Si applica a: SQL Server 2012 (11.x) e versioni successive.

Nell'esempio seguente viene utilizzato NEAR per cercare bracket e reflector chiudersi tra loro nella Production.Document tabella. 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

Nota

Se una query full-text non specifica un numero intero come distanza massima, un documento che contiene solo riscontri il cui gap è maggiore di 100 termini logici non soddisfa i NEAR requisiti e la relativa classificazione è 0.

D. Restituire i primi cinque risultati classificati usando top_n_by_rank

Nell'esempio seguente viene restituita la descrizione dei primi cinque prodotti in cui la Description colonna contiene la parola accanto alla parola aluminum o alla parola lightlightweight.

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

E. Specificare l'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