ALTER FULLTEXT INDEX (Transact-SQL)

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

Altera as propriedades de um índice de texto completo no SQL Server.

Convenções de sintaxe de Transact-SQL

Sintaxe

ALTER FULLTEXT INDEX ON table_name
   { ENABLE
   | DISABLE
   | SET CHANGE_TRACKING [ = ] { MANUAL | AUTO | OFF }
   | ADD ( column_name
           [ TYPE COLUMN type_column_name ]
           [ LANGUAGE language_term ]
           [ STATISTICAL_SEMANTICS ]
           [ , ...n ]
         )
     [ WITH NO POPULATION ]
   | ALTER COLUMN column_name
     { ADD | DROP } STATISTICAL_SEMANTICS
     [ WITH NO POPULATION ]
   | DROP ( column_name [ , ...n ] )
     [ WITH NO POPULATION ]
   | START { FULL | INCREMENTAL | UPDATE } POPULATION
   | { STOP | PAUSE | RESUME } POPULATION
   | SET STOPLIST [ = ] { OFF | SYSTEM | stoplist_name }
     [ WITH NO POPULATION ]
   | SET SEARCH PROPERTY LIST [ = ] { OFF | property_list_name }
     [ WITH NO POPULATION ]
   }
[ ; ]

Argumentos

table_name

O nome da tabela ou exibição indexada que contém a coluna ou colunas incluídas no índice de texto completo. A especificação dos nomes dos proprietários da tabela e do banco de dados é opcional.

ENABLE | DISABLE

Instrui o SQL Server quanto à coleta de dados de índice de texto completo para table_name. ENABLE ativa o índice de texto completo. DISABLE desativa o índice de texto completo. A tabela não dará suporte a consultas de texto completo enquanto o índice estiver desabilitado.

Desabilitar um índice de texto completo permite desativar o controle de alterações, mantendo o índice de texto completo que você pode reativar usando ENABLE a qualquer momento. Quando o índice de texto completo é desabilitado, os metadados de índice de texto completo permanecem nas tabelas do sistema. Se CHANGE_TRACKING estiver no estado habilitado (atualização automática ou manual) quando o índice de texto completo for desabilitado, o estado do índice congelará, qualquer rastreamento em andamento será interrompido e as novas alterações nos dados de tabela não serão controladas nem propagadas no índice.

SET CHANGE_TRACKING { MANUAL | AUTO | OFF }

Especifica se as alterações (atualizações, exclusões ou inserções) feitas nas colunas da tabela que estão cobertas pelo índice de texto completo serão propagadas pelo SQL Server para o índice de texto completo. As alterações de dados por meio de WRITETEXT e UPDATETEXT não são refletidas no índice de texto completo e não são coletadas com o controle de alterações.

• MANUAL

  Especifica que as alterações controladas são propagadas manualmente chamando a instrução Transact-SQL ALTER FULLTEXT INDEX … START UPDATE POPULATION (população manual). É possível usar o SQL Server Agent para chamar essa instrução Transact-SQL periodicamente.

• AUTO

  Especifica que as alterações controladas são propagadas automaticamente conforme os dados são modificados na tabela base (preenchimento automático). Embora sejam propagadas automaticamente, talvez essas alterações não se reflitam imediatamente no índice de texto completo. AUTO é o padrão.

• OFF

  Especifica que o SQL Server não mantém uma lista de alterações nos dados indexados.

ADD | DROP column_name

Especifica as colunas a serem adicionadas ou excluídas de um índice de texto completo. A coluna ou colunas devem ser do tipo char, varchar, nchar, nvarchar, text, ntext, image, xml, varbinary ou varbinary(max).

Use a cláusula DROP apenas em colunas que foram habilitadas anteriormente para indexação de texto completo.

Use TYPE COLUMN e LANGUAGE com a cláusula ADD para definir essas propriedades em column_name. Quando uma coluna é adicionada, o índice de texto completo na tabela deve ser repopulado para que as consultas de texto completo nessa coluna funcionem.

TYPE COLUMN type_column_name

Especifica o nome de uma coluna de tabela, type_column_name, usada para manter o tipo de um documento para um documento varbinary, varbinary(max) ou image. Essa coluna, conhecida como coluna de tipo, contém uma extensão de arquivo fornecida pelo usuário (.doc, .pdf, .xls e assim por diante). A coluna de tipo deve ser do tipo char, nchar, varchar, ou nvarchar.

Especifique TYPE COLUMN type_column_name somente se column_name especificar uma coluna varbinary, varbinary(max) ou image na qual os dados são armazenados como dados binários. Caso contrário, o SQL Server retornará um erro.

