CONTIDA (Transact-SQL)

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada SQL do Azure

Devolve uma tabela de zero, uma ou mais linhas para as colunas que contêm correspondências precisas ou difusas(menos precisas) para palavras e frases únicas, a proximidade de palavras a uma certa distância umas das outras ou correspondências ponderadas. CONTAINSTABLE é usado na cláusula FROM de uma instrução Transact-SQL SELECT e é referenciado como se fosse um nome de tabela regular. Ele executa uma pesquisa de texto completo do SQL Server em colunas indexadas de texto completo contendo tipos de dados baseados em caracteres.

CONTAINSTABLE é útil para os mesmos tipos de correspondências que o CONTÉM predicado e usa as mesmas condições de pesquisa que CONTAINS.

Ao contrário de CONTAINS, no entanto, as consultas usando CONTAINSTABLE retornam um valor de classificação de relevância (RANK) e uma chave de texto completo (KEY) para cada linha. Para obter informações sobre as formas de pesquisas de texto completo suportadas pelo SQL Server, consulte Consulta com Full-Textde Pesquisa .

Transact-SQL convenções de sintaxe

Sintaxe

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

Argumentos

tabela
É o nome de uma tabela que foi indexada em texto completo. tabela pode ser um nome de objeto de banco de dados de uma, duas, três ou quatro partes. Ao consultar um modo de exibição, apenas uma tabela base indexada de texto completo pode ser envolvida.

tabela não pode especificar um nome de servidor e não pode ser usada em consultas em servidores vinculados.

column_name
É o nome de uma ou mais colunas que são indexadas para pesquisa de texto completo. As colunas podem ser do tipo char, varchar, nchar, nvarchar, texto, ntext, image, xml, varbinary, ou varbinary(max).

column_list
Indica que várias colunas, separadas por uma vírgula, podem ser especificadas. column_list deve ser colocado entre parênteses. A menos que language_term seja especificado, o idioma de todas as colunas de column_list deve ser o mesmo.

*
Especifica que todas as colunas indexadas de texto completo em de tabela devem ser usadas para pesquisar a condição de pesquisa fornecida. A menos que language_term seja especificado, o idioma de todas as colunas da tabela deve ser o mesmo.

LÍNGUA language_term
É a linguagem cujos recursos serão usados para quebra de palavras, derivação e tesauro e remoção de palavras de ruído (ou de palavras-parada ) como parte da consulta. Esse parâmetro é opcional e pode ser especificado como uma cadeia de caracteres, inteiro ou valor hexadecimal correspondente ao identificador de localidade (LCID) de um idioma. Se language_term for especificado, o idioma que ele representa será aplicado a todos os elementos da condição de pesquisa. Se nenhum valor for especificado, o idioma de texto completo da coluna será usado.

Se documentos de idiomas diferentes forem armazenados juntos como objetos binários grandes (BLOBs) em uma única coluna, o identificador de localidade (LCID) de um determinado documento determinará qual idioma será usado para indexar seu conteúdo. Ao consultar essa coluna, especificar LANGUAGE**language_term pode aumentar a probabilidade de uma boa correspondência.

Quando especificado como uma cadeia de caracteres, language_term corresponde ao alias de valor da coluna no modo de exibição de compatibilidade sys.syslanguages . A cadeia de caracteres deve ser colocada entre aspas simples, como em 'language_term'. Quando especificado como um inteiro, language_term é o LCID real que identifica o idioma. Quando especificado como um valor hexadecimal, language_term é 0x seguido pelo valor hexadecimal do LCID. O valor hexadecimal não deve exceder oito dígitos, incluindo zeros à esquerda.

Se o valor estiver no formato DBCS (conjunto de caracteres de byte duplo), o Microsoft SQL Server o converterá em Unicode.

Se o idioma especificado não for válido ou não houver recursos instalados que correspondam a esse idioma, o SQL Server retornará um erro. Para usar os recursos de linguagem neutra, especifique 0x0 como language_term.

