FREETEXT (Transact-SQL)

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Banco de Dados SQL no Microsoft Fabric

É um predicado usado na cláusula WHERE do Transact-SQL de uma instrução Transact-SQL SELECT para executar uma pesquisa de texto completo do SQL Server em uma coluna indexada de texto completo que contém tipos de dados baseados em caracteres. Esse predicado procura valores correspondentes ao significado e não apenas o teor exato das palavras nos critérios da pesquisa. Quando FREETEXT é usado, o mecanismo de consulta de texto completo executa internamente as ações a seguir na freetext_string, atribui um peso a cada termo e, em seguida, localiza as correspondências:

• Separa a cadeia de caracteres em palavras individuais com base em limites de palavra (quebra de palavras).

• Gera formas flexivas das palavras (ramificações).

• Identifica uma lista de expansões ou substituições dos termos baseados em correspondências no dicionário de sinônimos.

Observação

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.

Aplica-se a: SQL Server [SQL Server 2008 (10.0.x) à versão atual].

Convenções de sintaxe de Transact-SQL

Sintaxe

FREETEXT ( { column_name | (column_list) | * }   
          , 'freetext_string' [ , LANGUAGE language_term ] )  

Argumentos

column_name
É o nome de uma ou mais colunas indexadas de texto completo da tabela especificada na cláusula FROM. 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 que forem registradas para pesquisa de texto completo deverão ser usadas para pesquisar a freetext_string determinada. Se mais de uma tabela estiver na cláusula FROM, * deverá ser qualificado pelo nome da tabela. A menos que language_term seja especificado, o idioma de todas as colunas da tabela precisará ser o mesmo.

freetext_string
É o texto a ser pesquisado no column_name. Qualquer texto, incluindo palavras, frases ou orações, pode ser inserido. Serão geradas correspondências se forem achados termos ou formas de termos no índice de texto completo.

Ao contrário do critério de pesquisa CONTAINS e CONTAINSTABLE, em que AND é uma palavra-chave, quando usada em freetext_string a palavra 'and' será considerada uma palavra de ruído ou palavra irrelevante (stop word) e será descartada.

Não é permitido o uso de WEIGHT, FORMSOF, curingas, NEAR e outra sintaxe. freetext_string é uma palavra quebrada, não flexionada e passada pelo dicionário de sinônimos.

freetext_string é nvarchar. Uma conversão implícita acontece quando outro tipo de dados de caractere é usado como entrada. Os tipos de dados de cadeia de caracteres grande nvarchar(max) e varchar(max) não podem ser usados. No exemplo a seguir, a variável @SearchWord, que está definida como varchar(30), causa uma conversão implícita no predicado FREETEXT.

USE AdventureWorks2022;  
GO  
DECLARE @SearchWord VARCHAR(30)  
SET @SearchWord ='performance'  
SELECT Description   
FROM Production.ProductDescription   
WHERE FREETEXT(Description, @SearchWord);  
  

Como a "detecção de parâmetro" não funciona na conversão, use nvarchar para melhorar o desempenho. No exemplo, declare @SearchWord como nvarchar(30).

USE AdventureWorks2022;  
GO  
DECLARE @SearchWord NVARCHAR(30)  
SET @SearchWord = N'performance'  
SELECT Description   
FROM Production.ProductDescription   
WHERE FREETEXT(Description, @SearchWord);  
  

Você também pode usar a dica de consulta OPTIMIZE FOR para casos em que um plano não ideal é gerado.

LANGUAGE language_term
É o idioma cujos recursos serão usados para quebra de palavras, lematização e dicionário de sinônimos e remoção de palavras irrelevantes (stop words) 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 uma coluna desse tipo, especificar 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 no modo de exibição de compatibilidade sys.syslanguages (Transact-SQL). 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 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 Microsoft SQL Server retornará um erro. Para usar os recursos de idioma neutro, especifique 0x0 como language_term.

Comentários gerais

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.

Consultas de texto completo que usam FREETEXT são menos precisas que consultas de texto completo que usam CONTAINS. O mecanismo de pesquisa de texto completo do SQL Server identifica palavras e frases importantes. Nenhum significado especial é dado a nenhuma das palavra-chave reservadas ou dos caracteres curingas que geralmente têm um significado quando são especificados no parâmetro <contains_search_condition> do predicado CONTAINS.

Predicados de texto completo não são permitidos na cláusula OUTPUT quando o nível de compatibilidade do banco de dados é definido como 100.

Observação

A função FREETEXTTABLE é útil para os mesmos tipos de correspondência que o predicado FREETEXT. É possível referenciar essa função como um nome de tabela normal na cláusula FROM de uma instrução SELECT. Para obter mais informações, confira FREETEXTTABLE (Transact-SQL).

Consultando servidores remotos

É possível usar um nome de quatro partes no predicado CONTAINS ou FREETEXT para consultar colunas indexadas de texto completo das tabelas de destino em um servidor vinculado. Para preparar um servidor remoto para receber consultas de texto completo, crie um índice de texto completo nas tabelas e colunas de destino no servidor remoto e, em seguida, adicione o servidor remoto como um servidor vinculado.

Comparação entre LIKE e a pesquisa de texto completo

Ao contrário da pesquisa de texto completo, o predicado LIKETransact-SQL funciona apenas em padrões de caracteres. Além disso, não é possível usar o predicado LIKE para consultar dados binários formatados. Além disso, uma consulta LIKE feita em uma grande quantidade de dados de texto não estruturados é bem mais lenta do que uma consulta de texto completo equivalente feita nos mesmos dados. Uma consulta LIKE executada em milhões de linhas de dados de texto pode demorar muitos minutos, enquanto uma consulta de texto completo pode demorar alguns segundos ou menos para ser executada nos mesmos dados, dependendo do número de linhas retornadas.

Exemplos

a. Usando FREETEXT para pesquisar palavras que contêm valores de caracteres especificados

As pesquisas de exemplo a seguir para todos os documentos que contêm as palavras relacionadas a componentes vitais, de segurança.

USE AdventureWorks2022;  
GO  
SELECT Title  
FROM Production.Document  
WHERE FREETEXT (Document, 'vital safety components' );  
GO  

B. Usando FREETEXT com variáveis

O exemplo a seguir usa uma variável em vez de um termo de pesquisa específico.

USE AdventureWorks2022;  
GO  
DECLARE @SearchWord NVARCHAR(30);  
SET @SearchWord = N'high-performance';  
SELECT Description   
FROM Production.ProductDescription   
WHERE FREETEXT(Description, @SearchWord);  
GO  

Consulte Também

Iniciar a pesquisa de texto completo
Criar e gerenciar catálogos de texto completo
CREATE FULLTEXT CATALOG (Transact-SQL)
CREATE FULLTEXT INDEX (Transact-SQL)
Criar e gerenciar índices de texto completo
Consulta com pesquisa de texto completo
Criar consultas de pesquisa de texto completo (Visual Database Tools)
CONTAINS (Transact-SQL)
CONTAINSTABLE (Transact-SQL)
Tipos de dados (Transact-SQL)
FREETEXTTABLE (Transact-SQL)
WHERE (Transact-SQL)