LANGUAGE language_term

O idioma dos dados armazenados em column_name.

language_term é 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 padrão da instância do SQL Server será usado.

Use o procedimento armazenado sp_configure para acessar informações sobre o idioma de texto completo da instância do SQL Server.

Quando especificado como uma cadeia de caracteres, language_term corresponde ao valor da coluna alias na tabela do sistema 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, incluindo zeros à esquerda.

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

Os recursos, como separadores e lematizadores de palavras, devem estar habilitados para o idioma especificado como language_term. Se tais recursos não aceitarem o idioma especificado, o SQL Server retornará um erro.

Para colunas não BLOB e não XML que contêm dados de texto em vários idiomas ou nos casos em que o idioma do texto armazenado na coluna é desconhecido, use o recurso de idioma neutro (0x0). Para documentos armazenados em colunas do tipo XML ou BLOB, a codificação de idioma do documento é usada no momento da indexação. Por exemplo, em colunas XML, o atributo xml:lang em documentos XML identifica o idioma. No momento da consulta, o valor especificado anteriormente em language_term se torna o idioma padrão usado para consultas de texto completo, a menos que language_term seja especificado como parte de uma consulta de texto completo.

STATISTICAL_SEMANTICS

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

Cria a frase-chave adicional e índices de similaridade de documentos que fazem parte da indexação semântica estatística. Para obter mais informações, confira Pesquisa semântica (SQL Server).

[ , ...n ]

Indica que várias colunas podem ser especificadas para as cláusulas ADD, ALTER ou DROP. Ao especificar várias colunas, separe-as com vírgulas.

WITH NO POPULATION

Especifica que o índice de texto completo não será populado depois de uma operação de coluna ADD ou DROP, ou uma operação SET STOPLIST. O índice é populado somente se o usuário executa um comando START...POPULATION.

Quando a opção NO POPULATION for especificada, o SQL Server não populará um índice. O índice será populado somente depois que o usuário executar um comando ALTER FULLTEXT INDEX...START POPULATION. Quando a opção NO POPULATION não for especificada, o SQL Server populará o índice.

Se CHANGE_TRACKING estiver habilitado e WITH NO POPULATION for especificado, o SQL Server retornará um erro. Se CHANGE_TRACKING estiver habilitado e WITH NO POPULATION não for especificado, o SQL Server executará um preenchimento completo do índice.

{ADD | DROP } STATISTICAL_SEMANTICS

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

Habilita ou desabilita a indexação semântica estatística para as colunas especificadas. Para obter mais informações, confira Pesquisa semântica (SQL Server).

START { FULL | INCREMENTAL | UPDATE } POPULATION

Instrui o SQL Server a começar a preencher o índice de texto completo de table_name. Se um preenchimento de índice de texto completo já estiver em andamento, o SQL Server retornará um aviso e não iniciará o novo preenchimento.

• FULL

  Especifica que cada linha da tabela deve ser recuperada para a indexação de texto completo, mesmo que as linhas já tenham sido indexadas.

• INCREMENTAL

  Especifica que somente as linhas modificadas desde que a última população devem ser recuperadas para indexação de texto completo. INCREMENTAL poderá ser aplicado somente se a tabela tiver uma coluna do tipo timestamp. Se uma tabela no catálogo de texto completo não tiver uma coluna do tipo timestamp, a tabela passará por um preenchimento FULL.

• UPDATE

  Especifica o processamento de todas as inserções, atualizações ou exclusões desde a última vez que o índice de controle de alterações foi atualizado. A população de controle de alterações deve estar habilitada em uma tabela, mas o índice de atualização em segundo plano ou o controle de alterações automático não devem estar ativados.

{STOP | PAUSE | RESUME } POPULATION

Interrompe ou pausa todas as populações em andamento; ou interrompe ou retoma todas as populações pausadas.

STOP POPULATION não interrompe o controle de alterações automático ou o índice de atualização em segundo plano. Para interromper o controle de alterações, use SET CHANGE_TRACKING OFF.

PAUSE POPULATION e RESUME POPULATION podem ser usados somente para populações completas. Eles não são relevantes para outros tipos de população porque as outras populações retomam os rastreamentos do ponto em que eles pararam.

SET STOPLIST { OFF | SYSTEM | stoplist_name }

Altera a lista de palavras irrelevantes de texto completo associada ao índice, se houver.

• OFF

  Especifica que nenhuma lista de palavras irrelevantes seja associada ao índice de texto completo.

• SISTEMA

  Especifica que a lista de palavras irrelevantes do sistema de texto completo padrão deve ser usada para esse índice de texto completo.

