CONTAINSTABLE (Transact-SQL)

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. La funzione CONTAINSTABLE viene utilizzata nella clausola FROM di un'istruzione Transact-SQL SELECT e vi viene fatto riferimento come se fosse un normale nome di tabella. Esegue una ricerca full-text di SQL Server in colonne indicizzate full-text che contengono tipi di dati basati su caratteri.

CONTAINSTABLE è utile per gli stessi tipi di corrispondenze del predicato CONTAINS e utilizza 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.

[!NOTA]

Per informazioni sulle forme di ricerca full-text supportate da SQL Server, vedere Esecuzione della query con ricerca Full-Text.

Convenzioni della 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, due, tre o quattro parti. L'esecuzione della ricerca in una vista può interessare solo una tabella di base con indicizzazione full-text.

  table non può includere un nome di server e non può essere utilizzato per l'esecuzione di query su server collegati.

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

• column_list
  Viene indicato che è possibile specificare più colonne, separate da virgola. column_list deve 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 in table devono essere utilizzate per la ricerca in base alle condizioni di ricerca specificate. 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 verranno utilizzate per il wordbreaking, lo stemming, il thesaurus e la rimozione di parole 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, la probabilità di ottenere una corrispondenza pertinente sarà maggiore.

  Se l'argomento language_term viene specificato come stringa, corrisponde al valore della colonna alias nella vista di compatibilità sys.syslanguages. La stringa deve essere racchiusa tra virgolette singole, come in 'language_term'. Se l'argomento language_term viene specificato come valore intero, corrisponde all'LCID effettivo che identifica la lingua. Se specificato come valore esadecimale, language_term è 0x seguito dal valore esadecimale dell'LCID. Il valore esadecimale non deve superare le otto cifre, inclusi gli zero 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 vi sono risorse installate corrispondenti a tale lingua, SQL Server restituisce un errore. Per utilizzare le risorse della lingua neutra, specificare 0x0 per language_term.

• top_n_by_rank
  Viene specificato che vengono restituite solo n corrispondenze di pertinenza maggiore in ordine decrescente. Viene applicata solo quando viene specificato un valore n intero. Se 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 risultati più significativi.

• <contains_search_condition>
  Specifica il testo da cercare in column_name e le condizioni della ricerca. Per ulteriori 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 include una colonna KEY che contiene valori di chiave full-text. Ogni tabella indicizzata full-text include una colonna contenente valori univoci. I valori restituiti nella colonna KEY sono i valori chiave full-text delle righe che corrispondono ai criteri di ricerca specificati nel predicato CONTAINS. La proprietà TableFulltextKeyColumn, ottenuta con la funzione OBJECTPROPERTY, assegna l'identità a questa colonna chiave univoca. Per ottenere l'ID della colonna associata alla chiave full-text dell'indice full-text, utilizzare sys.fulltext_indexes. Per ulteriori 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 restituita dalla funzione CONTAINSTABLE include una colonna denominata RANK. Ogni riga della colonna RANK include un valore compreso tra 0 e 1.000 che indica il livello di 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

A.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 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.Restituzione di valori di rango superiori a un valore specificato

Nell'esempio seguente viene utilizzato NEAR per cercare "bracket" e "reflector" vicini nella colonna Production.Document del database AdventureWorks2008. Vengono restituite solo le righe con un valore di pertinenza maggiore di 50.

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

[!NOTA]

Se una query full-text non specifica un valore intero come distanza massima, un documento che contiene solo riscontri il cui gap è maggiore di 100 termini logici non soddisferà i requisiti NEAR e il relativo rango sarà pari a 0.

C.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 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

GO

D.Utilizzo dell'argomento LANGUAGE

Nell'esempio seguente viene illustrato l'utilizzo dell'argomento 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

[!NOTA]

L'argomento LANGUAGE language_term non è obbligatorioper l'utilizzo del parametro top_n_by_rank.

Vedere anche

Attivitá

Creazione di query di ricerca full-text (Visual Database Tools)

Riferimento

CONTAINS (Transact-SQL)

SELECT (Transact-SQL)

FROM (Transact-SQL)

Concetti

Limitazione dei risultati della ricerca mediante RANK

Esecuzione della query con ricerca Full-Text

Esecuzione della query con ricerca Full-Text