Compartilhar via

CONTAINSTABLE (Transact-SQL)

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

Retorna 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 dentro de uma determinada 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 que contêm tipos de dados baseados em caracteres.

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

Ao contrário CONTAINS, no entanto, 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. Para obter informações sobre os formatos de pesquisas de texto completo compatíveis com o SQL Server, consulte Consulta com a pesquisa de texto completo.

Convenções de sintaxe de 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

mesa

O nome de uma tabela indexada em texto completo. table pode ser um nome de objeto de banco de dados de uma, duas, três ou quatro partes. Quando você consulta uma exibição, apenas uma tabela base indexada de texto completo pode ser envolvida.

A 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 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 precisa ser colocada entre parênteses. A menos que language_term seja especificado, o idioma de todas as colunas da column_list precisará ser o mesmo.

*

Especifica que todas as colunas indexadas de texto completo na tabela devem ser usadas para pesquisar o critério de pesquisa especificado. A menos que language_term seja especificado, o idioma de todas as colunas da tabela precisará ser o mesmo.

LANGUAGE language_term

A linguagem cujos recursos são usados para quebra de palavras, lematização e dicionário de sinônimos e remoção de palavra de ruído (ou palavra irrelevante) 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 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 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 essa coluna, especifique LANGUAGE <language_term> para aumentar a probabilidade de uma boa correspondência.

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

Se o valor estiver no formato DBCS (conjunto de caracteres de bytes duplo), o 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 idioma neutro, 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 somente quando um valor inteiro, n, é 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 da consulta recuperando apenas as 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 informações sobre as condições de pesquisa, consulte CONTAINS.

Comentários

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

A tabela retornada tem uma coluna nomeada 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 KEY coluna 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 TableFulltextKeyColumn propriedade, obtida da OBJECTPROPERTYEX função, 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.

Para obter as linhas desejadas na tabela original, especifique uma junção com as CONTAINSTABLE linhas. A forma típica da FROM cláusula para uma SELECT instrução 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 inclui CONTAINSTABLE uma coluna chamada RANK. A RANK coluna é um valor (de 0 a 1000) para cada linha que indica o 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 :

  • ORDER BY Na cláusula para retornar as linhas de classificação mais altas 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 por usuários com os privilégios apropriados SELECT na tabela ou nas colunas da tabela referenciada.

Exemplos

a. Exemplo básico

O exemplo a seguir cria e preenche uma tabela simples de duas colunas, listando três países/regiões e as cores em seus sinalizadores. Ele cria e popula um catálogo de texto completo e um índice na tabela. Em seguida, a CONTAINSTABLE sintaxe é demonstrada. Este exemplo demonstra como o valor da classificação aumenta quando o valor da pesquisa é atendido várias vezes. Na última consulta, a Tanzânia, que contém verde e preto, tem uma classificação maior do que a Itália que contém apenas uma das cores consultadas.

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

O exemplo a seguir pesquisa todos os nomes de produto que contêm as palavras frame, wheelou tire, 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 com classificação mais alta serã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. Retornar valores de classificação maiores que um valor especificado

aplica-se a: SQL Server 2012 (11.x) e versões posteriores.

O exemplo a seguir usa NEAR para pesquisar bracket e reflector fechar uns aos outros na Production.Document tabela. Somente linhas com um valor de classificação de 50 ou superior são retornadas.

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

Observação

Se uma consulta de texto completo não especificar um inteiro como a distância máxima, um documento que contém apenas ocorrências cuja lacuna é maior que 100 termos lógicos não atende aos NEAR requisitos e sua classificação é 0.

D. Retornar os cinco melhores resultados classificados usando top_n_by_rank

O exemplo a seguir retorna a descrição dos cinco principais produtos em que a Description coluna contém a palavra aluminum 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

E. Especificar 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

Observação

O argumento LANGUAGE language_term não é necessário para usar top_n_by_rank.

Conteúdo relacionado

  • Last updated on