CONTAINS (Transact-SQL)

  • Articolo

Data aggiornamento: 14 aprile 2006

Predicato utilizzato per cercare in colonne contenenti dati di tipo carattere corrispondenze esatte e fuzzy con singole parole e frasi, parole vicine separate da una distanza massima specifica oppure corrispondenze ponderate.

In SQL Server 2005 è possibile utilizzare nomi composti da quattro parti nei predicati full-text CONTAINS o FREETEXT per eseguire query su server collegati.

Il predicato CONTAINS consente di cercare:

  • Una parola o una frase.
  • Il prefisso di una parola o di una frase.
  • Una parola accanto a una parola specifica.
  • Una parola generata da un'altra per flessione, ad esempio le parole guida, guidare, guidando e guidare derivanti dalla radice guida.
  • Un sinonimo di una parola specifica utilizzando il thesaurus (ad esempio, alluminio e acciaio possono essere sinonimi della parola metallo).

Icona di collegamento a un argomentoConvenzioni della sintassi Transact-SQL

Sintassi

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 | | }

Argomenti

  • column_name
    Nome della colonna o delle colonne incluse nell'indice full-text. Le colonne valide per la ricerca full-text sono le colonne di tipo char, varchar, nchar, nvarchar, text, ntext, image, xml e varbinary(max).
  • column_list
    Indica che è possibile specificare più colonne, separate da virgola. column_list deve essere racchiuso tra parentesi. Se non si specifica language_term, la lingua di tutte le colonne in column_list deve essere la stessa.
  • *
    Specifica che tutte le colonne della tabella registrate per la ricerca full-text devono essere utilizzate per la ricerca in base alla condizione di ricerca specificata in CONTAINS. Le colonne della clausola CONTAINS devono appartenere a una sola tabella. Se nella clausola FROM sono specificate più tabelle, è necessario qualificare il simbolo * con il nome della tabella. Se non si specifica language_term, la lingua di tutte le colonne della tabella deve essere la stessa.

  • LANGUAGE language_term
    Lingua in cui l'utente crea la query. Se la colonna contiene diversi documenti archiviati come oggetti BLOB (Binary Large Object), la lingua utilizzata per indicizzare il contenuto effettivo di un documento è determinata dall'identificatore delle impostazioni internazioni (LCID) del documento. Ne consegue che in una stessa colonna possono essere presenti più lingue. Il parametro LANGUAGE consente agli utenti di specificare la lingua in cui eseguire la ricerca, aumentando le probabilità che la ricerca abbia un buon esito.

    Questo parametro è facoltativo ed è possibile specificare un valore stringa, un valore integer o un valore esadecimale corrispondente all'identificatore delle impostazioni internazionali (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 per la ricerca full-text della colonna.

    Se l'argomento language_term viene specificato come stringa, corrisponde al valore della colonna alias nella tabella di sistema syslanguages. La stringa deve essere racchiusa tra virgolette singole, come in 'language_term'. Se l'argomento language_term viene specificato come valore integer, 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 zero iniziali.

    Se il valore è in formato DBCS (Double-Byte Character Set), verrà convertito in Unicode da 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.

  • <contains_search_condition>
    Specifica il testo da cercare nella colonna specificata da column_name e le condizioni della ricerca.

    contains_search_condition è di tipo nvarchar. Si verifica una conversione implicita quando un diverso tipo di dati character viene utilizzato come input. Nell'esempio seguente la variabile @SearchWord, definita come varchar(30), causa una conversione implicita nel predicato CONTAINS.

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

    Poiché non è possibile utilizzare lo sniffing dei parametri nella conversione, utilizzare nvarchar per migliorare le prestazioni. Nell'esempio dichiarare @SearchWord come nvarchar(30).

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

    È inoltre possibile utilizzare l'hint per la query OPTIMIZE FOR nei casi in cui venga generato un piano non ottimale.

  • word
    Stringa di caratteri senza spazi o punteggiatura.

  • phrase
    Una o più parole separate da uno spazio.

    [!NOTA] In alcune lingue, ad esempio nelle lingue asiatiche, è possibile avere frasi composte da una o più parole non separate da alcuno spazio.

  • <simple_term>
    Specifica che deve essere trovata l'esatta corrispondenza di una parola o frase. Esempi di termini semplici validi sono "copri capo", copricapo e "Microsoft SQL Server". Le frasi devono essere racchiuse tra virgolette doppie (""). Le parole di una frase devono essere specificate in <contains_search_condition> nello stesso ordine in cui compaiono nella colonna del database. La distinzione tra maiuscole e minuscole non è rilevante per la ricerca di caratteri nella parola o frase. Le parole non significative, quali preposizioni, congiunzioni e articoli, delle colonne con indicizzazione full-text non vengono archiviate nell'indice full-text. Se una parola non significativa viene utilizzata nella ricerca di una sola parola, SQL Server restituisce un messaggio di errore che informa che la query contiene solo parole non significative. In SQL Server è incluso un elenco standard delle parole non significative, disponibile nella directory \Mssql\Binn\FTERef di ogni istanza di SQL Server.

    La punteggiatura viene ignorata. CONTAINS(testing, "computer failure"), quindi, consente di trovare una riga contenente il valore "Where is my computer? Failure to find it would be expensive". Per ulteriori informazioni sul funzionamento dei word breaker, vedere Word breaker e stemmer.

  • <prefix_term>
    Specifica che devono essere trovate le parole o frasi che iniziano con il testo specificato. Racchiudere il prefisso tra virgolette doppie ("") e aggiungere un asterisco (*) prima delle virgolette di chiusura. In tal modo viene eseguita la ricerca di tutte le parole o frasi che iniziano con il termine semplice che precede l'asterisco. La clausola deve essere specificata nel modo seguente: CONTAINS (column, '"text*"') L'asterisco corrisponde a zero, uno o più caratteri della parola o parole radice della parola o frase. Se il testo e l'asterisco non sono racchiusi tra virgolette doppie, come ad esempio in CONTAINS (column, 'text*'), nella ricerca full-text l'asterisco viene interpretato come carattere e viene eseguita la ricerca esatta di text*. Non verranno trovate le parole con il carattere asterisco (*), perché di norma i word breaker ignorano tali caratteri.

    Se <prefix_term> è una frase, ogni parola della frase viene considerata un prefisso distinto. Pertanto, una query che specifica il prefisso "local wine*" consente di individuare tutte le righe che includono il testo "local winery", "locally wined and dined", e così via.

  • <generation_term>
    Specifica che devono essere trovate le parole i cui termini semplici includono varianti della parola originale da cercare.

  • INFLECTIONAL
    Specifica che deve essere utilizzato lo stemmer specifico della lingua per il termine semplice specificato. Il comportamento dello stemmer dipende dalle regole di analisi morfologica della lingua specifica. Alla lingua neutra non è associato alcuno stemmer. Per individuare lo stemmer viene utilizzata la lingua delle colonne in cui viene eseguita la ricerca. Se si specifica language_term, viene utilizzato lo stemmer corrispondente a tale lingua.

    Un valore <simple_term> incluso in un valore <generation_term> non potrà restituire sia sostantivi che verbi.

  • THESAURUS
    Specifica che verrà utilizzato il thesaurus corrispondente alla lingua specificata per le colonne con indicizzazione full-text oppure alla lingua specificata nella query. Il derivato o i derivati più lunghi di simple_term vengono confrontati con il thesaurus e vengono generati termini aggiuntivi per espandere o sostituire il modello originale. Se non viene trovata alcuna corrispondenza per il valore simple_term o parte di esso, la parte per cui non è stata trovata alcuna corrispondenza viene trattata come simple_term. Per ulteriori informazioni sul thesaurus e la ricerca full-text, vedere Thesaurus.

  • <proximity_term>
    Specifica che devono essere trovate parole o frasi vicine tra loro. <proximity_term> funziona in modo analogo all'operatore AND: per entrambi è necessario che nella colonna in cui verrà eseguita la ricerca esistano più di una parola o frase. Maggiore è la prossimità delle parole specificate in <proximity_term>, migliore sarà l'esito della ricerca.

    • NEAR | ~
      Indica che la parola o frase a sinistra dell'operatore NEAR o ~ deve essere vicina alla parola o frase a destra dell'operatore NEAR o ~. È possibile concatenare più termini, ad esempio:

      a NEAR b NEAR c

      La parola o frase a deve essere vicina alla parola o frase b, che a sua volta deve essere vicina alla parola o frase c. Se vengono concatenati più termini, tutti devono essere vicini l'uno all'altro. Pertanto, nell'esempio a ~ b ~ c, la parola o frase a deve essere vicina anche alla parola o frase c.

  • <weighted_term>
    Specifica che le righe restituite dalla query corrispondono a un elenco di parole e di frasi, a ognuna delle quali può essere associato un valore di ponderazione facoltativo.

  • ISABOUT
    Specifica la parola chiave <weighted_term>.

    • WEIGHT(weight_value)
      Specifica un valore di ponderazione compreso tra 0,0 e 1,0. Ogni componente in <weighted_term> può includere un valore weight_value. L'utilizzo di weight_value consente di modificare l'effetto delle varie parti di una query sul valore di pertinenza assegnato a ogni riga che soddisfa la query. WEIGHT non ha alcun effetto sui risultati delle query CONTAINS, ma ha effetto sul valore di pertinenza nelle query CONTAINSTABLE. Per ulteriori informazioni, vedere CONTAINSTABLE (Transact-SQL).

      [!NOTA] Il separatore decimale è sempre un punto indipendentemente dalle impostazioni internazionali del sistema operativo.

  • { AND | & } | { AND NOT | &! } | { OR | | }
    Specifica un'operazione logica tra due condizioni di ricerca del predicato CONTAINS.

    • AND | &
      Indica che devono essere soddisfatte entrambe le condizioni di ricerca. Per rappresentare l'operatore AND è possibile utilizzare il carattere e commerciale (&) anziché la parola chiave AND.
    • AND NOT | &!
      Indica che la seconda condizione di ricerca non deve essere soddisfatta. Per rappresentare l'operatore AND NOT è possibile utilizzare il carattere e commerciale seguito dal punto esclamativo (&!) anziché la parola chiave AND NOT.

    • OR | |
      Indica che deve essere soddisfatta una delle due condizioni di ricerca. Per rappresentare l'operatore OR è possibile utilizzare il carattere barra (|) anziché la parola chiave OR.

      Quando <contains_search_condition> include gruppi tra parentesi, tali gruppi vengono valutati per primi. Dopo la valutazione dei gruppi tra parentesi, gli operatori logici con condizioni di ricerca vengono valutati nell'ordine seguente:

      • L'operatore NOT viene applicato prima dell'operatore AND.
      • L'operatore NOT può essere usato solo dopo l'operatore AND, come in AND NOT. L'operatore OR NOT non è consentito. Non è possibile specificare l'operatore NOT prima del primo termine. Ad esempio, CONTAINS (mycolumn, 'NOT "phrase_to_search_for" ' ) non è valido:
      • L'operatore AND viene applicato prima dell'operatore OR.
      • Gli operatori booleani dello stesso tipo (AND, OR) sono associativi ed è pertanto possibile applicarli in qualsiasi ordine.
      • n
        Segnaposto che indica la possibilità di specificare più condizioni di ricerca e più termini.

