Skip to main content
LanceDB provides performant full-text search based on BM25, allowing you to incorporate keyword-based search in your retrieval solutions. This page shows examples on how to create and configure FTS indexes in LanceDB OSS and Enterprise, using the synchronous and asynchronous APIs.
In LanceDB Enterprise, create_fts_index API returns immediately, but index building happens asynchronously.

​
Creating FTS Indexes

​
Synchronous API

Use create_fts_index with synchronous LanceDB connections: Check FTS index status using the API: wait_for_index(...) waits until the named FTS index exists and index_stats(...) reports num_unindexed_rows == 0. It can time out if writes keep adding rows faster than the index catches up. If a table has multiple FTS indexes, specify the target text column when querying instead of relying on implicit selection.

​
Asynchronous API

When using async connections (connect_async), use create_index with the FTS configuration:
The create_fts_index method is not available on AsyncTable. Use create_index with FTS config instead.

​
Nested field paths

FTS indexes can target text leaves inside struct columns by passing a dotted path (for example, payload.text). The same path works for MatchQuery and PhraseQuery, and for the columns argument on async nearest_to_text queries. You can point an index at any string leaf nested in a struct, regardless of depth. The struct container itself isn’t indexable: you have to name a specific text field. LanceDB rejects paths that don’t resolve to a text leaf:
  • A struct container (for example, payload): raises ValueError: FTS index cannot be created ....
  • A non-text leaf such as an integer or float (for example, payload.count): raises the same error.
  • A path that doesn’t exist in the schema (for example, payload.missing): raises ValueError: Field path ... not found.
The async API accepts the same dotted paths through create_index:
Python
from lancedb.index import FTS

await async_table.create_index("payload.text", config=FTS(with_position=True))

​
Configuration Options

​
FTS Parameters

ParameterTypeDefaultDescription
with_positionboolFalseStore token positions (required for phrase queries)
base_tokenizerstr"simple"Text splitting method (simple, whitespace, raw, ngram, icu, jieba/*, or lindera/*)
languagestr"English"Language for stemming and stop-word filters. Choose CJK and mixed-language segmentation with base_tokenizer.
max_token_lengthint40Maximum token size; longer tokens are omitted
lower_caseboolTrueLowercase tokens
stemboolTrueApply stemming (running → run)
remove_stop_wordsboolTrueDrop common stop words
ascii_foldingboolTrueNormalize accented characters
custom_stop_wordslist[str]NoneExtra stop words to drop in addition to the language defaults. Requires remove_stop_words=True.
ngram_min_lengthint3Minimum n-gram length. Applies only when base_tokenizer="ngram".
ngram_max_lengthint3Maximum n-gram length. Applies only when base_tokenizer="ngram".
prefix_onlyboolFalseIndex only prefix n-grams rather than all substrings. Applies only when base_tokenizer="ngram".
  • max_token_length can filter out base64 blobs or long URLs.
  • Disabling with_position reduces index size but disables phrase queries.
  • ascii_folding helps with international text (e.g., “café” → “cafe”).

​
Tokenizer choices

base_tokenizer controls segmentation before token filters run:
  • simple, whitespace, and raw cover common tokenization strategies for space-delimited text.
  • ngram indexes overlapping character spans for substring-style matching.
  • icu uses bundled ICU4X word segmentation for mixed-language text and scripts where whitespace splitting is not enough. ICU stands for International Components for Unicode, and this tokenizer does not need external model files.
  • jieba/* is for Chinese word segmentation with Jieba.
  • lindera/* loads a compiled Lindera dictionary, such as lindera/ipadic for Japanese or lindera/ko-dic for Korean.
Model-backed tokenizers such as jieba/default, lindera/ipadic, and lindera/ko-dic require tokenizer model files in Lance’s language model home. Lance looks under the default platform data directory for lance/language_models, or you can set LANCE_LANGUAGE_MODEL_HOME to point to another model root. For example, jieba/default is resolved under <model-home>/jieba/default/.... language is used by token filters, not by the base tokenizer. Stemming supports Arabic, Danish, Dutch, English, Finnish, French, German, Greek, Hungarian, Italian, Norwegian, Portuguese, Romanian, Russian, Spanish, Swedish, Tamil, and Turkish. Built-in stop-word removal supports Danish, Dutch, English, Finnish, French, German, Hungarian, Italian, Norwegian, Portuguese, Russian, Spanish, and Swedish. For other stemming languages, set remove_stop_words=False or pass custom_stop_words.

​
Phrase Query Configuration

Enable phrase queries by setting:
ParameterRequired ValuePurpose
with_positionTrueTrack token positions for phrase matching
remove_stop_wordsFalsePreserve stop words for exact phrase matching

​
Indexing nested string fields

You can build an FTS index on a string field inside a struct by passing its full dotted path, like nested.text. The same path is used when you query the index through fts_columns, and the indexed column is reported back as the full path from list_indices(). 
# Schema: pa.struct([pa.field("text", pa.string())]) stored under the `nested` column.
table.create_fts_index("nested.text")

results = (
    table.search("puppy", query_type="fts", fts_columns="nested.text")
    .limit(5)
    .to_list()
)
Use the canonical Lance path: dot-separate each struct field from root to leaf (for example, metadata.author.name). The same convention applies to scalar and vector indexes.