lucisearch 0.4.0

An embeddable, in-process search engine written in Rust

lucisearch

The SQLite of Search — an embeddable, in-process search engine.

No cluster to manage. No HTTP layer. No JVM. pip install and search.

pip install lucisearch

Quick Start

import luci

# Create an index with field mappings
index = luci.Index.create("products.luci", {
    "properties": {
        "title": {"type": "text"},
        "description": {"type": "text"},
        "category": {"type": "keyword"},
        "price": {"type": "float"},
        "in_stock": {"type": "boolean"},
    }
})

# Index documents
index.bulk([
    {"title": "Wireless Headphones", "description": "Noise-cancelling bluetooth headphones", "category": "electronics", "price": 79.99, "in_stock": True},
    {"title": "Running Shoes", "description": "Lightweight trail running shoes", "category": "sports", "price": 129.99, "in_stock": True},
    {"title": "Coffee Maker", "description": "Programmable drip coffee maker", "category": "kitchen", "price": 49.99, "in_stock": False},
])

# Search
results = index.search({"match": {"title": "headphones"}}, 10)
for hit in results["hits"]:
    print(f'{hit["_score"]:.2f}  {hit["_source"]["title"]}')

Queries

Luci supports the Elasticsearch query DSL. Pass any query as a Python dict.

Full-text search

# Single field
index.search({"match": {"title": "running shoes"}}, 10)

# Multiple fields
index.search({"multi_match": {"query": "wireless", "fields": ["title", "description"]}}, 10)

# Exact phrase
index.search({"match_phrase": {"description": "trail running"}}, 10)

Filtering and boolean logic

# Term query (exact match on keyword fields)
index.search({"term": {"category": "electronics"}}, 10)

# Bool query — combine must, should, must_not, filter
index.search({
    "bool": {
        "must": [{"match": {"title": "shoes"}}],
        "filter": [
            {"term": {"in_stock": True}},
            {"range": {"price": {"lte": 100}}},
        ]
    }
}, 10)

# Prefix, wildcard, regexp, fuzzy
index.search({"prefix": {"category": "elec"}}, 10)
index.search({"fuzzy": {"title": {"value": "headphoens", "fuzziness": 1}}}, 10)

Sorting and pagination

# Sort by field
results = index.search({
    "query": {"match_all": {}},
    "sort": [{"price": "asc"}],
    "size": 10
})

# Pagination with from/size
results = index.search({
    "query": {"match_all": {}},
    "sort": ["price"],
    "from": 20,
    "size": 10
})

# Cursor-based pagination with search_after
results = index.search({
    "query": {"match_all": {}},
    "sort": ["price"],
    "size": 10,
    "search_after": [49.99]
})

Aggregations

# Terms aggregation
results = index.search({
    "query": {"match_all": {}},
    "aggs": {"categories": {"terms": {"field": "category"}}},
    "size": 0
})
for bucket in results["aggregations"]["categories"]["buckets"]:
    print(f'{bucket["key"]}: {bucket["doc_count"]}')

# Metric aggregations
results = index.search({
    "query": {"match_all": {}},
    "aggs": {
        "avg_price": {"avg": {"field": "price"}},
        "price_stats": {"stats": {"field": "price"}},
        "price_ranges": {"range": {
            "field": "price",
            "ranges": [{"to": 50}, {"from": 50, "to": 100}, {"from": 100}]
        }},
    },
    "size": 0
})

# Nested aggregations
results = index.search({
    "query": {"match_all": {}},
    "aggs": {"by_category": {
        "terms": {"field": "category"},
        "aggs": {"avg_price": {"avg": {"field": "price"}}},
    }},
    "size": 0
})

Highlighting

results = index.search({
    "query": {"match": {"description": "coffee"}},
    "highlight": {
        "fields": {"description": {}},
        "pre_tags": ["<b>"],
        "post_tags": ["</b>"],
    }
})
for hit in results["hits"]:
    print(hit.get("highlight", {}))

Vector search (kNN)

# Create index with vector field
index = luci.Index.create("vectors.luci", {
    "properties": {
        "title": {"type": "text"},
        "embedding": {"type": "dense_vector", "dims": 384},
    }
})

# kNN search
results = index.search({
    "knn": {
        "field": "embedding",
        "query_vector": [0.1, 0.2, ...],  # 384-dim vector
        "k": 10,
        "num_candidates": 50,
    }
}, 10)

# Hybrid search — text + vector combined via RRF
results = index.search({
    "query": {"match": {"title": "headphones"}},
    "knn": {
        "field": "embedding",
        "query_vector": query_vector,
        "k": 10,
        "num_candidates": 50,
    }
}, 10)

Geospatial queries

# Create index with geo fields
index = luci.Index.create("places.luci", {
    "properties": {
        "name": {"type": "text"},
        "location": {"type": "geo_point"},
    }
})

# Geo distance
index.search({
    "geo_distance": {
        "distance": "10km",
        "location": {"lat": 40.7128, "lon": -74.0060}
    }
}, 10)

# Geo bounding box
index.search({
    "geo_bounding_box": {
        "location": {
            "top_left": {"lat": 41.0, "lon": -74.5},
            "bottom_right": {"lat": 40.5, "lon": -73.5}
        }
    }
}, 10)

Document CRUD

# Add with explicit ID
index.add({"_id": "prod-1", "title": "Widget", "price": 9.99})

# Get by ID
doc = index.get("prod-1")

# Update (partial merge)
index.update("prod-1", {"price": 7.99})

# Delete by ID
index.delete("prod-1")

# Delete by query
index.delete_by_query({"term": {"category": "discontinued"}})

# Count
count = index.count({"term": {"in_stock": True}})

Field Types

Type	Description
text	Full-text search with BM25 scoring and analysis
keyword	Exact match, sorting, aggregations
integer, long	Signed integers
float, double	Floating point numbers
boolean	true / false
date	Date/time values
dense_vector	Fixed-dimension float vectors (cosine, L2, dot product; int8 quantization)
geo_point	Latitude/longitude pairs
geo_shape	Polygons, multipolygons with spatial relations
nested	Arrays of objects with independent field scoping

Features

• Full-text search with BM25 scoring, analyzers, phrase queries, fuzzy matching
• Vector search with HNSW, int8 quantization, pre-filtering
• Hybrid search with Reciprocal Rank Fusion (RRF)
• 20+ aggregation types — terms, avg, sum, min, max, stats, range, histogram, cardinality, percentiles, date_histogram, geo_bounds, filters, nested, and more
• Geospatial — geo_distance, geo_bounding_box, geo_shape with all spatial relations
• Nested documents with block-join queries and inner_hits
• Highlighting with custom tags, per-field configuration
• Sort by field — keyword, numeric, score, with multi-level sort
• Pagination — from/size and cursor-based search_after
• Collapse — deduplicate results by a keyword field
• Explain — BM25 score breakdowns
• Rescore — two-phase scoring with custom query weights
• Single-file storage — one .luci file, no directory sprawl
• Auto-commit — documents are searchable immediately after add() or bulk()
• ES-compatible JSON query DSL — same queries, same field types

License

MIT