{"id":5502,"library":"sqlite-fts4","title":"SQLite FTS4","description":"sqlite-fts4 is a Python library providing custom SQLite functions designed for efficient full-text search (FTS4) ranking and decoding. It offers functions like `rank_score`, `rank_bm25`, `decode_matchinfo`, and `annotate_matchinfo` to enhance the utility of SQLite's built-in FTS4 extension. The library, currently at version 1.0.3, is actively maintained with a focus on stability and compatibility, addressing specific issues such as big-endian system support.","status":"active","version":"1.0.3","language":"en","source_language":"en","source_url":"https://github.com/simonw/sqlite-fts4","tags":["sqlite","fts4","search","full-text search","database","ranking"],"install":[{"cmd":"pip install sqlite-fts4","lang":"bash","label":"PyPI"},{"cmd":"conda install conda-forge::sqlite-fts4","lang":"bash","label":"Conda"}],"dependencies":[],"imports":[{"note":"Registers all custom FTS4 functions with an SQLite connection.","symbol":"register_functions","correct":"from sqlite_fts4 import register_functions"},{"note":"Imports only the rank_score function for selective registration.","symbol":"rank_score","correct":"from sqlite_fts4 import rank_score"}],"quickstart":{"code":"import sqlite3\nfrom sqlite_fts4 import register_functions\n\n# Connect to an in-memory SQLite database\nconn = sqlite3.connect(':memory:')\n\n# Register all custom FTS4 functions\nregister_functions(conn)\n\n# Create an FTS4 virtual table\nconn.execute(\"CREATE VIRTUAL TABLE docs USING fts4(title, body);\")\n\n# Insert some data\nconn.execute(\"INSERT INTO docs (title, body) VALUES (?, ?)\", (\"Hello World\", \"This is a test document with some words.\"))\nconn.execute(\"INSERT INTO docs (title, body) VALUES (?, ?)\", (\"Python SQLite FTS4\", \"Exploring full-text search capabilities in Python with SQLite FTS4.\"))\n\n# Perform a search and rank results using rank_score\n# 'pcx' is required for rank_score()\ncursor = conn.execute(\n    \"SELECT title, body, rank_score(matchinfo(docs, 'pcx')) as score FROM docs WHERE docs MATCH ? ORDER BY score DESC\",\n    (\"python search\",)\n)\n\nfor row in cursor.fetchall():\n    print(f\"Title: {row[0]}, Score: {row[2]:.2f}\")\n\nconn.close()","lang":"python","description":"This quickstart demonstrates how to establish an SQLite connection, register the `sqlite-fts4` custom functions, create an FTS4 virtual table, insert data, and then perform a full-text search with relevance ranking using `rank_score`."},"warnings":[{"fix":"Always pass the exact required `matchinfo` format string (e.g., `matchinfo(table, 'pcx')`) to `rank_score()` or `rank_bm25()`.","message":"The `rank_score()` and `rank_bm25()` functions require specific `matchinfo` format strings ('pcx' for `rank_score`, 'pcnalx' for `rank_bm25`) to return correct results. Using an incorrect format string can lead to inaccurate scores or math domain errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Sanitize user input for FTS queries, consider disabling advanced FTS operators for untrusted input, or implement a custom parser to build safe FTS queries from user-friendly input.","message":"SQLite FTS query syntax can be complex and easily lead to errors if user-provided search strings are not carefully handled. Exposing raw FTS operators to users without validation or a custom query language can result in unexpected behavior or exceptions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `MATCH` clauses are always present when `matchinfo()` is intended to be used with meaningful data, or explicitly handle the silently failing case for empty `matchinfo` buffers.","message":"Prior to version 0.5.2, calling `matchinfo()` without a `MATCH` clause in the query would raise an error. From version 0.5.2 onwards, this scenario now fails silently, which may alter behavior for applications relying on the previous error.","severity":"gotcha","affected_versions":"<0.5.2"},{"fix":"If encountering this error, ensure your Python installation uses an SQLite library compiled with FTS4. This may involve installing Python/SQLite from source or using a distribution that provides FTS4-enabled `sqlite3`.","message":"The Python `sqlite3` module must be compiled with FTS4 support in the underlying SQLite library for `sqlite-fts4` to function. If your Python environment's SQLite is not compiled with FTS4, attempts to create FTS4 tables will result in a 'no such module: fts4' error.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}