Full-Text Search

Full-text search finds documents by matching text content, ranked by BM25 relevance scoring. It supports natural language queries, exact phrase matching, and boolean operators.

Prerequisites

This guide assumes you have opened a collection and have a collection object ready.

Defining an FTS Field

To enable full-text search on a field, add a FieldSchema with an FtsIndexParam as its index_param. The field must be of type STRING.

import zvec

fts_field = zvec.FieldSchema(  
    name="content",
    data_type=zvec.DataType.STRING,
    nullable=False,
    index_param=zvec.FtsIndexParam(
        tokenizer_name="standard",   # Tokenizer to use
        filters=["lowercase"],       # Token filters applied after tokenization
    ),
)

FtsIndexParam Parameters

Performing Full-Text Search

Zvec provides two query modes for full-text search, both using the Fts object within a Query:

1. Match String — natural language input, automatically tokenized
2. Query String — advanced expression syntax with boolean operators

Match String

Use match_string for natural language queries. The input is plain text — no special syntax or escaping is needed. It is tokenized using the same tokenizer configured on the field, and tokens are combined using the default operator (OR by default).

from zvec.model.param.query import Fts, Query

result = collection.query(  
    queries=Query(
        field_name="content",
        fts=Fts(match_string="machine learning"),  
    ),
    topk=5,
)
print(result)

With the default OR operator, this returns documents containing either "machine" or "learning" (or both), ranked by BM25 relevance.

Query String

Use query_string for advanced queries with explicit boolean operators, required/excluded terms, and exact phrase matching.

from zvec.model.param.query import Fts, Query

result = collection.query(  
    queries=Query(
        field_name="content",
        fts=Fts(query_string='+learning -neural "vector search"'),  
    ),
    topk=5,
)
print(result)

This query requires "learning", excludes "neural", and matches the exact phrase "vector search".

Query Syntax Reference

The following operators are supported in query_string expressions:

Query Parameters

Default Operator

By default, adjacent bare terms in both match_string and query_string are combined with OR. To change this to AND, pass a FtsQueryParam via the param field:

import zvec
from zvec.model.param.query import Fts, Query

result = collection.query(
    queries=Query(
        field_name="content",
        fts=Fts(match_string="machine learning"),
        param=zvec.FtsQueryParam(default_operator="AND"),  
    ),
    topk=5,
)

With default_operator="AND", this returns only documents containing both "machine" and "learning".

Combining FTS with Scalar Filters

You can combine full-text search with scalar filters to narrow results:

from zvec.model.param.query import Fts, Query

result = collection.query(
    queries=Query(
        field_name="content",
        fts=Fts(match_string="machine learning"),
    ),
    filter="category = 'tech'",  
    topk=5,
)

Tokenizers

Zvec provides three built-in tokenizers. The tokenizer is configured per-field via FtsIndexParam.

Standard Tokenizer

The default tokenizer. Splits text into tokens at non-alphanumeric character boundaries and discards delimiters.

zvec.FtsIndexParam(tokenizer_name="standard", filters=["lowercase"])

Configuration (via extra_params JSON):

Whitespace Tokenizer

Splits text only on whitespace characters. Useful when punctuation should be preserved in tokens.

zvec.FtsIndexParam(tokenizer_name="whitespace", filters=["lowercase"])

Jieba Tokenizer

Chinese word segmentation tokenizer. Also handles mixed Chinese/English text.

The Python SDK bundles a default Jieba dictionary — the Jieba tokenizer works out of the box with no extra configuration. You only need to set jieba_dict_dir if you want to use a custom dictionary.

zvec.FtsIndexParam(
    tokenizer_name="jieba",
    filters=["lowercase"],
    extra_params='{"jieba_dict_dir": "/path/to/jieba/dict"}',
)

Configuration (via extra_params JSON):

Token Filters

Token filters are applied in sequence after tokenization. Currently, only one filter is available:

Constraints