TreeSearch Rust Library and CLI
rtreesearch is a fast, structure-aware document search library and optional CLI built with Rust.
It indexes files into a local SQLite FTS5 database and searches by document
structure instead of chunking text into arbitrary fragments.
The default features preserve the complete ts executable. Embedding applications
can disable defaults and compile only the parsers they actually use.
Library embedding
For an application that constructs authorized documents itself and only parses Markdown/plain text, use the dependency-minimal profile:
= { = "rtreesearch", = "1.1.2", = false, = ["parser-markdown", "parser-plaintext"] }
This profile keeps the in-memory flat/tree ranking engine, document model,
Markdown hierarchy, plain-text hierarchy, scorer, and dependency-free CJK
bigram/character tokenizers. The host supplies its authorized candidate scores
to engine::candidate_search::search_with_scores_strict; TreeSearch performs
mode routing, traversal, path aggregation, and final ranking. It does not
compile SQLite/FTS5, the CLI, directory crawler, progress rendering, output
formatters, HTML/config/code parsers, or jieba.
Available opt-in features:
| Feature | Capability |
|---|---|
cli (default) |
Full backward-compatible ts binary and all built-ins |
directory-indexer |
.gitignore-aware parallel directory crawling |
progress |
Indexing progress bars |
output |
JSON/plain/TTY renderers |
sqlite-fts |
Optional rusqlite/libsqlite3-sys adapter linked to a host/system SQLite |
sqlite-bundled |
sqlite-fts plus a bundled SQLite build; used by the default CLI |
cjk-jieba |
Jieba segmentation and custom dictionaries |
parser-markdown |
Markdown heading hierarchy |
parser-plaintext |
Plain-text paragraph hierarchy |
parser-html |
Browser-grade HTML parsing |
parser-config |
JSON, YAML, and TOML parsing |
parser-code |
Source-code structure parsing |
parsers-all |
Every built-in parser |
ParserRegistry::empty() plus ParserRegistry::register() lets a host add
domain-specific parsers without enabling unrelated built-ins.
The default cli feature includes sqlite-bundled, so existing CLI installs
remain self-contained. Library consumers should make an explicit choice:
- omit both SQLite features for pure in-memory candidate reranking;
- enable
sqlite-ftsto share the host/systemsqlite3link; - enable
sqlite-bundledonly for a self-contained SQLite build.
The minimal Markdown/plain-text profile contains neither rusqlite nor
libsqlite3-sys. rusqlite 0.37 and SQLx 0.9 both resolve
libsqlite3-sys 0.35, but disabling TreeSearch's SQLite adapter is still the
recommended choice when the host does not use local FTS5.
Candidate-search API
Hosts that already perform authorization and candidate retrieval should use the strict API:
use ;
use ;
let mut config = default;
config.search_mode = Auto;
let outcome = search_with_candidates_strict?;
Strict search rejects empty queries, duplicate document/node identities,
unknown candidates, non-finite/out-of-range scores, invalid source ranges, and
invalid frontier thresholds. Scores must be globally calibrated in 0.0..=1.0.
The lenient API ignores invalid candidates and, when raw positive scores exceed
1.0, divides the accepted set by its global maximum without destroying
cross-document ordering.
All result ordering has explicit (score, doc_id, node_id) tie-breaks.
top_k_docs limits distinct returned documents and max_nodes_per_doc limits
nodes from each selected document. Tree paths report the actual retrieval
anchor and UTF-8-safe snippets. See API.md for the full contract.
Resource policies are active rather than documentary: max_concurrency builds
a request-local Rayon pool for directory parsing, max_node_chars bounds text
examined by scoring/FTS indexing, and max_result_chars bounds returned node
text on UTF-8 character boundaries. SQLite transfers at most 5,000 raw matches
into memory before bounded TreeSearch reranking.
Install
Homebrew (macOS / Linux)
Cargo
Prebuilt binaries
Download from GitHub Releases:
- Linux:
x86_64-unknown-linux-gnu - macOS Intel:
x86_64-apple-darwin - macOS Apple Silicon:
aarch64-apple-darwin - Windows:
x86_64-pc-windows-msvc
Release page: https://github.com/shibing624/TreeSearch/releases
Why TreeSearch
- No embeddings
- No vector database
- No chunk splitting
- SQLite FTS5 with persistent local indexes
- Structure-aware retrieval for Markdown, text, code, HTML, and more
Quick Start
Search the current directory with the default auto mode:
Build the index explicitly:
Inspect index stats:
Wildcard Queries
ts supports a narrow set of wildcard shortcuts:
auth*: prefix match*auth*: contains-style regex match- other wildcard shapes currently fall back to regular query parsing
For explicit control:
ts --regex "o?auth" .treats the query as a raw regexts search --regex "o?auth"runs indexed search in regex modets --fts-expression "auth*" .passes a raw FTS5 expressionts search --fts-expression "auth*"runs indexed search with raw FTS5 syntax- Invalid regex patterns raise an explicit error instead of silently returning no results
Examples:
Search Modes
ts supports three search modes:
auto: default mode, automatically selectsflatortreeflat: force FTS-style flat retrievaltree: force tree traversal retrieval
Examples:
In auto mode, TreeSearch uses the same three-layer decision logic as the
Python version:
- Source type mapping: file types that benefit from tree search are marked explicitly.
- Depth verification: only documents with real structure depth are treated as hierarchical.
- Ratio threshold: if enough indexed documents benefit from tree mode, use
tree; otherwise useflat.
Commands
ts [OPTIONS] [QUERY] [PATH]
ts search <QUERY> [PATH]
ts index [PATH]
ts stats [PATH]
Useful options:
--mode auto|flat|tree--format tty|json|plain--json--follow-n, --max-results <N>
Output Formats
tty: colored terminal outputjson: machine-readable JSON outputplain: plain text output
Documentation
- Project homepage: https://github.com/DDGRCF/TreeSearch
- API docs: https://docs.rs/treesearch
- Embedding contract: API.md
License
Apache-2.0