top_n_by_rank
Especifica que apenas as correspondências n mais bem classificadas, em ordem decrescente, são retornadas. Aplica-se somente quando um valor inteiro, n, é especificado. Se top_n_by_rank for combinado com outros parâmetros, a consulta poderá retornar menos linhas do que o número de linhas que realmente correspondem a todos os predicados. top_n_by_rank permite aumentar o desempenho da consulta lembrando apenas os acertos mais relevantes.

<contains_search_condition>
Especifica o texto a ser pesquisado em column_name e as condições para uma correspondência. Para obter informações sobre as condições de pesquisa, consulte CONTÉM (Transact-SQL).

Comentários

Predicados e funções de texto completo funcionam em uma única tabela, o que está implícito no predicado FROM. Para pesquisar em várias tabelas, use uma tabela unida na cláusula FROM para pesquisar um conjunto de resultados que seja o produto de duas ou mais tabelas.

A tabela retornada tem uma coluna chamada KEY que contém valores de chave de texto completo. Cada tabela indexada de texto completo tem uma coluna cujos valores são garantidos como exclusivos, e os valores retornados na coluna KEY são os valores de chave de texto completo das linhas que correspondem aos critérios de seleção especificados na condição de pesquisa contém. A propriedade TableFulltextKeyColumn, obtida da função OBJECTPROPERTYEX, fornece a identidade dessa coluna de chave exclusiva. Para obter a ID da coluna associada à chave de texto completo do índice de texto completo, use sys.fulltext_indexes. Para obter mais informações, consulte sys.fulltext_indexes (Transact-SQL).

Para obter as linhas desejadas da tabela original, especifique uma associação com as linhas CONTAINSTABLE. A forma típica da cláusula FROM para uma instrução SELECT usando 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];  

A tabela produzida por CONTAINSTABLE inclui uma coluna chamada RANK. A coluna RANK é um valor (de 0 a 1000) para cada linha que indica quão bem uma linha correspondeu aos critérios de seleção. Esse valor de classificação normalmente é usado de uma destas maneiras na instrução SELECT:

• Na cláusula ORDER BY para retornar as linhas de classificação mais alta como as primeiras linhas da tabela.

• Na lista de seleção para ver o valor de classificação atribuído a cada linha.

Permissões

As permissões de execução estão disponíveis apenas por usuários com os privilégios SELECT apropriados na tabela ou nas colunas da tabela referenciada.

Exemplos

Um. Exemplo simples

O exemplo a seguir cria e preenche uma tabela simples de duas colunas, listando 3 condados e as cores em suas bandeiras. Ele cria e preenche um catálogo de texto completo e um índice na tabela. Em seguida, a sintaxe CONTAINSTABLE é demonstrada. Este exemplo demonstra como o valor de classificação aumenta quando o valor de pesquisa é atendido várias vezes. Na última consulta, a Tanzânia, que contém verde e preto, tem uma classificação mais alta do que a Itália, que contém apenas uma das cores consultadas.

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. Retornando valores de classificação

O exemplo a seguir procura todos os nomes de produtos que contenham as palavras "quadro", "roda" ou "pneu" e pesos diferentes são dados a cada palavra. Para cada linha retornada que corresponde a esses critérios de pesquisa, a proximidade relativa (valor de classificação) da correspondência é mostrada. Além disso, as linhas de classificação mais alta são retornadas primeiro.

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. Retornando valores de classificação maiores que um valor especificado

O exemplo a seguir usa NEAR para procurar "bracket" e "reflector" próximos um do outro na tabela Production.Document. Apenas as linhas com um valor de classificação igual ou superior a 50 são devolvidas.

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. Retornando os 5 melhores resultados classificados usando top_n_by_rank

O exemplo a seguir retorna a descrição dos 5 principais produtos em que a coluna Description contém a palavra "alumínio" perto da palavra "light" ou da palavra "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. Especificando o argumento LANGUAGE

O exemplo a seguir mostra o uso do argumento 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  

Ver também

Limitar resultados de pesquisa com RANK
Consulta com de Pesquisa Full-Text
Criar consultas de pesquisa Full-Text (Visual Database Tools)
CONTÉM (Transact-SQL)
Consulta com de Pesquisa Full-Text
SELECIONAR (Transact-SQL)
DE (Transact-SQL)