• stoplist_name

  Especifica o nome da lista de palavras irrelevantes que deve ser associada ao índice de texto completo.

Para obter mais informações, veja Configurar e gerenciar palavras irrelevantes e listas de palavras irrelevantes para pesquisa de texto completo.

SET SEARCH PROPERTY LIST { OFF | property_list_name } [ WITH NO POPULATION ]

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

Altera a lista de propriedades de pesquisa associada ao índice, se houver.

• OFF

  Especifica que nenhuma lista de propriedades será associada ao índice de texto completo. Quando você desliga a lista de propriedades de pesquisa de um índice de texto completo (ALTER FULLTEXT INDEX ... SET SEARCH PROPERTY LIST OFF), a pesquisa de propriedades na tabela base não é mais possível.

  Por padrão, quando você desativar uma lista de propriedades de pesquisa existente, o índice de texto completo será repopulado automaticamente. Se você especificar WITH NO POPULATION quando desativar a lista de propriedades de pesquisa, a repopulação automática não ocorrerá. Porém, quando for conveniente, é recomendável executar uma população completa nesse índice de texto completo. A repopulação do índice de texto completo remove os metadados específicos de cada propriedade de pesquisa removida, o que torna o índice de texto completo menor e mais eficiente.

• property_list_name

  Especifica o nome da lista de propriedades de pesquisa que deve ser associada ao índice de texto completo.

  A adição de uma lista de propriedades de pesquisa a um índice de texto completo exige a repopulação do índice para indexar as propriedades de pesquisa que são registradas para a lista de propriedades de pesquisa associada. Se você especificar WITH NO POPULATION ao adicionar a lista de propriedades de pesquisa, será necessário executar uma população no índice em um momento apropriado.

Localizar as listas de propriedades de pesquisa no banco de dados atual

• sys.registered_search_property_lists

Para obter mais informações sobre listas de propriedades de pesquisa, veja Pesquisar propriedades de documento com listas de propriedades de pesquisa.

Comentários

Em colunas xml, você pode criar um índice de texto completo que indexa o conteúdo dos elementos XML, mas ignora a marcação XML. Os valores de atributos são indexados como texto completo, a menos que sejam valores numéricos. Marcas de elemento são usadas como limites do token. Há suporte a fragmentos e documentos XML ou HTML bem formados que contêm vários idiomas. Para obter mais informações, veja Usar a pesquisa de texto completo com colunas XML.

Recomendamos que a coluna de chave de índice seja de um tipo de dados inteiro. Isso otimiza o tempo de execução da consulta.

ALTER FULLTEXT INDEX não pode ser colocado dentro de uma transação de usuário. Essa instrução deve ser executada em sua própria transação implícita.

Para obter mais informações sobre índices de texto completo, veja Criar e gerenciar índices de texto completo.

Interações do controle de alterações e do parâmetro NO POPULATION

O fato de o índice de texto completo ser populado depende de o controle de alterações estar habilitado e de WITH NO POPULATION ter sido especificado na instrução ALTER FULLTEXT INDEX. A tabela a seguir resume o resultado da interação.

Para obter mais informações sobre o preenchimento de índices de texto completo, veja Preencher índices de texto completo.

Alterar a lista de propriedades de pesquisa causa a recriação do índice

Da primeira vez que um índice de texto completo é associado a uma lista de propriedades de pesquisa, o índice deve ser repopulado para indexar termos de pesquisa específicos da propriedade. Os dados de índice existentes não são truncados.

Porém, se você associar o índice de texto completo a uma outra lista de propriedades, o índice será recriado. A recriação trunca o índice de texto completo imediatamente, removendo todos os dados existentes, e o índice deve ser repopulado. Enquanto o preenchimento é realizado, consultas de texto completo na tabela base pesquisam apenas nas linhas da tabela que já foram indexadas pelo preenchimento. Os dados de índice repopulados incluem metadados das propriedades registradas da lista de propriedades de pesquisa recém-adicionada.

Os cenários que causam a recriação incluem:

• Alterne diretamente para uma outra lista de propriedades de pesquisa (consulte "Cenário A" posteriormente nesta seção).

• Desative a lista de propriedades de pesquisa e depois associe o índice a qualquer lista de propriedades de pesquisa (consulte "Cenário B" posteriormente nesta seção).

Cenário A: Alternar diretamente para uma outra lista de propriedades de pesquisa

1. Um índice de texto completo é criado em table_1 com uma lista de propriedades de pesquisa spl_1:

   CREATE FULLTEXT INDEX ON table_1 (column_name) KEY INDEX unique_key_index
       WITH SEARCH PROPERTY LIST=spl_1,
       CHANGE_TRACKING OFF, NO POPULATION;
   

