Customize filters and word breakers

Applies to: SQL Server

This article describes how to view and customize Full-Text Search filters, word breakers, and stemmers on a SQL Server instance.

Note

Customization is disallowed for Azure SQL Database or Azure SQL Managed Instance, because access to the Windows registry or host filesystem is restricted.

The customization process differs based on the full-text index version.

Full-text index version 1 uses Windows registry-based component registration. Instance-specific component registration is stored under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRoot>\MSSearch, which is divided into Filters, Language, and CLSID subkeys. When you set load_os_resources to 1 via sp_fulltext_service, Full-Text Search falls back to searching HKEY_CLASSES_ROOT for extensions and LCIDs missing from the instance registration. For details, see Customize version 1 filters and word breakers.
Full-text index version 2 simplifies the customization process. Instead of reading the Windows registry, you can provide an optional version_overrides.json file per instance. For details, see Customize version 2 filters and word breakers.

To check the version used by a full-text index, query the index_version column in sys.fulltext_indexes. To control the version used when creating or rebuilding indexes, use the FULLTEXT_INDEX_VERSION database scoped configuration.

View registered components

For a conceptual overview, see Configure and manage filters and Configure and manage word breakers and stemmers.

To view all linguistic components, run sp_help_fulltext_system_components with the all argument:

EXECUTE sp_help_fulltext_system_components 'all';

Note

sp_help_fulltext_system_components reports registered components for the full-text index version specified via the FULLTEXT_INDEX_VERSION database scoped configuration.

Customize version 2 filters and word breakers

Applies to: SQL Server 2025 (17.x) and later versions.

Version 2 full-text indexes don't read the Windows registry. Follow the steps in this section to customize version 2 word breakers, stemmers, and filters.

The default full-text index version in SQL Server 2025 (17.x) and later versions is version 2. The default DLL files for version 2 are located in the C:\Program Files\Microsoft SQL Server\MSSQL17.<instance-name>\MSSQL\Binn\ftcomponents\[filters|wordbreakers] directory.
To override a default or add a new component, create a version_overrides.json file inside the C:\Program Files\Microsoft SQL Server\MSSQL17.<instance-name>\MSSQL\FTData directory.
To add or replace the word breaker, update the languages section in the JSON file. For filters, update the doctypes section.

Sample JSON structure:
```
{
   "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>": [{ ... }],
      }
}
```
Consider the following rules for the version_overrides.json file:
- All fields in the JSON file are mandatory except stemmerClsid (optional).
- Locale name can be any BCP 47 locale name, following standard locale names.
- When duplicate entries exist for the same language and version, or extension and version, the most recent entry takes precedence.
- Handler DLL can be a relative path to the file in relation to the C:\Program Files\Microsoft SQL Server\MSSQL17.<instance-name>\MSSQL\Binn\ftcomponents\[filters|wordbreakers] directory where default binaries are located. It can also be an absolute path. For example, the following JSON file enables support for indexing PDFs via the built-in Windows PDF filter:
```
{
   "doctypes": {
      ".pdf": [
         {
            "version": 2,
            "handler": "%SystemRoot%\\system32\\windows.data.pdf.dll",
            "clsid": "6C337B26-3E38-4F98-813B-FBA18BAB64F5"
         }
      ]
   }
}
```
Important

You should load only signed and verified components. Configure the correct access control lists (ACLs) on DLL files and folders containing them. Also, you should run the FDHOST Launcher (MSSQLFDLauncher) Service with the least possible privileges.
Use sp_fulltext_service to update the internal list of languages and document types for accurate DMV reporting:
```
EXECUTE sp_fulltext_service 'update_languages';
```
Restart the filter daemon host processes (fdhost.exe) for the overrides to take effect for future queries and populations:
```
EXECUTE sp_fulltext_service 'restart_all_fdhosts';
```

Example: Support a custom document extension

Scenario: You want to add support for indexing files with your own custom extension, such as .myextension.

