Personalizar filtros e separadores de palavras

Aplica-se a:SQL Server

Este artigo descreve como visualizar e personalizar filtros de Pesquisa de Texto Completo, separadores de palavras e stemmers em uma instância do SQL Server.

Observação

A personalização é proibida para Banco de Dados SQL do Azure ou Instância Gerenciada de SQL do Azure, porque o acesso ao registro do Windows ou ao sistema de arquivos do host é restrito.

O processo de personalização difere com base na versão de índice de texto completo.

Índice de Texto Completo versão 1 usa o registro de componentes baseado no Registro do Windows. O registro de componente específico da instância é armazenado em HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRoot>\MSSearch, que é dividido em Filters, Languagee CLSID subchaves. Quando você define load_os_resources como 1 por meio de sp_fulltext_service, a Pesquisa de Texto Completo passa a pesquisar HKEY_CLASSES_ROOT em busca de extensões e LCIDs ausentes no registro da instância. Para obter detalhes, consulte Personalizar filtros e separadores de palavras da versão 1.
O índice de texto completo versão 2 simplifica o processo de personalização. Em vez de ler o registro Windows, você pode fornecer um arquivo opcional version_overrides.json por instância. Para obter detalhes, consulte Personalizar filtros e separadores de palavras da versão 2.

Para verificar a versão usada por um índice de texto completo, consulte a index_version coluna em sys.fulltext_indexes. Para controlar a versão usada ao criar ou recriar índices, use a configuração com escopo de banco de dados FULLTEXT_INDEX_VERSION.

Exibir componentes registrados

Para uma visão geral conceitual, consulte Configurar e gerenciar filtros e Configurar e gerenciar separadores de palavras e stemmers.

Para exibir todos os componentes linguísticos, execute sp_help_fulltext_system_components com o all argumento:

EXECUTE sp_help_fulltext_system_components 'all';

Observação

sp_help_fulltext_system_components exibe os componentes registrados para a versão do índice de texto completo especificada por meio da FULLTEXT_INDEX_VERSION configuração com escopo de banco de dados.

Personalizar filtros e separadores de palavras da versão 2

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

Os índices de texto completo da versão 2 não leem o registro Windows. Siga as etapas desta seção para personalizar separadores de palavras, stemmers e filtros da versão 2.

A versão padrão do índice de texto completo no SQL Server 2025 (17.x) e versões posteriores é a versão 2. Os arquivos DLL padrão da versão 2 estão localizados no C:\Program Files\Microsoft SQL Server\MSSQL17.<instance-name>\MSSQL\Binn\ftcomponents\[filters|wordbreakers] diretório.
Para sobrescrever um padrão ou adicionar um novo componente, crie um version_overrides.json arquivo dentro do C:\Program Files\Microsoft SQL Server\MSSQL17.<instance-name>\MSSQL\FTData diretório.
Para adicionar ou substituir o separador de palavras, atualize a languages seção no arquivo JSON. Para filtros, atualize a doctypes seção.

Estrutura JSON de exemplo:
```
{
   "languages": {
         "en": [{
            "version": 2,
            "handler": "MSWB7.dll",
            "wbClsid": "9faed859-0b30-4434-ae65-412e14a16fb8",
            "stemmerClsid": "e1e5ef84-c4a6-4e50-8188-99aef3de2659"
         }],
         "<BCP 47 locale name>": [{ ... }],
      }

   "doctypes": {
         ".html": [{
            "version": 2,
            "handler": "nlhtml.dll",
            "clsid": "e0ca5340-4534-11cf-b952-00aa0051fe20"
         }],
         ".<extension 2>": [{ ... }],
      }
}
```
Considere as seguintes regras para o version_overrides.json arquivo:
- Todos os campos no arquivo JSON são obrigatórios, exceto stemmerClsid (opcional).
- O nome da localidade pode ser qualquer nome de localidade BCP 47, seguindo os nomes de localidade padrão.
- Quando existem entradas duplicadas para o mesmo idioma e versão, ou extensão e versão, a entrada mais recente tem precedência.
- A DLL do manipulador pode ser um caminho relativo para o arquivo em relação ao C:\Program Files\Microsoft SQL Server\MSSQL17.<instance-name>\MSSQL\Binn\ftcomponents\[filters|wordbreakers] diretório em que os binários padrão estão localizados. Também pode ser um caminho absoluto. Por exemplo, o arquivo JSON a seguir habilita o suporte para indexação de PDFs por meio do filtro PDF Windows interno:
```
{
   "doctypes": {
      ".pdf": [
         {
            "version": 2,
            "handler": "%SystemRoot%\\system32\\windows.data.pdf.dll",
            "clsid": "6C337B26-3E38-4F98-813B-FBA18BAB64F5"
         }
      ]
   }
}
```
Importante