2. Uma população completa é executada no índice de texto completo:

   ALTER FULLTEXT INDEX ON table_1 START FULL POPULATION;
   

3. O índice de texto completo é associado posteriormente a uma outra lista de propriedades de pesquisa, spl_2, usando a seguinte instrução:

   ALTER FULLTEXT INDEX ON table_1 SET SEARCH PROPERTY LIST spl_2;
   

   Essa instrução gera uma população completa, o comportamento padrão. Porém, antes de começar essa população, o Mecanismo de Texto Completo trunca o índice automaticamente.

Cenário B: Desativar a lista de propriedades de pesquisa e depois associar o índice a qualquer lista de propriedades de pesquisa

1. Um índice de texto completo é criado em table_1 com uma lista de propriedades de pesquisa spl_1, seguido pelo preenchimento completo automático (o comportamento padrão):

   CREATE FULLTEXT INDEX ON table_1 (column_name) KEY INDEX unique_key_index
       WITH SEARCH PROPERTY LIST=spl_1;
   

2. A lista de propriedades de pesquisa é desativada da seguinte maneira:

   ALTER FULLTEXT INDEX ON table_1
       SET SEARCH PROPERTY LIST OFF WITH NO POPULATION;
   

3. O índice de texto completo é associado mais uma vez à mesma lista de propriedades de pesquisa ou a uma lista de propriedades de pesquisa diferente.

   Por exemplo, a seguinte instrução reassocia o índice de texto completo com a lista de propriedades de pesquisa original, spl_1:

   ALTER FULLTEXT INDEX ON table_1 SET SEARCH PROPERTY LIST spl_1;
   

   Essa instrução inicia uma população completa, o comportamento padrão.

   Observação

   A recompilação também seria necessária para uma lista de propriedades de pesquisa diferente, como spl_2.

Permissões

O usuário deve ter a permissão ALTER na exibição de tabela ou indexada, ou ser membro da função de servidor fixa sysadmin ou das funções de banco de dados fixas db_ddladmin ou db_owner.

Se a opção SET STOPLIST estiver especificada, o usuário deverá ter a permissão REFERENCES na lista de palavras irrelevantes. Se a opção SEARCH PROPERTY LIST estiver especificada, o usuário deverá ter a permissão REFERENCES na lista de propriedades de pesquisa. O proprietário da lista de palavras irrelevantes ou da lista de propriedades de pesquisa especificada pode conceder a permissão REFERENCES, se o proprietário tiver permissões ALTER FULLTEXT CATALOG.

Exemplos

R. Definir rastreamento manual de alterações

O exemplo a seguir define o controle de alterações manual no índice de texto completo na tabela JobCandidate.

USE AdventureWorks2022;
GO
ALTER FULLTEXT INDEX ON HumanResources.JobCandidate
   SET CHANGE_TRACKING MANUAL;
GO

B. Associar uma lista de propriedades a um índice de texto completo

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

O exemplo a seguir associa a lista de propriedades DocumentPropertyList ao índice de texto completo na tabela Production.Document. Essa instrução ALTER FULLTEXT INDEX inicia uma população completa, que é o comportamento padrão da cláusula SET SEARCH PROPERTY LIST.

USE AdventureWorks2022;
GO
ALTER FULLTEXT INDEX ON Production.Document
   SET SEARCH PROPERTY LIST DocumentPropertyList;
GO

C. Remover uma lista de propriedades de pesquisa

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

O exemplo a seguir remove a lista de propriedades DocumentPropertyList do índice de texto completo na tabela Production.Document. Neste exemplo, não há pressa para remover as propriedades do índice, de forma que a opção WITH NO POPULATION é especificada. Porém, a pesquisa em nível de propriedade é permitida por mais tempo em relação a esse índice de texto completo.

USE AdventureWorks2022;
GO
ALTER FULLTEXT INDEX ON Production.Document
   SET SEARCH PROPERTY LIST OFF WITH NO POPULATION;
GO

D. Iniciar uma população completa

O exemplo a seguir inicia um preenchimento total no índice de texto completo na tabela JobCandidate.

USE AdventureWorks2022;
GO
ALTER FULLTEXT INDEX ON HumanResources.JobCandidate
   START FULL POPULATION;
GO

Confira também

• sys.fulltext_indexes (Transact-SQL)
• CREATE FULLTEXT INDEX (Transact-SQL)
• DROP FULLTEXT INDEX (Transact-SQL)
• Pesquisa de texto completo
• Popular índices de texto completo