CONTAINSTABLE (Transact-SQL)

Artigo
06/18/2013

Retorna uma tabela com zero, uma ou mais linhas para as colunas que contêm correspondências precisas ou difusas (menos precisas) com palavras individuais e frases, a proximidade entre as palavras em uma determinada distância 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 comum. Ele executa uma pesquisa de texto completo do SQL Server em colunas indexadas de texto completo que contêm tipos de dados com base em caracteres.

CONTAINSTABLE é útil para os mesmos tipos de correspondências que o predicado CONTAINS e utiliza os mesmos critérios de pesquisa de CONTAINS.

Diferentemente de CONTAINS, as consultas que usam CONTAINSTABLE retornam um valor de classificação de relevância (RANK) e uma chave de texto completo (KEY) para cada linha.

Observação
Para obter informações sobre os formulários de pesquisas de texto completo que têm suporte no SQL Server, consulte Consulta com pesquisa de texto completo.

Ícone de vínculo de tópico Convenções da sintaxe Transact-SQL

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

table
É o nome de uma tabela que foi indexada com texto completo. table pode ser um nome de objeto de banco de dados de uma, duas, três ou quatro partes. Durante a consulta a uma exibição, apenas uma tabela base indexada por texto completo pode ser envolvida.

table não pode especificar um nome de servidor e não pode ser usado em consultas a servidores vinculados.
column_name
É o nome de uma ou mais colunas indexadas para pesquisa de texto completo. As colunas podem ser do tipo char, varchar, nchar, nvarchar, text, 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 incluído entre parênteses. A menos que language_term esteja especificado, o idioma de todas as colunas de column_list deve ser o mesmo.
*
Especifica que todas as colunas indexadas por texto completo em table devem ser usadas para pesquisar pelo critério de pesquisa fornecido. A menos que language_term esteja especificado, o idioma de todas as colunas da tabela deve ser o mesmo.
LANGUAGE language_term
É o idioma cujos recursos serão usados para separação de palavras, lematização, dicionário de sinônimos e remoção de palavras de ruído (ou palavras irrelevantes) como parte da consulta. Esse parâmetro é opcional e pode ser especificado como uma cadeia de caracteres, um inteiro ou um valor hexadecimal que corresponda ao LCID (identificador de localidade) de um idioma. Se language_term for especificado, o idioma que ele representa será aplicado a todos os elementos do critério de pesquisa. Se nenhum valor for especificado, o idioma de texto completo da coluna será usado.

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

Quando especificado como uma cadeia de caracteres, language_term corresponde ao valor da coluna alias da exibição de compatibilidade sys.syslanguages. A cadeia de caracteres deve estar 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 dois bytes), o Microsoft SQL Server o converterá em Unicode.

Se o idioma especificado não for válido ou se não houver nenhum recurso instalado que corresponda ao idioma, o SQL Server retornará um erro. Para usar os recursos de idioma neutros, especifique 0x0 como language_term.
top_n_by_rank
Especifica que apenas as n correspondências com classificação mais alta, em ordem decrescente, são retornadas. Aplica-se apenas quando um valor inteiro, n, está especificado. Se top_n_by_rank for combinado com outros parâmetros, a consulta retornará menos linhas do que o número de linhas que corresponde de fato a todos os predicados. top_n_by_rank permite aumentar o desempenho de consultas com a recuperação apenas das ocorrências mais relevantes.
<contains_search_condition>
Especifica o texto a ser pesquisado em column_name e os critérios para uma correspondência. Para obter mais informações sobre os critérios de pesquisa, consulte CONTAINS (Transact-SQL).

Comentários

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

A tabela retornada possui uma coluna chamada KEY que contém valores de chave de texto completo. Cada tabela indexada de texto completo possui uma coluna cujos valores têm garantia de exclusividade e os valores retornados na coluna KEY são valores de chave de texto completo das linhas que correspondem aos critérios de seleção especificados no critério de pesquisa contains. A propriedade TableFulltextKeyColumn, obtida a partir 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 junção com as linhas CONTAINSTABLE. O formulário típico da cláusula FROM de uma instrução SELECT que usa 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 contém uma coluna chamada RANK. A coluna RANK é um valor (de 0 a 1000) para cada linha que indica a qualidade da correspondência da linha com os critérios de seleção. Geralmente, esse valor de classificação é usado de uma destas maneiras na instrução SELECT:

Na cláusula ORDER BY para retornar as linhas com classificação mais alta como as primeiras linhas da tabela.
Na lista de seleção para ver o valor de classificação atribuído à cada linha.

Permissões

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

Exemplos

A.Retornando valores de classificação

O exemplo a seguir pesquisa todos os nomes de produtos que contêm as palavras "frame," "wheel" ou "tire", e diferentes pesos são dados a cada uma. Para cada linha retornada que corresponda a esses critérios de pesquisa, será mostrada a proximidade relativa (valor de classificação) da correspondência. Além disso, as linhas com classificação mais alta serão retornadas primeiro.

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

O exemplo a seguir usa NEAR para pesquisar as palavras "bracket" e "reflector" próximas uma da outra na coluna Production.Document do banco de dados AdventureWorks2008. Apenas as linhas com valor de classificação 50 ou maior são retornadas.

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

Observação
Se uma consulta de texto completo não especificar um valor inteiro como a distância máxima, um documento que contenha apenas ocorrências cujos intervalos sejam maiores que 100 termos lógicos não atenderá aos requisitos de NEAR e terá uma classificação de 0.

C.Retornando os 5 maiores resultados da classificação por meio de top_n_by_rank

O exemplo a seguir retorna a descrição dos cinco produtos cuja coluna Description contém a palavra "aluminum" próxima às palavras "light" ou "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

D.Especificando o argumento LANGUAGE

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

Observação
O argumento LANGUAGE language_term não é necessário para o uso de top_n_by_rank.

Consulte também