Você deve carregar apenas componentes assinados e verificados. Configure as listas de controle de acesso (ACLs) corretas nos arquivos de biblioteca DLL e nas pastas que os contêm. Além disso, você deve executar o Serviço de Inicializador FDHOST (MSSQLFDLauncher) com os privilégios menos possíveis.
Use sp_fulltext_service para atualizar a lista interna de idiomas e tipos de documento para relatórios de DMV precisos:
```
EXECUTE sp_fulltext_service 'update_languages';
```
Reinicie os processos do daemon de filtro (fdhost.exe) para que as substituições entrem em vigor em consultas e populações futuras:
```
EXECUTE sp_fulltext_service 'restart_all_fdhosts';
```

Exemplo: dar suporte a uma extensão de documento personalizada

Cenário: Você quer adicionar suporte à indexação de arquivos com uma extensão personalizada própria, como .myextension.

Localize o manipulador de filtro instalado existente para a classe de documento associada por meio sys.fulltext_document_types ou sp_help_fulltext_system_components 'filter'. Para texto sem formatação, por exemplo:
```
ALTER DATABASE SCOPED CONFIGURATION
    SET FULLTEXT_INDEX_VERSION = 1;
GO

SELECT *
FROM sys.fulltext_document_types
WHERE document_type = '.txt';
```

Criar ou atualizar version_overrides.json no diretório FTData usando os class_id e path anteriores. Nesse caso:

{
   "doctypes": {
      ".myextension": [
         {
            "version": 2,
            "handler": "%SystemRoot%\\system32\\query.dll",
            "clsid": "C1243CA0-BF96-11CD-B579-08002B30BFEB"
         }
      ]
   }
}

Atualize a lista de componentes registrados e reinicie os processos host do daemon de filtro:

EXECUTE sp_fulltext_service 'update_languages';
EXECUTE sp_fulltext_service 'restart_all_fdhosts';

Exemplo: instalar um filtro de terceiros (Foxit PDF IFilter)

Siga a documentação de instalação de terceiros. Para o Foxit PDF IFilter, consulte Como baixar o IFilter Addon para o Foxit PDF Editor.

Os instaladores geralmente gravam informações de registro em HKCR e instalam binários em Program Files.

Criar ou atualizar version_overrides.json no FTData diretório:

{
   "doctypes": {
      ".pdf": [
         {
            "version": 2,
            "handler": "C:\\Program Files\\Foxit Software\\Foxit PDF IFilter\\PDFFilt.dll",
            "clsid": "987f8d1a-26e6-4554-b007-6b20e2680632"
         }
      ]
   }
}

Atualize a lista de componentes registrados e reinicie os processos host do daemon de filtro:

EXECUTE sp_fulltext_service 'update_languages';
EXECUTE sp_fulltext_service 'restart_all_fdhosts';

Encontre o CLSID

A maneira mais fácil de encontrar o CLSID, se ele não estiver documentado publicamente, é consultar as DMVs ou sp_help_fulltext_system_components com FULLTEXT_INDEX_VERSION = 1, ou obtê-lo em uma instância mais antiga do SQL Server.

Você também pode verificar as chaves do Registro afetadas. Uma instalação de filtro PDF, por exemplo, atualiza HKCR\.pdf\PersistentHandler. Você pode então usar esse CLSID do PH para encontrar o CLSID do componente como HKEY_CLASSES_ROOT\CLSID\{PH CLSID}\PersistentAddinsRegistered\{Component CLSID}.

Personalizar filtros e separadores de palavras da versão 1

Aplica-se a: SQL Server 2025 (17.x) e versões anteriores.

Os índices de texto completo da versão 1 usam o registro do Windows para resolver filtros, separadores de palavras e stemmers. Isso se aplica a índices SQL Server 2025 (17.x) que ainda usam index_version = 1e a índices de texto completo em versões de SQL Server anteriores.

A pesquisa de componentes da versão 1 usa esta ordem:

Registro específico da instância em HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRoot>\MSSearch\Filters para correspondência de extensões e HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRoot>\MSSearch\Languages para correspondência de LCIDs.
Registro do sistema em HKEY_CLASSES_ROOT (HKCR), se o carregamento de recursos do sistema operacional estiver habilitado via sp_fulltext_service 'load_os_resources'.