Osservazioni

Il predicato CONTAINS non viene riconosciuto come parola chiave se il livello di compatibilità è inferiore a 70. Per ulteriori informazioni, vedere sp_dbcmptlevel (Transact-SQL).

Esempi

A. Utilizzo di CONTAINS con <simple_term>

Nell'esempio seguente vengono trovati tutti i prodotti il cui prezzo è $80.99 che includono la parola "Mountain".

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

B. Utilizzo di CONTAINS e di una frase in <simple_term>

Nell'esempio seguente vengono restituiti tutti i prodotti che contengono la parola "Mountain" o "Road".

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

C. Utilizzo di CONTAINS con <prefix_term>

Nell'esempio seguente vengono trovati tutti i nomi di prodotto della colonna Name contenenti almeno una parola che inizia con il prefisso chain.

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

D. Utilizzo di CONTAINS e OR con <prefix_term>

Nell'esempio seguente vengono restituite tutte le descrizioni di categoria contenenti stringhe con il prefisso "chain" o "full".

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

E. Utilizzo di CONTAINS con <proximity_term>

Nell'esempio seguente vengono restituiti tutti i nomi di prodotto in cui la parola bike è vicina alla parola performance.

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

F. Utilizzo di CONTAINS con <generation_term>

Nell'esempio seguente viene eseguita la ricerca di tutti i prodotti con parole derivate da ride: riding, ridden e così via.

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

G. Utilizzo di CONTAINS con <weighted_term>

Nell'esempio seguente viene eseguita la ricerca di tutti i nomi di prodotto contenenti le parole performance, comfortable o smooth. Ogni parola viene ponderata in modo diverso.

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

H. Utilizzo del predicato CONTAINS con variabili

Nell'esempio seguente viene utilizzata una variabile anziché un termine di ricerca specifico.

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

Vedere anche

Riferimento

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

Altre risorse

Ricerca full-text
Query di ricerca full-text

Guida in linea e informazioni

Assistenza su SQL Server 2005

Cronologia modifiche

Versione Cronologia

14 aprile 2006
Nuovo contenuto:
  • Aggiunta di informazioni in cui si consiglia di evitare la conversione con contains_search_condition.

15 settembre 2007
Nuovo contenuto:
  • Aggiunta di una nota sul separatore decimale alla definizione ISABOUT.