ALTER FULLTEXT INDEX (Transact-SQL)

Altera as propriedades de um índice de texto completo.

Convenções da sintaxe 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 cobertas pelo índice de texto completo serão propagadas pelo SQL Server para o índice de texto completo. As alterações de dados através de WRITETEXT e UPDATETEXT não se refletem no índice de texto completo e não são obtidas com o controle de alterações.

  Observação
  Para obter informações sobre a interação do controle de alterações e de WITH NO POPULATION, consulte "Comentários" posteriormente neste tópico.

• MANUAL
  Especifica que as alterações controladas serã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 serão propagadas automaticamente conforme os dados forem modificados na tabela base (população automática). 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 manterá 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 as colunas devem ser dos tipos 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.

  Observação
  O fato de o índice de texto completo ser populado depois que uma coluna é adicionada ou removida de um índice de texto completo depende de o controle de alterações estar habilitado e de WITH NO POPULATION ter sido especificado. Para obter mais informações, consulte "Comentários" posteriormente neste tópico.

• TYPE COLUMN type_column_name
  Especifica o nome de uma coluna de tabela, type_column_name, usada para manter o tipo de 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.

  Observação

  No momento da indexação, o Mecanismo de Texto Completo usa a abreviação na coluna de tipo de cada linha da tabela para identificar o filtro de pesquisa de texto completo que deve ser usado para o documento no column_name. O filtro carrega o documento como um fluxo binário, remove as informações de formatação e envia o texto do documento para o componente do separador de palavras. Para obter mais informações, consulte Configurar e gerenciar filtros para pesquisa.

• 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 padrão 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 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 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 será usada no momento da indexação. Por exemplo, em colunas XML, o atributo xml:lang em documentos XML identificará 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
  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, consulte 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 será populado somente se o usuário executar 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, 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á uma população completa no índice.

  Observação
  Para obter mais informações sobre a interação do controle de alterações e WITH NO POPULATION, consulte "Comentários" mais adiante neste tópico.

• {ADD | DROP } STATISTICAL_SEMANTICS
  Habilita ou desabilita a indexação semântica estatística para as colunas especificadas. Para obter mais informações, consulte Pesquisa semântica (SQL Server).

• START {FULL|INCREMENTAL|UPDATE} POPULATION
  Instrui o SQL Server a começar a população do índice de texto completo de table_name. Se uma população de índice de texto completo já estiver em andamento, o SQL Server retornará um aviso e não iniciará a nova população.

• • 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 sofrerá uma população 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.

  • SYSTEM
    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, consulte Configurar e gerenciar palavras irrelevantes e listas de palavras irrelevantes (stoplists) para pesquisa de texto completo.

• SET SEARCH PROPERTY LIST { OFF | property_list_name } [ WITH NO POPULATION ]
  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ê desativar 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 será 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.

    Importante

    Se o índice de texto completo foi previamente associado a uma outra pesquisa, ele deverá ser a lista de propriedades recriada para que o índice tenha um estado consistente. O índice é truncado imediatamente e fica vazio até que a população completa seja executada. Para obter mais informações sobre quando a alteração da lista de propriedades de pesquisa causa uma reconstrução, consulte "Comentários" posteriormente neste tópico.

    Observação
    Você pode associar uma determinada lista de propriedades de pesquisa a mais de um índice de texto completo no mesmo banco de dados.

    Para 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, consulte Pesquisar propriedades de documento com listas de propriedades de pesquisa.

Comentários

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 a população de índices de texto completo, consulte Popular índices de texto completo.

A alteração da 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. Durante o andamento da população, as consultas de texto completo na tabela base pesquisam apenas nas linhas da tabela que já foram indexadas pela população. Os dados de índice repopulados incluirão metadados das propriedades registradas da lista de propriedades de pesquisa recém-adicionada.

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

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

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

Observação
Para obter mais informações sobre como a pesquisa de texto completo trabalha com listas de propriedades de pesquisa, consulte Pesquisar propriedades de documento com listas de propriedades de pesquisa. Para obter informações sobre populações completas, consulte Popular índices de texto completo.

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

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

   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: Desativando a lista de propriedades de pesquisa e depois associando o índice a qualquer lista de propriedades de pesquisa

1. Um índice de texto completo é criado em table_1 com um spl_1 de lista de propriedades de pesquisa, seguido por uma população completa automática (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 recriaçã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.

Observação
O público recebe a permissão REFERENCES para a lista de palavras irrelevantes padrão fornecida com o SQL Server.

Exemplos

A.Definindo rastreamento manual de alterações

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

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

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

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

Observação
Para obter um exemplo que cria a lista de propriedades DocumentPropertyList, consulte CREATE SEARCH PROPERTY LIST (Transact-SQL).

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

C.Removendo uma lista de propriedades de pesquisa

O exemplo a seguir remove a lista de propriedades DocumentPropertyList do índice de texto completo na tabela Production.Document do banco de dados AdventureWorks. 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 AdventureWorks;
GO
ALTER FULLTEXT INDEX ON Production.Document 
   SET SEARCH PROPERTY LIST OFF WITH NO POPULATION; 
GO

D.Iniciando uma população completa

O exemplo a seguir inicia uma população completa no índice de texto completo na tabela JobCandidate do banco de dados AdventureWorks.

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

Consulte também

Referência

sys.fulltext_indexes (Transact-SQL)

CREATE FULLTEXT INDEX (Transact-SQL)

DROP FULLTEXT INDEX (Transact-SQL)

Conceitos

Pesquisa de texto completo (SQL Server)

Popular índices de texto completo