O registro específico da instância tem prioridade. Modifique-o quando quiser que uma instância de SQL Server use um componente que difere do registro do sistema operacional ou de outras instâncias instaladas.

Instalar e carregar componentes da versão 1

Antes de instalar um arquivo DLL que contém novos separadores de palavras ou filtros, verifique se ele tem um nome de arquivo diferente de qualquer um dos arquivos DLL existentes instalados na instância do servidor.
Copie o novo arquivo DLL no diretório que contém os arquivos DLL padrão do SQL Server para a instância de servidor. O local padrão é:
```
C:\Program Files\Microsoft SQL Server\MSSQL.<instance_name>\MSSQL\Binn
```
Instale o novo quebrador de palavras ou os filtros de acordo com a documentação.
Use sp_fulltext_service para carregar os separadores de palavras e filtros recém-instalados na instância de servidor, da seguinte maneira:
```
EXECUTE sp_fulltext_service
    @action = 'load_os_resources',
    @value = 1;
```
Use sp_fulltext_service para atualizar a lista de idiomas, da seguinte maneira:
```
EXECUTE sp_fulltext_service 'update_languages';
```
Reinicie os processos do host daemon do filtro (fdhost.exe), usando sp_fulltext_service da seguinte forma:
```
EXECUTE sp_fulltext_service 'restart_all_fdhosts';
```

Exemplo: dar suporte a uma extensão de documento personalizada

Cenário: Você quer adicionar suporte para indexação de arquivos com sua própria extensão personalizada, como .myextension, usando um filtro já instalado.

Localize o CLSID para o filtro que você deseja reutilizar. Por exemplo, para reutilizar o filtro de texto simples, inspecione o registro .txt com o relatório de componentes da versão 1:
```
ALTER DATABASE SCOPED CONFIGURATION
    SET FULLTEXT_INDEX_VERSION = 1;
GO

SELECT *
FROM sys.fulltext_document_types
WHERE document_type = '.txt';
```
Adicione entradas de registro específicas de instância para a nova extensão. A entrada de extensão mapeia .myextension para o CLSID do filtro e a entrada CLSID mapeia esse CLSID para a DLL do filtro.

O exemplo a seguir usa o filtro de texto simples legado CLSID e msfte.dll:
```
reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRoot>\MSSearch\Filters\.myextension" /ve /t REG_SZ /d "{C7310720-AC80-11D1-8DF3-00C04FB6EF4F}" /f
```
Substitua <InstanceRoot> pela raiz da instância SQL Server, como MSSQL16.MSSQLSERVER.

Atualize a lista de componentes registrados e reinicie os processos host do daemon de filtro:

EXECUTE sp_fulltext_service 'update_languages';
EXECUTE sp_fulltext_service 'restart_all_fdhosts';

Exemplo: instalar um filtro de terceiros (Foxit PDF IFilter)

Cenário: você deseja que os índices de texto completo da versão 1 usem um IFilter PDF de terceiros que se registre com Windows.

Siga a documentação de instalação de terceiros. Para o Foxit PDF IFilter, consulte Como baixar o IFilter Addon para o Foxit PDF Editor.
Habilite o carregamento de recursos do sistema operacional para que a pesquisa de componentes da versão 1 possa recorrer a HKCR quando a instância do SQL Server não tiver um registro específico da instância para .pdf:
```
EXECUTE sp_fulltext_service
    @action = 'load_os_resources',
    @value = 1;
```

Atualize a lista de componentes registrados e reinicie os processos host do daemon de filtro:

EXECUTE sp_fulltext_service 'update_languages';
EXECUTE sp_fulltext_service 'restart_all_fdhosts';

Se você não quiser depender do fallback HKCR, adicione entradas específicas da instância MSSearch\Filters e MSSearch\CLSID para .pdf. As entradas específicas da instância têm prioridade sobre o registro do sistema.

Comentários

Esta página foi útil?

Last updated on 2026-07-21

Personalizar filtros e separadores de palavras

Exibir componentes registrados

Personalizar filtros e separadores de palavras da versão 2

Exemplo: dar suporte a uma extensão de documento personalizada

Exemplo: instalar um filtro de terceiros (Foxit PDF IFilter)

Encontre o CLSID

Personalizar filtros e separadores de palavras da versão 1

Instalar e carregar componentes da versão 1

Exemplo: dar suporte a uma extensão de documento personalizada

Exemplo: instalar um filtro de terceiros (Foxit PDF IFilter)

Conteúdo relacionado

Comentários

Recursos adicionais