Find the existing installed filter handler for the associated document class via sys.fulltext_document_types or sp_help_fulltext_system_components 'filter'. For plaintext, for example:
```
ALTER DATABASE SCOPED CONFIGURATION
    SET FULLTEXT_INDEX_VERSION = 1;
GO

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

Create or update version_overrides.json in the FTData directory with the preceding class_id and path. In this case:

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

Refresh the registered component list and restart the filter daemon host processes:

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

Example: Install a third-party filter (Foxit PDF IFilter)

Follow the third-party installation documentation. For Foxit PDF IFilter, see How to Download the IFilter Addon for Foxit PDF Editor.

Installers usually write registration information into HKCR and place binaries under Program Files.

Create or update version_overrides.json in the FTData directory:

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

Refresh the registered component list and restart the filter daemon host processes:

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

Find the CLSID

The easiest way to find the CLSID, if it isn't publicly documented, is to query the DMVs or sp_help_fulltext_system_components with FULLTEXT_INDEX_VERSION = 1, or from an older SQL Server instance.

You can also check affected registry keys. A PDF filter install, for example, updates HKCR\.pdf\PersistentHandler. You can then take that PH CLSID and find the component CLSID as HKEY_CLASSES_ROOT\CLSID\{PH CLSID}\PersistentAddinsRegistered\{Component CLSID}.

Customize version 1 filters and word breakers

Applies to: SQL Server 2025 (17.x) and prior versions.

Version 1 full-text indexes use the Windows registry to resolve filters, word breakers, and stemmers. This applies to SQL Server 2025 (17.x) indexes that still use index_version = 1, and to full-text indexes in earlier SQL Server versions.

Version 1 component lookup uses this order:

Instance-specific registration under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRoot>\MSSearch\Filters for matching extensions and HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRoot>\MSSearch\Languages for matching LCIDs.
System registration under HKEY_CLASSES_ROOT (HKCR), if operating-system resource loading is enabled via sp_fulltext_service 'load_os_resources'.

Instance-specific registration has priority. Modify it when you want a SQL Server instance to use a component that differs from the operating-system registration or other installed instances.

Install and load version 1 components

Before you install a DLL file that contains new word breakers or filters, make sure that it has a different filename from any of the existing DLL files installed on your server instance.
Copy the new DLL file into the directory containing the standard SQL Server DLL files for the server instance. The default location is:
```
C:\Program Files\Microsoft SQL Server\MSSQL.<instance_name>\MSSQL\Binn
```
Install the new word breaker or filters following their documentation.
Use sp_fulltext_service to load newly installed word breakers and filters in the server instance, as follows:
```
EXECUTE sp_fulltext_service
    @action = 'load_os_resources',
    @value = 1;
```
Use sp_fulltext_service to update the list of languages, as follows:
```
EXECUTE sp_fulltext_service 'update_languages';
```
Restart the filter daemon host processes (fdhost.exe), using sp_fulltext_service as follows:
```
EXECUTE sp_fulltext_service 'restart_all_fdhosts';
```

Example: Support a custom document extension

Scenario: You want to add support for indexing files with your own custom extension, such as .myextension, by using an existing installed filter.

Find the CLSID for the filter you want to reuse. For example, to reuse the plaintext filter, inspect the .txt registration with version 1 component reporting:
```
ALTER DATABASE SCOPED CONFIGURATION
    SET FULLTEXT_INDEX_VERSION = 1;
GO

SELECT *
FROM sys.fulltext_document_types
WHERE document_type = '.txt';
```
Add instance-specific registry entries for the new extension. The extension entry maps .myextension to the filter CLSID, and the CLSID entry maps that CLSID to the filter DLL.

The following example uses the legacy plaintext filter CLSID and 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
```
Replace <InstanceRoot> with the SQL Server instance root, such as MSSQL16.MSSQLSERVER.

Refresh the registered component list and restart the filter daemon host processes:

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

Example: Install a third-party filter (Foxit PDF IFilter)

Scenario: You want version 1 full-text indexes to use a third-party PDF IFilter that registers itself with Windows.

Follow the third-party installation documentation. For Foxit PDF IFilter, see How to Download the IFilter Addon for Foxit PDF Editor.
Enable operating-system resource loading so version 1 component lookup can fall back to HKCR when the SQL Server instance doesn't have an instance-specific registration for .pdf:
```
EXECUTE sp_fulltext_service
    @action = 'load_os_resources',
    @value = 1;
```

Refresh the registered component list and restart the filter daemon host processes:

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

If you don't want to rely on the HKCR fallback, add instance-specific MSSearch\Filters and MSSearch\CLSID entries for .pdf instead. The instance-specific entries take priority over system registration.

Feedback

Was this page helpful?

Last updated on 2026-07-21

Customize filters and word breakers

View registered components

Customize version 2 filters and word breakers

Example: Support a custom document extension

Example: Install a third-party filter (Foxit PDF IFilter)

Find the CLSID

Customize version 1 filters and word breakers

Install and load version 1 components

Example: Support a custom document extension

Example: Install a third-party filter (Foxit PDF IFilter)

Related content

Feedback

Additional resources