DEV Community: Sergey Nikolaev

Prepared statements in Manticore Search

Sergey Nikolaev — Fri, 03 Apr 2026 04:38:10 +0000

Imagine you're building a powerful search application. Users type in keywords, and your backend needs to query the Manticore Search database to find matching results. A common (and tempting!) approach is to embed user input directly into your SQL queries. For example, you might filter by a numeric field such as a category or record ID. If the user passes a normal value like 5, the query is SELECT * FROM products WHERE id=5. But what if they pass 1 OR 1=1? The query becomes SELECT * FROM products WHERE id=1 OR 1=1 — the condition is always true, so the query returns every row instead of one. This is SQL injection.

Fortunately, there's a safer and more efficient way: prepared statements. Essentially, prepared statements separate your SQL code from the data you pass in. Instead of building the entire query string each time, you define the query structure once with placeholders and then supply the search terms separately. You can learn more about the concept on Wikipedia.

Manticore Search supports prepared statements over the standard MySQL protocol, giving you a powerful tool for building secure search applications. By using prepared statements, you'll not only dramatically reduce the risk of SQL injection, but you'll also improve the readability of your code.

Prepared statements aren't just a feature; they're sometimes a requirement. For example, the Rust sqlx library works with the MySQL endpoint solely using prepared statements. Also, some OLE DB connectors that enable MS SQL to work with a MySQL server use prepared statements internally.

Why Use Prepared Statements?

Security First (SQL Injection): SQL injection is a web security vulnerability that allows attackers to interfere with the queries an application makes to its database. It happens when user input is improperly incorporated into a SQL query, allowing malicious code to be executed. For example, consider a simple search query built by concatenating a user's search term directly into the SQL:

// Vulnerable code example (DO NOT USE!)
$productId = $_GET['search'];
$query = "SELECT * FROM products WHERE id= " . $productId;

If $productId contained something like 0 OR 1=1, the query would become SELECT * FROM products WHERE id= 0 OR 1=1, effectively bypassing the WHERE clause and returning all products.

Prepared statements prevent this by treating user input strictly as data, not as part of the SQL command itself. The database driver handles the escaping and quoting, ensuring that any potentially harmful characters are neutralized. Here's the same query using a prepared statement:

// Secure code example using a prepared statement
$productId = $_GET['search'];
$stmt = $mysqli->prepare("SELECT * FROM products WHERE id= ?");
$stmt->bind_param("i", $productId);
$stmt->execute();

In this case, even if $productId contains malicious code, it will be treated as a literal value, not executable SQL.

How They Work

Prepared statements operate using a simple three-step process:

Prepare: First, you send the SQL statement with placeholders (like ? or ?VEC?) to Manticore Search. Manticore parses this statement and creates a query plan. It then returns a unique identifier for this prepared statement.
Bind: Next, you send the actual data – the values for the placeholders – to Manticore separately. This is where the security comes in; the data is treated purely as data, not as SQL code.
Execute: Finally, you instruct Manticore to execute the prepared statement using the stored query plan and the bound parameters.

Think of it like creating a template. You build the structure once, then fill in the blanks with different information each time you need to use it.

Parameter Placeholders: `?` & `?VEC?`

Manticore Search uses specific placeholders to identify parameters within your prepared statements:

? represents a single parameter – this could be an integer, a floating-point number, or a string. When using this placeholder, Manticore automatically handles escaping and quoting for string values, protecting against SQL injection and ensuring proper data formatting.
?VEC? is designed for lists of numeric values. It expects a string containing numbers separated by commas and optional spaces (e.g., 1, 2.3, 4, 1e-10, INF). Crucially, no escaping or quoting is applied to the values within ?VEC?. Valid input consists solely of numbers, commas, and spaces; any other characters will likely result in an error. This makes it perfect for directly inserting numeric vectors into your data - both float vectors and integer MVAs (multi-value attributes).

Example: prepared statements in PHP

Let's see how prepared statements work in practice using PHP. We'll demonstrate both a simple insert with string values and a more complex insert involving a floating-point vector using the ?VEC? placeholder.

First, a basic insertion:

<?php
// Assuming you have a valid MySQLi connection established ($mysqli)

$stmt = $mysqli->prepare("INSERT INTO products (name, description) VALUES (?, ?)");
$productName = "Awesome Widget";
$productDescription = "A truly amazing widget for all your needs.";
$stmt->bind_param("ss", $productName, $productDescription); // "ss" indicates two strings
$stmt->execute();

echo "Product added successfully!";
?>

This code prepares the INSERT statement, binds the string values for the product name and description, and then executes the query. The resulting SQL executed by Manticore would be:

INSERT INTO products (name, description) VALUES ('Awesome Widget', 'A truly amazing widget for all your needs.');

Now, let's tackle an example using a float vector. What is ?VEC?? It is a placeholder (only used in prepared statements) for a vector — a list of numbers, e.g. for embeddings or similar data. In Manticore SQL, a vector literal is always written with parentheses: (0.1, 0.2, 0.3). So when you use a prepared statement and have a vector parameter, you write those parentheses in the SQL string and use ?VEC? where the numbers go. You bind only the comma-separated numbers (e.g. "0.1,0.2,0.3"); you do not bind the ( and ) — they stay in the query. Without prepared statements you would build the full literal (0.1, 0.2, 0.3) yourself in the query string.

In PHP mysqli, the usual way to bind ?VEC? values is as strings, so iss is the normal choice in this example. If you want to stream a larger vector payload, you can also bind the parameter as b and send the contents with send_long_data().

<?php
// Assuming you have a valid MySQLi connection established ($mysqli)

$stmt = $mysqli->prepare("INSERT INTO items (item_id, coords, features) VALUES (?, (?VEC?),(?VEC?))");
$itemId = 123;
$coordVector = "20.245,54.354,30.000"; // that is vector of floats
$featureSet = "1,4,20,456,112,3"; // that is set of integer values (MVA)
$stmt->bind_param("iss", $itemId, $coordVector, $featureSet); // "i" for integer (itemId), "s" for string
$stmt->execute();

echo "Item with feature vector added successfully!";

$itemId = 124;
$coordVector = "18.500,42.000,31.125"; // Another float vector
$featureSet = "0,6,34,665,22,3445,221,564,2232,5644,43"; // Example with more feature values

// For larger payloads you can bind the second ?VEC? as a blob and stream it.
$featurePlaceholder = "";
$stmt->bind_param("isb", $itemId, $coordVector, $featurePlaceholder); // "b" is for blob data
// bind_param() must be called before send_long_data().
$stmt->send_long_data(2, $featureSet); // zero-based index: 2 means the third bound parameter
$stmt->execute();

echo "Item with feature vector added successfully!";
?>

Notice that the parentheses are part of the SQL string in the prepare() call. We only bind the values within the parentheses using the ?VEC? placeholder. The resulting SQL executed by Manticore will be:

INSERT INTO items (item_id, coords, features) VALUES (123, (20.245,54.354,30.000), (1,4,20,456,112,3));
INSERT INTO items (item_id, coords, features) VALUES (124, (18.500,42.000,31.125), (0,6,34,665,22,3445,221,564,2232,5644,43));

Using ?VEC? in a prepared statement gives you the same benefits as with the ? placeholder: the vector values are sent as data, not as part of the SQL text, so they cannot be interpreted as SQL and cannot cause injection. You also avoid having to manually build or escape the vector literal in your application — Manticore receives the bound numbers and formats the vector correctly, which keeps the query safe and the data consistent.

Important Considerations & Limitations

While powerful, Manticore's prepared statements have a few limitations to keep in mind.

Multi-Queries: Only a single SQL statement is allowed per prepared statement. Attempts to use multi-queries (e.g., SELECT ...; SHOW META) will fail. If you need to execute multiple statements, prepare a separate statement for each one and execute them sequentially within the same session.

Numeric Types: Some database drivers (like mysql2 for Node.js) might send numeric parameters as DOUBLE by default. This could lead to unexpected behavior if you require strict integer behavior (like rejecting negative IDs). In such cases, consider sending integers as strings or utilize driver-specific integer types (e.g., BigInt) to ensure correct data handling.

Rust sqlx Users: If you're using the sqlx crate in Rust, be aware that when reading result set rows, you must use column indices rather than column names. While column names are present in the result set, sqlx doesn't utilize them for mapping. For example, use row.try_get(0)? instead of row.try_get("id")?.

Conclusion

Prepared statements offer a critical combination of security, readability, and potential performance gains when working with Manticore Search. By separating your SQL logic from your data, you dramatically reduce the risk of SQL injection attacks, improve code maintainability, and potentially speed up query execution. We strongly encourage you to adopt prepared statements in your Manticore Search applications.

For more in-depth information, be sure to consult these resources:

Manticore Search Documentation on Prepared Statements: https://manual.manticoresearch.com/Connecting_to_the_server/MySQL_protocol#Prepared-statements
Wikipedia - Prepared Statements: https://en.wikipedia.org/wiki/Prepared_statement

This guide provides a solid foundation for using prepared statements effectively in your Manticore Search projects, leading to more secure, efficient, and maintainable applications.

KNN prefiltering in Manticore Search

Sergey Nikolaev — Thu, 02 Apr 2026 05:50:56 +0000

Vector search rarely happens in isolation. You almost always have filters — a price range, a category, a date window, a geographic boundary. The question is: when do those filters get applied?

The answer makes a surprising difference in result quality.

KNN prefiltering is available in Manticore Search starting from version 19.0.1.

The problem with postfiltering

Consider a product catalog with 10 million items. A user asks for the 10 nearest neighbors to a query vector, restricted to category = 'electronics'. With postfiltering, the KNN search runs first over the entire dataset, then the filter is applied to the results. If electronics make up 5% of the catalog, the graph explores nodes that are mostly irrelevant. Worse, many of the k nearest neighbors may not be electronics at all, so the final result set can be much smaller than requested. Ask for 10 results, get 2.

This is the fundamental limitation of postfiltering: the HNSW graph doesn't know about your filters. It finds the closest vectors overall, not the closest vectors that match your criteria. The more selective the filter, the worse the problem gets.

What prefiltering does differently

Prefiltering passes the filter into the HNSW graph traversal itself. As the algorithm explores candidate nodes, each one is checked against the filter before being added to the result heap. Only matching documents contribute to the final k results. This means you reliably get the k results you asked for, assuming k matching documents exist in the dataset.

In Manticore Search, prefiltering is enabled by default when your query combines KNN search with attribute filters. No special syntax is needed:

SELECT id, title, knn_dist()
FROM products
WHERE knn(embedding, (0.12, 0.45, 0.78, 0.33))
  AND category = 'electronics'
  AND price < 500
LIMIT 10;

Both category = 'electronics' and price < 500 are evaluated during HNSW traversal, not after. The equivalent JSON query:

POST /search
{
    "table": "products",
    "knn": {
        "field": "embedding",
        "query": [0.12, 0.45, 0.78, 0.33]
    },
    "query": {
        "bool": {
            "must": [
                { "equals": { "category": "electronics" } },
                { "range": { "price": { "lt": 500 } } }
            ]
        }
    },
    "limit": 10
}

Naive prefiltering and where it falls short

The obvious first approach is straightforward: traverse the HNSW graph normally, compute distances for every neighbor, but only add filter-matching nodes to the result heap. Filtered-out nodes still participate in navigation — if a non-matching node has a competitive distance, it enters the candidate queue and its neighbors get explored. The filter only gates what goes into the results.

This actually works reasonably well. The graph stays connected because filtered-out nodes are still traversed. But it has a performance problem that gets worse as the filter becomes more selective: every unvisited neighbor gets a distance computation regardless of whether it passes the filter. Distance computation is the most expensive operation in the search. With a filter matching 5% of documents, 95% of that work produces results that are immediately discarded. The algorithm pays full cost for navigation but gets no results from most of the work.

How Manticore solves it: ACORN-1

Manticore uses an ACORN-1-based algorithm (from the ACORN paper, SIGMOD 2024) that improves on naive prefiltering in two ways:

No distance computation for filtered-out nodes. When visiting a node's neighbors, ACORN-1 checks the filter first and only computes distance for nodes that pass. Filtered-out neighbors are never scored. When 95% of nodes fail the filter, this saves roughly 95% of the distance work compared to the naive approach.

Adaptive expansion through filtered-out nodes. When a neighbor fails the filter, the algorithm looks through that node's own neighbors to find filter-passing nodes further away. If those neighbors also fail the filter and not enough matching candidates have been found yet, it keeps going — 3 hops, 4 hops, as far as needed. The more selective the filter, the more aggressively the algorithm expands. This targeted walk through non-matching neighborhoods reaches matching candidates without scoring the non-matching ones along the way.

Think of it as searching for Italian restaurants in a city. The naive approach checks the menu at every restaurant and only keeps the Italian ones. ACORN-1 glances at the sign first — "French, skip; Thai, skip" — without going inside. And when it sees a stretch of non-Italian restaurants, it walks past them, peeking around each corner until it finds an Italian place on the other side.

Manticore activates ACORN-1 when fewer than 60% of total documents pass the filter. Above that threshold, naive prefiltering works well enough on its own.

Automatic brute-force fallback

Prefiltering works well across a wide range of filter selectivities, but there's an extreme case: what if only 50 documents out of 10 million match the filter? Traversing the HNSW graph — even with ACORN-1 — visits far more nodes than just scanning those 50 documents directly.

Manticore detects this automatically. When prefiltering is enabled, the query planner estimates the cost of HNSW traversal versus a brute-force distance scan over the filtered subset. It uses histogram-based selectivity estimates to predict how many documents pass the filter, then compares that against the expected number of nodes HNSW would visit. If brute-force is cheaper, Manticore skips HNSW entirely and scans the filtered documents directly.

This means you don't need to think about edge cases. Prefiltering adapts: ACORN-1 for moderate selectivity, brute-force for extreme selectivity, and standard HNSW when no filter is present.

When to use postfiltering instead

Prefiltering isn't always the best choice. There are cases where postfiltering is preferable:

When you want the closest vectors regardless of filters. Postfiltering gives you the k nearest neighbors from the full dataset, then removes non-matching ones. If your application tolerates getting fewer than k results and you care most about vector distance quality, postfiltering is simpler and more predictable.
When the filter matches most documents. If 95% of documents pass the filter, prefiltering adds overhead for almost no benefit — nearly every candidate matches anyway.
When you're debugging or benchmarking. Postfiltering gives you a clean baseline: pure HNSW results with a filter on top. This makes it easier to isolate whether a quality issue comes from the graph or the filter.

To explicitly request postfiltering in SQL:

SELECT id, knn_dist()
FROM products
WHERE knn(embedding, (0.12, 0.45, 0.78, 0.33), { prefilter=0 })
  AND category = 'electronics'
LIMIT 10;

In JSON, set "prefilter": false inside the knn object:

POST /search
{
    "table": "products",
    "knn": {
        "field": "embedding",
        "query": [0.12, 0.45, 0.78, 0.33],
        "prefilter": false
    },
    "query": {
        "equals": { "category": "electronics" }
    },
    "limit": 10
}

Forcing brute-force

If you know your dataset is small enough or your filters selective enough that a linear scan is the right strategy, you can force brute-force mode directly:

SELECT id, knn_dist()
FROM products
WHERE knn(embedding, (0.12, 0.45, 0.78, 0.33), { fullscan=1 })
  AND category = 'electronics'
LIMIT 10;

This skips HNSW entirely and computes exact distances over all documents that pass the filter. It guarantees perfect recall at the cost of linear-time scanning.

Summary

Prefiltering is the default in Manticore and the right choice for most filtered KNN queries. It guarantees you get k results (if they exist). Manticore automatically picks the best strategy based on how selective the filter is: standard filtered HNSW when most documents match, ACORN-1 when fewer than 60% pass (saving distance computations on filtered-out nodes), and brute-force when the filtered subset is small enough to scan directly. The query planner estimates filter selectivity per-query, per-segment, so there's nothing to tune.

Use postfiltering (prefilter=0 in SQL, "prefilter": false in JSON) when you want the globally closest vectors and can tolerate getting fewer than k results. Use brute-force (fullscan=1 in SQL, "fullscan": true in JSON) when you know a linear scan is the right strategy for your data.

Hybrid search in Manticore Search

Sergey Nikolaev — Wed, 01 Apr 2026 10:46:41 +0000

Search is rarely a one-size-fits-all problem. A user typing "cheap running shoes" wants exact keyword matches, but a user asking "comfortable footwear for jogging" is expressing the same intent in different words. Traditional full-text search handles the first case well. Vector search handles the second. Hybrid search combines both in a single query so you don't have to choose.

In modern search systems, this is often described as combining lexical (sparse) retrieval with semantic (dense) retrieval. Different terms, same idea: exact matching plus meaning.

What is hybrid search?

Hybrid search runs a full-text (BM25) search and a vector (KNN) search side by side, then merges the two result lists into one. Documents that score well on either signal (or both) rise to the top.

Full-text search is great at exact keywords, rare terms, and identifiers. Vector search understands meaning — that "automobile" and "car" are the same concept — because their embeddings are nearby in vector space.

Each method has blind spots:

Full-text struggles with synonyms and natural language
Vector search struggles with exact tokens like SKUs, error codes, and IDs

Hybrid search covers both.

How hybrid search fits into modern search pipelines

Hybrid search is the retrieval stage — the part that finds relevant candidates from your dataset.

Instead of relying on a single method, hybrid search combines keyword matching and semantic similarity to produce a stronger result set from the start.

In practice, this means:

Better recall for natural language queries
Precise matching for identifiers like SKUs or error codes
More relevant results without needing complex query logic

The goal is simple: return the best possible candidates in a single pass, using both signals together.

When should you use it?

Hybrid search is a good fit when:

Your queries mix intent and specifics. A search like python error 403 forbidden benefits from keyword precision on the error code and semantic understanding of the problem description.
You're building a RAG pipeline. Retrieval-Augmented Generation needs the most relevant chunks fed to the LLM. Hybrid retrieval consistently finds more relevant documents than either method alone.
Your catalog has structured and unstructured data. E-commerce products have precise names and model numbers (keyword territory) but also descriptions where meaning matters more than exact wording.
You can't predict how users will search. Some will paste exact phrases, others will describe what they're looking for in natural language. Hybrid search handles both gracefully.

How it works

Manticore uses Reciprocal Rank Fusion (RRF) to merge results. The idea is simple: instead of trying to compare raw BM25 scores with KNN distances (which are on completely different scales), RRF looks at rank positions. A document that's ranked #1 in the text results and #3 in the KNN results gets a higher combined score than a document that only appears in one list.

Here's a quick example. Suppose a text search and a KNN search each return their own top 3:

Text search results:

Rank	Document
1	Doc A
2	Doc B
3	Doc C

KNN search results:

Rank	Document
1	Doc C
2	Doc A
3	Doc D

RRF scores each document using the formula 1 / (rank_constant + rank). With the default rank_constant=60:

Document	Text contribution	KNN contribution	RRF score
Doc A	1/(60+1) = 0.0164	1/(60+2) = 0.0161	0.0325
Doc C	1/(60+3) = 0.0159	1/(60+1) = 0.0164	0.0323
Doc B	1/(60+2) = 0.0161	—	0.0161
Doc D	—	1/(60+3) = 0.0159	0.0159

Doc A ranks highest because it appears near the top in both lists. Doc C is close behind for the same reason. Doc B and Doc D each appear in only one list, so they score lower.

Why RRF?

There are two common ways to combine results:

Rank-based fusion (RRF) — simple, robust, no need to normalize scores
Score-based fusion — normalize scores first, then combine

Manticore uses RRF because it works well out of the box and avoids score calibration problems.

Under the hood, a hybrid query is split into independent sub-queries — one for full-text, one (or more) for KNN — that run in parallel. Once all sub-queries finish, RRF fuses their ranked result lists into a single output.

Why not just use one or the other?

Consider a support knowledge base with articles for different error codes — connection failures, authentication problems, sync issues. A user sees error E-5020 on screen and reports: "I can't connect to the server."

Vector search understands the symptom but not the error code. A KNN search for "can not connect to the server" returns:

#	Title	KNN distance
1	Error E-5030: DNS Resolution Failed	0.572
2	Error E-2091: App Loading Timeout	0.583
3	Error E-5020: SSL Certificate Mismatch	0.605
4	Error E-5010: Service Unavailable	0.622
5	Error E-4001: Login Failed	0.665

The correct article (E-5020) is buried at #3. KNN ranks DNS and timeout errors higher because their descriptions are semantically closer to "can't connect." The actual problem — an SSL certificate mismatch — uses completely different vocabulary, so it scores lower.

You might think: just add the error code to the KNN query. But "E-5020" and "E-5010" are arbitrary identifiers with no semantic meaning — embeddings treat them as nearly identical tokens. KNN for "E-5020 can not connect to the server" does move E-5020 to #1, but only because the added text shifts the semantic context — the error code itself carries no weight.

Hybrid search solves this by sending each signal where it works best — the error code to full-text, the symptom to KNN:

SELECT title, hybrid_score()
FROM support_articles
WHERE knn(embedding, 'can not connect to the server')
  AND MATCH('E-5020')
LIMIT 5
OPTION fusion_method='rrf';

#	Title	Hybrid score
1	Error E-5020: SSL Certificate Mismatch	0.032
2	Error E-5030: DNS Resolution Failed	0.016
3	Error E-2091: App Loading Timeout	0.016
4	Error E-5010: Service Unavailable	0.016
5	Error E-4001: Login Failed	0.015

E-5020 jumps from #3 to #1 with twice the score of everything else. Full-text treats "E-5020" as an exact string — not similar to "E-5010", not close enough, just different. KNN ensures related connection errors still appear below for context.

This is the core value of hybrid search:

Identifiers → full-text
Meaning → vector search

Each method covers the other's blind spot.

Getting started

The simplest way to run a hybrid search is with hybrid_match(). If your table has auto-embeddings configured, one line does everything — text search, embedding generation, KNN search, and RRF fusion:

SELECT id, hybrid_score()
FROM products
WHERE hybrid_match('running shoes');

The JSON equivalent:

POST /search
{
  "table": "products",
  "hybrid": { "query": "running shoes" }
}

Manticore:

generates embeddings
runs both searches in parallel
fuses results

Full control: explicit MATCH + KNN

When you need to supply your own vectors or tune individual sub-queries, use the explicit form with MATCH() and KNN() in the WHERE clause:

SELECT id, hybrid_score()
FROM products
WHERE match('running shoes')
  AND knn(embedding, (0.12, 0.45, 0.78, ...))
OPTION fusion_method='rrf';

POST /search
{
  "table": "products",
  "knn": {
    "field": "embedding",
    "query_vector": [0.12, 0.45, 0.78, "..."]
  },
  "query": { "match": { "title": "running shoes" } },
  "options": { "fusion_method": "rrf" }
}

Each result includes:

hybrid_score() — fused score (used for default sorting)
weight() — BM25 score
knn_dist() — vector distance

Attribute filters (AND category = 'footwear') apply to both sub-queries.

Tuning

Three options let you adjust fusion behavior:

rank_constant — controls how much top positions dominate the fused score. Lower values (e.g. 10) make rank #1 count significantly more than rank #5. Higher values flatten the curve. See rank_constant.
fusion_weights — lets you give different importance to each sub-query. If text relevance matters more than vector similarity, weight it higher. See fusion_weights.
window_size — how many results each sub-query retrieves before fusion. By default, Manticore computes this automatically from your KNN parameters and query LIMIT. See window_size.

Multi-vector fusion

Hybrid search isn't limited to one text search plus one KNN search. You can fuse multiple vector searches together — useful when your data has several distinct semantic dimensions. For example, an e-commerce product has a textual description and a photo. A user searching for "minimalist white sneakers" cares about both: the title should match the style, and the product image should look like what they have in mind. By encoding the title and the image into separate vector spaces, you can search both at once and let RRF surface products that match across all three signals — keywords, text meaning, and visual similarity:

SELECT id, hybrid_score()
FROM products
WHERE match('running shoes') AS text
  AND knn(title_vec, (0.12, 0.45, ...)) AS title_sim
  AND knn(image_vec, (0.88, 0.21, ...)) AS image_sim
OPTION fusion_method='rrf',
       fusion_weights=(text=0.5, title_sim=0.3, image_sim=0.2);

All sub-queries run in parallel and are fused together via RRF.

Conclusion

Hybrid search is not about replacing full-text or vector search — it’s about using both where they work best.

Keyword search gives you precision for exact terms and identifiers. Vector search gives you flexibility for natural language and meaning. On their own, each has gaps. Together, they produce consistently better results across a wide range of queries.

With hybrid search in Manticore, you don’t need to choose between the two or build complex query logic to handle different cases. You can run both signals in parallel and get a single, unified result set.

If your search needs to handle both exact matches and intent — which most real-world applications do — hybrid search is a straightforward way to improve relevance without adding complexity.

Manticore Search 25.0.0

Sergey Nikolaev — Tue, 31 Mar 2026 10:54:20 +0000

Manticore Search 25.0.0 has been released. This version brings a simpler packaging model together with major improvements in hybrid search, vector filtering, backups, RT table maintenance, and application integration.

Upgrade Notes

Please review these before upgrading:

MCL 13.0.0 is required. Manticore Search 25.0.0 updates the daemon/MCL interface and adds API_URL and API_TIMEOUT for auto-embedding models. If you manage MCL separately, upgrade the daemon and MCL together. (PR #123)
Replication clusters require coordinated upgrades. Mixed-version clusters are not compatible with the replication changes in 24.0.0. Upgrade clustered nodes together. (Issue #4343)
Newer bigram tokenization options affect downgrade paths. If you rebuild indexes with the bigram tokenization changes introduced in 23.0.0, those rewritten indexes are not compatible with older Manticore versions. (Issue #4364)
Filtered KNN results may change. Since KNN prefiltering was introduced in 19.0.0, filtered vector queries can now prioritize nearest neighbors that satisfy the filter during search, rather than filtering only after candidate selection. (Issue #4103)

Packaging Simplified

Starting with 25.0.0, manticore is the bundle package for deb and rpm. It includes the daemon, tools, converter, development headers, ICU data, bundled dependency packages, and built-in language packs for German, English, and Russian, along with Jieba support.

In most cases, upgrading is now simpler: install manticore and let the bundle pull in the components you need. If older split packages conflict with the new layout, remove them first with apt remove 'manticore*' or yum remove 'manticore*' and then install manticore. Your existing data remains intact. On yum-based systems, the package manager may replace the config file, but it automatically keeps a backup of the previous one.

This is an important operational change: it reduces packaging friction and makes installation simpler and more predictable.

Highlights

Hybrid search is now a first-class option

Manticore now supports hybrid search, allowing you to combine full-text and vector retrieval in a single query. This makes it much easier to build retrieval pipelines that balance lexical precision with semantic recall.

You can use hybrid search via both SQL and JSON interfaces. In SQL, you can combine MATCH() with one or more KNN() subqueries. For teams building modern search experiences, this is one of the biggest additions in the release line.

Better vector search with KNN prefiltering

With KNN prefiltering, attribute filters can be applied during vector search instead of only after candidate selection. That matters when you need "the nearest neighbors among documents that also match my filter", not just "the nearest neighbors overall, filtered afterward".

This improves both relevance and predictability for filtered vector search workloads such as category-constrained product search, tenant-aware search, and permission-filtered semantic retrieval.

Faster RT maintenance with parallel chunk merging

Manticore RT tables now handle heavy maintenance much better thanks to N-way merges and parallel OPTIMIZE jobs. We covered the details in Parallel chunk merging.

The result is simpler to explain than the implementation: when a table accumulates many disk chunks, cleanup and compaction take less time, so RT tables perform better under sustained write load.

Easier application integration with prepared statements

Manticore now supports MySQL-compatible prepared statements, which we covered in Prepared statements in Manticore Search. This improves compatibility with MySQL clients, connection pools, ORMs, and frameworks that expect binary protocol prepare/execute behavior.

For application developers, this removes one more integration edge case and makes Manticore easier to adopt in existing stacks.

S3-compatible backup and restore

Backup operations are more flexible now thanks to S3-compatible backup and restore. Manticore Backup supports AWS S3, MinIO, Wasabi, and Cloudflare R2, making it easier to ship backups to object storage and build cleaner disaster-recovery workflows.

This is especially useful for containerized and cloud-native deployments where local disk is temporary but object storage is the durable layer.

Auto-embeddings keep improving

25.0.0 also extends Manticore's recent auto-embeddings work. The new MCL version adds API_URL and API_TIMEOUT controls for auto-embedding models. Recent development also added support for GGUF quantized local embedding models, T5 encoders, gated Hugging Face downloads, and replication-safe embedding handling for RT tables.

Taken together, these changes make Manticore more practical both for local embedding pipelines and for deployments that rely on external model endpoints.

Other Notable Improvements

This release also includes 36 bug fixes across query execution, replication, macOS packaging, auto-embeddings, RT tables, and SQL compatibility.

False-positive full-text matches caused by max_query_time interruptions in complex queries were fixed, so timed-out searches no longer return rows that do not actually satisfy the query. (Issue #4375)
Replication was fixed for transactions containing duplicate document IDs, so replicas no longer lose rows while the donor removes duplicates correctly. (Issue #4388)
Several auto-embedding stability issues were fixed, including crashes during embedding generation, invalid UTF-8 handling, and missing RT locks during validation. (PR #4349, PR #4370, PR #4371)
LEFT JOIN now returns proper MySQL NULL values instead of the string NULL, improving compatibility with MySQL clients and drivers. (Issue #4229)
A race during RT disk chunk save that could lose killed documents and produce duplicate rows after merges or saves was fixed. (Issue #4207)
Fuzzy search now works across queries involving multiple tables. (PR #4372)

Why 25.0.0 Matters

Manticore Search 25.0.0 combines the packaging changes with several important capabilities that are now available together:

hybrid lexical + vector retrieval
filtered vector search that behaves the way users expect
simpler integration through prepared statements
object-storage-friendly backup workflows
faster RT table compaction and maintenance
more flexible auto-embedding deployments

For the complete technical details, see the changelog.

Need help or want to connect?

Join our Slack
Visit the Forum
Report issues or suggest features on GitHub
Email us at contact@manticoresearch.com

MCP-Manticore: Let Your AI Assistant Write Manticore Queries for You

Sergey Nikolaev — Wed, 25 Mar 2026 10:23:25 +0000

Introduction

You've heard Manticore Search is fast. You've heard it handles full-text, vector, and fuzzy search in one engine. But when you sit down to actually use it, you're staring at documentation, guessing at SQL syntax, and hoping your CREATE TABLE doesn't throw an obscure error.

MCP-Manticore changes the game. It's a Model Context Protocol (MCP) server that connects Cursor, Claude Code, Codex CLI, or any MCP-compatible AI assistant directly to your Manticore instance. The AI can read the docs, inspect your schema, and execute queries — all before it writes a single query for you.

MCP (Model Context Protocol) is an open standard that lets AI assistants connect to external tools and data sources. Instead of the AI hallucinating Manticore syntax based on training data from who-knows-when, it gets real-time access to your database and the official documentation.

Two Ways This Helps You

Depending on what you're doing, MCP-Manticore provides value in two different ways:

1. Developer Assistance (Primary): You're building an app that uses Manticore. The AI helps you create tables, write complex queries, and understand features — without you memorizing SQL syntax.

2. Data Exploration (Secondary): You have data in Manticore and want to ask questions in plain English. "Show me the cheapest accessories" or "Find products similar to this one." For complex operations like vector search or fuzzy matching, the AI needs MCP to know the correct Manticore-specific syntax.

Let's look at both.

The Problem: AI Without Context

When you ask an AI assistant to help with Manticore without MCP integration, here's what happens:

Example: Creating a Table with Auto-Embeddings

You: "How do I create a Manticore table with auto-embeddings for semantic search?"

AI (guessing):

CREATE TABLE products (
    title text,
    description text,
    description_vector float_vector 
        embedding='sentence-transformers/all-MiniLM-L6-v2' 
        source='description'
);

Looks reasonable, right? Wrong. The actual syntax uses MODEL_NAME and FROM, not embedding and source. You'd discover this only after the query fails, sending you back to the documentation.

This is the pattern:

AI generates query based on outdated or guessed syntax
You run it, get an error
You manually check documentation
You correct the AI (or fix it yourself)
Repeat until it works

For developers integrating Manticore into applications, this friction kills productivity. You're not exploring data — you're fighting syntax.

The Solution: MCP-Manticore

With MCP-Manticore enabled, the conversation changes:

You: "How do I create a Manticore table with auto-embeddings for semantic search?"

AI: "Let me check the documentation for the correct syntax..."

[AI calls list_documentation via MCP, searches for "embedding|semantic|knn|vector"]

AI: "Here's the correct syntax. Manticore uses MODEL_NAME and FROM for auto-embeddings:"

CREATE TABLE products (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='sentence-transformers/all-MiniLM-L6-v2' FROM='title,description'
);

The AI now has:

Real-time access to Manticore documentation
Schema introspection via list_tables() and describe_table()
Query execution to test and validate
Safety controls — read-only by default, write operations require opt-in

Real Examples: With and Without MCP

Example 1: Schema Creation

Without MCP:
The AI guessed the syntax, using embedding='...' and source='...'—which doesn't exist in Manticore. You'd hit an error and waste time debugging.

With MCP:
The AI retrieved the official documentation first and provided the correct MODEL_NAME and FROM syntax. It also explained the supported models (local HuggingFace models, OpenAI, Voyage, Jina) and the HNSW_SIMILARITY options (L2, IP, COSINE).

Example 2: Semantic Search with Auto-Embeddings

You: "Find products similar to 'noise-canceling headphones for travel'"

Without MCP:
The AI completely loses track. Without access to documentation, it:

Tries to SELECT all data and aggregate internally without any filter
Hallucinates embedding vectors with made-up syntax: ANY_KNN(embedding, (-0.07089090,0.04201586,-0.03262700...))
Attempts to write Python scripts to manually calculate similarity
Eventually gives up and just does string matching on descriptions

Result: It finds "Wireless Headphones" only because the description literally contains "noise-canceling headphones" — pure luck, not semantic search.

With MCP:
The AI checks documentation, discovers your table uses auto-embeddings, and learns that knn() accepts text directly when MODEL_NAME is configured:

SELECT id, name, description, knn_dist() 
FROM products 
WHERE knn(embedding, 5, 'noise-canceling headphones for travel');

Result: Returns Wireless Headphones as #1 (correct), but also surfaces semantically related items — actual vector similarity, not keyword matching.

Example 3: Fuzzy Search (Typo Tolerance)

You: "Find products even if I misspell the name, like 'headphons' instead of 'headphones'"

Without MCP:
The AI tries everything it was trained on, hoping something works:

MATCH('headphons~1') and MATCH('headphons~') — wrong operators
CALL SUGGEST('headphons', 'products') — wrong approach for this use case
MATCH('FUZZY(headphons') — hallucinated syntax that doesn't exist
ALTER TABLE products SET min_infix_len = 3 — unnecessary and wrong
OPTION expand_keywords = 1 — unrelated feature

It even tried to optimize the table and run suggestions again. Complete chaos.

Result: No working query. Just a pile of failed attempts based on outdated or confused training data.

With MCP:
The AI checks the documentation and finds the correct syntax immediately:

SELECT * FROM products WHERE MATCH('headphons') OPTION fuzzy=1;

Result: Returns "Wireless Headphones" despite the typo. The AI also explains that fuzzy=1 allows Levenshtein distance of 1 (one character difference), and you can adjust tolerance with OPTION fuzzy=1, distance=2 for more flexibility.

Key Features

Intelligent Documentation Lookup

MCP-Manticore includes a documentation fetcher that pulls directly from the Manticore Search manual on GitHub. When you ask about features like KNN vector search, fuzzy matching, or full-text operators, the AI retrieves the official documentation before responding.

Schema-Aware Query Building

The server provides tools that let the AI understand your data structure before writing queries:

list_tables() — See what tables exist
describe_table() — Understand column names and types
execute_query() — Run queries and see results

Safe Query Execution

By default, MCP-Manticore runs in read-only mode. Write operations (INSERT, UPDATE, DELETE, DROP) require explicit opt-in via environment variables:

export MANTICORE_ALLOW_WRITE_ACCESS=true  # Enable INSERT/UPDATE/DELETE
export MANTICORE_ALLOW_DROP=true            # Enable DROP/TRUNCATE

Multiple Transport Options

Connect via:

stdio (for CLI-based AI assistants like Claude Code)
HTTP (for web-based integrations)
SSE (Server-Sent Events for real-time updates)

With optional JWT authentication for secure deployments.

Tutorial: Setting Up MCP-Manticore

MCP-Manticore works with any MCP-compatible AI assistant, including Cursor, Claude Code, Codex CLI, Windsurf, and any other tool that supports the Model Context Protocol.

Step 1: Ensure UV is Installed

MCP-Manticore runs best with uv, a fast Python package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

With uv, you don't need to manually install MCP-Manticore—uvx downloads and runs it automatically.

Step 2: Configure Environment Variables (Optional)

# Required: Manticore connection (defaults shown)
export MANTICORE_HOST=localhost
export MANTICORE_PORT=9308

# Optional: Enable write access (default: read-only)
export MANTICORE_ALLOW_WRITE_ACCESS=true

# Optional: Allow destructive operations (DROP, TRUNCATE)
export MANTICORE_ALLOW_DROP=false

Step 3: Add to Your MCP Client

General Configuration:

Command: uvx mcp-manticore
Environment variables (if needed): MANTICORE_HOST, MANTICORE_PORT, etc.

Example configuration (mcp.json):

{
  "mcpServers": {
    "manticore": {
      "command": "uvx",
      "args": ["mcp-manticore"],
      "env": {
        "MANTICORE_HOST": "localhost",
        "MANTICORE_PORT": "9308"
      }
    }
  }
}

For client-specific setup instructions (Cursor, Claude Desktop, Windsurf, etc.), see the MCP-Manticore README.

Step 4: Verify Connection

Test by asking your AI assistant:

"Show me all tables in Manticore"

You should see the AI call the list_tables() tool and display your tables.

Configuration Reference

Environment Variable	Description	Default
`MANTICORE_HOST`	Manticore server hostname	`localhost`
`MANTICORE_PORT`	Manticore HTTP port	`9308`
`MANTICORE_ALLOW_WRITE_ACCESS`	Enable INSERT/UPDATE/DELETE	`false`
`MANTICORE_ALLOW_DROP`	Enable DROP/TRUNCATE	`false`
`MANTICORE_MCP_TRANSPORT`	Transport type (stdio/http/sse)	`stdio`
`MANTICORE_MCP_AUTH_TOKEN`	JWT token for HTTP/SSE	-

The Future: Agents That Install Themselves

There's a third use case on the horizon: autonomous agents that discover and install MCP servers themselves.

Imagine an AI agent that:

Finds your GitHub repo mentioning Manticore
Searches for "Manticore MCP server"
Finds MCP-Manticore, installs it automatically
Starts querying your database to complete its task

This isn't science fiction — OpenAI's Codex and similar agentic systems are moving in this direction. When that future arrives, having MCP-Manticore in the MCP registry means your AI tools will just work with Manticore, no manual setup required.

Conclusion

MCP-Manticore transforms AI assistants from passive text generators into active, knowledgeable development partners. Whether you're:

Building with Manticore — Let the AI handle syntax while you focus on your application
Learning Manticore — Ask questions in plain English, get accurate answers backed by docs
Exploring your data — Query without memorizing SQL syntax or table schemas

The old way: guess, error, debug, repeat.

The new way: ask, verify, execute, done.

Ready to try it? With uv installed, just add MCP-Manticore to your MCP client settings and start asking. Your future self — free from syntax rabbit holes — will thank you.

Resources:

Manticore Search on Microsoft Azure: DX1's Story

Sergey Nikolaev — Wed, 18 Feb 2026 04:02:42 +0000

TL;DR: 

- DX1 uses Manticore Search for customer and parts search with a fast typeahead UX  
- Chosen for open-source licensing and speed  
- Deployed on Azure VMs running Ubuntu, aligned with DX1’s existing Azure footprint  
- Handles 20M+ parts; best typeahead performance requires indexes in memory  
- Scales by upgrading VM memory or adding nodes to a Manticore cluster  
- Day-to-day operations are low touch and low maintenance

Context

This article is based on direct input from Damir Tresnjo at DX1. It describes how DX1 runs Manticore Search in production on Microsoft Azure today, focusing on why they chose Manticore, how they deploy it, and what they have learned about performance and scaling.

DX1 in One Paragraph

DX1 uses Manticore Search as a fast, user-facing search layer for customers and a parts catalog that has grown beyond 20 million records. The setup is intentionally simple: Manticore runs on Ubuntu-based Azure VMs alongside the rest of their Azure infrastructure, delivering responsive typeahead while staying “low touch” operationally. As their data and traffic grow, they scale in a straightforward way by upgrading VM sizes or adding more nodes.

Search That Customers Actually Enjoy Using

DX1 uses Manticore Search to power search across customer and parts data. Typeahead is a core part of the experience, and according to Damir, it is one of the most appreciated features by their users.

“We use it for searching through customers and parts data, we have a type ahead functionality that our customers love.”

This is a practical, user-facing use case where milliseconds matter, and it has shaped both infrastructure and operational choices.

If you're exploring autocomplete in Manticore, there are multiple ways to implement it depending on data and UX requirements. For a deeper dive, see our overview of fuzzy search and autocomplete: New fuzzy search and autocomplete.

Why DX1 Chose Manticore Search

The decision to use Manticore Search was straightforward: it is open source and fast.

“Open source and very fast.”

That combination made it a good fit for DX1’s search workload and cost expectations, while keeping the stack approachable for a lean team.

Deployment on Azure VMs

DX1 runs all of its infrastructure on Azure, so deploying Manticore there was the natural choice. The team runs Manticore Search on Azure virtual machines using Ubuntu.

**“We run everything on Azure, so we deployed Manticore there as well."

No Azure-specific expensive managed services were required; VMs provided the flexibility they needed while staying consistent with the rest of their environment.

Performance, Memory, and Scale

Manticore has been fast and stable for DX1, even at large scale. Their production dataset includes over 20 million parts.

“It performs very fast, we have over 20 million parts we search through.”

One practical consideration is memory. Typeahead performance benefits from indexes being in memory, which means VM memory may need to grow alongside the index.

“It does need the database to be in memory for the type ahead performance. As soon as index outgrows available memory, we need to upgrade the VM memory.”

This creates a clear scaling path: grow memory on existing VMs or add more nodes to a cluster.

“We can scale each VM or we can add more VMs to a Manticore cluster.”

Day-to-Day Operations

Operationally, DX1 describes Manticore as low touch and low maintenance.

“Low touch, low maintenance, most of the time it just runs.”

There are no special Azure features involved; the setup is deliberately simple, focused on VMs and predictable operations.

Recommendation

DX1 would recommend Manticore Search to other teams looking for a fast and cost-effective search engine.

“Yes, I would recommend Manticore to anyone looking for a fast, reliable and cost effective search engine.”

For DX1, the combination of speed, open-source flexibility, and straightforward VM-based deployment on Azure has been a dependable foundation for search at scale.

Conclusion

DX1’s story is a good fit for teams who want a fast, reliable search engine without turning search infrastructure into a project of its own: run Manticore on straightforward Linux VMs, keep operations simple, and scale predictably. For low-latency typeahead in particular, it’s normal to plan for sufficient RAM headroom, so scaling often starts with memory (scale up) and later expands to adding nodes (scale out) as data and traffic grow.

Talk to Us About Migrating to Manticore

If you're considering a migration to Manticore Search and want a quick architecture review (for example, a VM-based setup on Azure), get in touch with us. Share a bit about your dataset size, query patterns, and latency targets, and we will help you validate an approach and plan the next steps.

Azure AI Search vs Manticore Search

Sergey Nikolaev — Mon, 16 Feb 2026 11:13:41 +0000

Vector search is great for the “kinda similar” part of search. The annoying part is everything else: exact phrases, filters that must be respected, typo tolerance, relevance you can explain to a PM, and results that don’t randomly flip because a model sneezed.

So this isn’t a “vectors vs keywords” post. It’s about the boring, practical combo: vector + full-text, in the same system, with predictable behavior.

Azure AI Search and Manticore Search can both do hybrid search. But they feel very different to operate day-to-day.

Azure optimizes for rapid delivery. Manticore optimizes for living with search over time. That difference shows up less in week one — and a lot more in month six.

Where “generic search” stops working

There’s a whole class of search problems that look simple until you ship them: document search, knowledge bases, internal tools, anything with “small chunks” (paragraphs/sections) and lots of metadata.

This is where managed abstractions start to leak, and where defaults stop being your friend.

You end up caring about stuff like:

strict filters (workspace/project, region, owner/team, timestamps, doc type, visibility, version)
phrase/proximity (because wording matters)
stable ranking (so results don’t wander around week to week)
highlights/snippets that look like actual citations, not “AI vibes”

And yes, semantic/vector search helps — but it doesn’t replace full-text fundamentals or explainability.

Once you’re in that world (filters, phrases, stable ranking, “why did this rank?”), search stops being a thing you “turn on” and becomes something you’ll tune and debug over time. That’s when the real choice shows up: accept a managed service’s abstraction layer, or run an engine where ranking and execution are more explicit.

That split maps pretty closely to Azure AI Search vs Manticore.

Two ways to solve it

The cleanest way to think about it:

Azure AI Search is a managed service you rent. You trade control for convenience (and you get Azure-shaped guardrails).
Manticore Search is a search engine you run. You get knobs and dials, plus responsibility for the box it runs on.

If all you need is “good enough search” plus easy integration, Azure is hard to beat. If you need to argue with relevance and win, Manticore is easier to live with.

Cost comparison: managed vs self-hosted

This is one of the biggest practical differences between these two approaches, and it often only becomes obvious after a few months in production.

Azure AI Search costs

Azure AI Search is billed as a managed cloud service. You provision capacity (replicas and partitions), and you pay for that capacity per hour, whether it’s fully used or not.

That model has a few practical consequences:

Cost scales with provisioned capacity, not actual query volume.
High availability and higher throughput multiply costs (replicas × partitions).
Vector search increases memory pressure, which often pushes you into higher tiers sooner than expected.
You can’t “scale to zero” — the service costs money as long as it exists.

In real-world setups, teams often start small and then gradually scale up as indexes grow, query volume increases, or latency requirements tighten. Over time, it’s common for Azure AI Search to land in the hundreds of dollars per month, and for more demanding workloads, four figures per month is not unusual.

None of this is surprising — you’re paying for a fully managed service with SLAs, built-in redundancy, and tight Azure integration. But the important thing is that cost growth can feel indirect: you don’t always see a clear, linear connection between “we changed X” and “the bill went up”.

Manticore Search costs

Manticore Search itself is free and open source. There is no licensing cost. What you pay for is infrastructure and operations.

In practice, that usually means:

one or more VMs (or containers)
storage
monitoring and backups
some ops time

For many document and knowledge-base workloads, a single modest VM is enough. That often puts the monthly infrastructure cost in the tens of dollars, not hundreds. Even with redundancy or horizontal scaling, costs tend to grow in a predictable, hardware-shaped way.

The key difference is visibility: if costs increase with Manticore, it’s usually because you explicitly added RAM, CPU, or machines. There’s no opaque service unit math in the middle.

The tipping point

If your priority is minimal operational effort and deep Azure-native integration, Azure AI Search’s pricing can be a reasonable trade-off.

If your priority is predictable long-term cost, clear performance knobs, and avoiding surprise bills as data grows, running Manticore yourself often ends up significantly cheaper — especially once vector search is in the mix.

Azure AI Search: works fast, gets fuzzy later

Azure has a solid keyword engine: analyzers, stemming, phrases/proximity, synonym maps, scoring profiles, filters, and an optional semantic ranking layer. You can ship something quickly.

Where it starts to sting is when you’re past the demo and now you’re maintaining it:

Tuning is mostly “turn these weights” (scoring profiles), plus maybe semantic ranking.
The scoring is less transparent end-to-end than Manticore. You can tune with scoring profiles/analyzers and measure results, but you don’t get the same “read the query, understand the ranking” feeling.
Hybrid merging is managed; keyword and vector results are fused with Reciprocal Rank Fusion (RRF). It’s convenient. It’s also harder to inspect when the top 10 looks wrong.

In practice, this often turns into compensating logic in the application layer: boosting, filtering, or post-processing results because the search engine won’t quite do what you need. That logic is harder to test, harder to explain, and harder to remove later.

If you’ve never had to explain “why is this #1?” to someone who’s mad, this is fine. If you have, you already know the pain.

Also: the whole thing is defined in service terms — schema JSON, Azure APIs, Azure limits. The practical downside is vendor lock-in: once your indexing model, analyzers, scoring profiles, and query patterns are Azure-shaped, moving later is real work.

Manticore Search: explicit, and honestly… nicer to debug

Manticore comes from the classic IR world and keeps full-text features very upfront: BM25-style scoring, field-level matching, phrases/proximity, filtering, and a SQL-ish query language. You can look at a query and tell what it will do. And more importantly: you can explain it to someone who doesn’t work on search.

Example: a “normal” full-text query

SELECT doc_id, WEIGHT()
FROM documents
WHERE MATCH('"data retention policy"~3')
  AND department = 'Finance'
  AND effective_date >= '2022-01-01'
ORDER BY WEIGHT() DESC
LIMIT 10;

That “WEIGHT()” bit is not magic; it’s part of the mental model. This matters more than people think.

Hybrid search without guesswork

With Azure, hybrid is “run both, fuse with RRF”. With Manticore, hybrid is “do this, then this, then filter and apply secondary ordering”. It’s less elegant on a slide, but it’s very practical.

Example (vector first, then text, then explicit sorting):

SELECT doc_id, knn_dist(), WEIGHT()
FROM documents
WHERE knn(embedding, 50, 'how to rotate api keys safely')
  AND MATCH('"key rotation" | "rotate keys"')
ORDER BY knn_dist() ASC, WEIGHT() DESC
LIMIT 10;

You can read this query out loud and it doesn’t sound like a prayer. That’s the point.

One nuance: KNN results are primarily ordered by vector distance; additional ORDER BY criteria refine within that KNN set (think: tie-breaks / secondary sorting), rather than “fully fusing” scores into a single blended rank.

Also: when ranking changes, you can usually point to the exact part of the query that caused it. Regressions become boring to debug — which is exactly what you want.

Storage-first products don’t replace search (they just force a second system)

This comes up a lot on Azure: you pick a document store (Cosmos DB, DocumentDB/Mongo API, etc.) and hope it’ll cover search too.

It won’t, not for anything chunk-level or relevance-sensitive. You’ll quickly want:

phrase/proximity
relevance tuning beyond basic text matching
better ranking control
hybrid (vector + keyword) that you can reason about

So you end up bolting on Azure AI Search anyway, and now you’re maintaining two separate things: storage + search, plus an indexing pipeline in between. That can be totally fine. Just don’t pretend it’s one system.

Freshness and “did my update land?”

In Azure, updates are API calls with their own semantics (and you need to be careful with partial updates). When content changes, vector fields need to be handled explicitly. It’s doable, it’s just… application-work.

Manticore’s real-time tables behave more like a database: insert/update/delete and the full-text + vector indexes keep up together. If you’re building something like product search or docs search where things change all the time, this feels simpler.

“We want Azure, preferably managed” (fair)

If your company’s default posture is “managed everything”, Azure AI Search fits that worldview. You plug it in, you accept the service model, you move on.

If you want Manticore with minimal headaches on Azure, the honest pitch is: it’s not managed, but it can be boring.

Azure AI Search works best when search is an infrastructure dependency. Manticore works best when search is a product surface.

Typical setup that doesn’t turn into a science project:

keep documents in whatever Azure storage you already trust (Blob, a DB, etc.)
run Manticore on a single VM (or a small VMSS later) in a VNet
keep chunking/segmentation + indexing as a simple worker pipeline (queue + worker, or whatever you already have)
treat search as a stateless-ish service: snapshots/backups, metrics, and replacement, not “pet servers”

If you’re in a compliance-heavy environment, this is also the boring win: private networking, predictable data flow, and no “please open the internet so the managed thing can talk to the other managed thing” dance.

You still own it, but you’re not forced into a complex cluster if you don’t need one.

A practical note: why vector search changes the bill

Hybrid search isn’t just “keyword + vector”. It’s also CPU + RAM.

Keyword-heavy workloads mostly burn CPU.
Vector-heavy workloads mostly burn memory.
Chunk-level indexing often multiplies both: more rows, more vectors, more metadata, more filters.

On Azure AI Search, that usually shows up as “we need more capacity” (and the bill follows the provisioned units).
On Manticore, it usually shows up as “we need more RAM/CPU” (and you choose the VM size).

Same physics — different pricing model.

Quick note on “maybe Elastic then?”

Elastic is capable, and on Azure it’s a familiar choice. The trade is usually operational: more moving pieces, more knobs, more “cluster care and feeding”.

If you already run it well, cool. If you don’t, and all you want is chunk-level document search that behaves, it can feel like bringing a whole orchestra because you need a violin.

Developer experience (how it feels in the editor)

Area	Azure AI Search	Manticore Search
Query style	REST + JSON	SQL + HTTP JSON
Full-text logic	Service-defined	Explicit, query-level
Vector + text	Managed fusion	Explicit composition
Debugging relevance	Indirect	Direct
Portability	Azure-only	Any environment
Transparency	Low	High

A concrete example: clause-level document search

If you want a stress test that exposes search tradeoffs quickly, this is it: split documents into clauses/sections, index those chunks, then ask people to find specific language under strict filters.

Why it’s unforgiving:

Phrase/proximity really matters. A system that’s merely “similar” will surface lookalikes that waste time.
Filters are not optional. Users will treat them as hard constraints, and they’ll notice when “almost matching” sneaks in.
Trust is fragile. If people can’t tell why a result is #1, they stop trusting search and start working around it.

What it usually turns into (roughly):

each clause becomes a row/document with clause_id, document_id, clause_path (or whatever naming), and the clause text
metadata fields become hard filters (workspace/matter, jurisdiction/region, dates, version, visibility, etc.)
optional: an embedding per clause for the “find me similar language” part
UI pulls the full document separately and shows the clause with a snippet/highlight that’s easy to verify

Full-text baseline (predictable, easy to explain). Use this when people know the wording they’re hunting for:

SELECT clause_id, document_id, WEIGHT()
FROM clauses
WHERE MATCH('"limitation of liability"~3')
  AND jurisdiction = 'AU'
  AND effective_date >= '2022-01-01'
ORDER BY WEIGHT() DESC
LIMIT 10;

Where embeddings fit: they can be great for expanding recall (“find similar language”), but they’re not “thinking”. In practice, semantic search can land in an awkward middle ground: it looks smart at first, then frustrates people because it’s not reliably smart enough.

So here’s the pattern that tends to behave:

If the user types exact-ish keywords → do pure full-text (BM25/WEIGHT()).
If the user types an idea (“cap on liability”, “excluded damages”) → use embeddings to pull candidates, then lock it down with full-text + filters.

Hybrid example (semantic candidates → strict text + metadata → distance-first ordering):

SELECT clause_id, document_id, knn_dist(), WEIGHT()
FROM clauses
WHERE knn(embedding, 50, 'cap on liability and excluded damages')
  AND MATCH('"limitation of liability" | "consequential damages"')
  AND jurisdiction = 'AU'
ORDER BY knn_dist() ASC, WEIGHT() DESC
LIMIT 10;

What this actually does:

knn(...) picks a candidate set by meaning.
MATCH(...) + filters keep it verifiable (you can point at the words on the page).
Results are primarily sorted by vector distance; WEIGHT() refines within that KNN set.

If you need real reasoning, do it after retrieval (e.g., run an LLM over the top N candidates).

This is also where RAG-style workflows fit. Manticore’s RAG support is on the roadmap (see issue #2286) — and by the time you’re reading this, it might already be shipped.

So which one would I pick?

If you want “don’t make me run search infra” and you’re already deep in Azure, Azure AI Search is the obvious choice. You’ll move fast.
If search relevance is a product feature (not a checkbox), and you expect to tune and debug it for months, you’ll probably prefer Manticore. You can be opinionated and precise without fighting managed abstractions.

One slightly unromantic rule: if your team can’t or won’t own search as a system, pick Azure. If your team can own it, pick the option that lets you see what’s going on — which usually means Manticore is the calmer long-term choice.

Inline Stopwords, Exceptions, and Wordforms

Sergey Nikolaev — Thu, 12 Feb 2026 10:30:16 +0000

Manticore Search now supports inline specification of tokenization dictionary settings directly in the CREATE TABLE statement. This enhancement eliminates the need for external files when configuring stopwords, exceptions, wordforms, and hitless words, making table creation more streamlined and deployment-friendly.

New Features

Four new configuration options are now available in RT mode:

stopwords_list - Specify stop words directly in the table definition
exceptions_list - Define tokenization exceptions inline
wordforms_list - Configure word form mappings without external files
hitless_words_list - Set hitless words as part of table creation

All of these options use semicolon (;) as a separator between entries, making them easy to use in SQL and HTTP JSON interfaces.

The Problem They Solve

Traditionally, configuring tokenization dictionaries required creating external files that Manticore would read during table creation. While this approach works well in many scenarios, it presents several challenges:

File Permission Issues

Web applications running under restricted user accounts often struggle to create files in directories that are both:

Writable by the web server process
Readable by the Manticore daemon process

This is particularly problematic in shared hosting environments where web applications run under restricted user accounts (such as in Virtualmin or similar control panel setups), where user home directories are typically only readable by the owner, while system directories may have restrictive permissions.

Sticky Directory Problems

Using system temporary directories (like /tmp) introduces another issue: the sticky bit on these directories can prevent proper cleanup of stopword files. When indexes are frequently rebuilt, orphaned files can accumulate, consuming disk space and creating maintenance headaches.

File Lifecycle Management

When tables are frequently created and destroyed, managing the associated tokenization dictionary files becomes cumbersome. Developers must:

Create the file before table creation
Ensure the file is readable by Manticore
Remember to clean up the file when the table is dropped

This manual process is error-prone and can lead to file system clutter.

The New Options

The new *_list options let you specify tokenization dictionary settings directly in the CREATE TABLE statement. With external files, SHOW CREATE TABLE shows file paths and you maintain dictionary content in separate files; with the inline options, you never create or reference external paths. Dictionary content lives in the DDL (internally it still ends up as files in the table directory, same as with file paths). SHOW CREATE TABLE shows the full dictionary settings inline (e.g., stopwords_list = 'a; the; an'), so the table definition is self-contained in one statement, easier to version control and to copy or share. The table definition is portable across different environments.

Usage Examples

Stopwords

Instead of creating a stopwords file:

-- Old way (requires external file)
CREATE TABLE products(title text, price float) 
stopwords = '/usr/local/manticore/data/stopwords.txt'

You can now specify stopwords inline:

-- New way (no external file needed)
CREATE TABLE products(title text, price float) 
stopwords_list = 'a; the; an; and; or; but'

Exceptions

Exceptions (synonyms) can be defined inline:

CREATE TABLE products(title text, price float) 
exceptions_list = 'AT&T => ATT; MS Windows => ms windows; C++ => cplusplus'

Wordforms

Word form mappings can be specified directly:

CREATE TABLE products(title text, price float) 
wordforms_list = 'walks > walk; walked > walk; walking > walk'

Hitless Words

Hitless words can be configured inline:

CREATE TABLE products(title text, price float) 
hitless_words_list = 'hello; world; test'

Combining Multiple Options

You can combine all these options in a single CREATE TABLE statement:

CREATE TABLE products(title text, price float) 
stopwords_list = 'a; the; an' 
exceptions_list = 'AT&T => ATT' 
wordforms_list = 'walks > walk; walked > walk' 
hitless_words_list = 'hello; world'

When to Use Inline Configuration

Inline configuration is ideal when:

Small to Medium Lists: The lists are reasonably sized (typically under a few hundred entries). For very large dictionaries, external files may still be more practical.
Dynamic Table Creation: Your application programmatically creates and destroys tables, making file management cumbersome.
Restricted File System Access: You're running in an environment with limited file system permissions (shared hosting, containers, etc.).
Simplified Deployment: You want to avoid managing additional files as part of your deployment process.
Frequent Index Rebuilding: Tables are frequently recreated, making file cleanup a maintenance burden.

When External Files Are Better

While inline configuration is convenient, external files remain the better choice in these scenarios:

Large Dictionaries: When you have thousands of entries, external files are more manageable and don't bloat your CREATE TABLE statements.
Shared Dictionaries: If the same dictionary is used across multiple tables, an external file allows you to define it once and reference it from multiple tables, reducing duplication.
Version Control: External files can be easily tracked in version control systems, making it easier to review changes and maintain history.
Dynamic Updates: If you need to update dictionaries without recreating tables, external files can be modified and then use ALTER TABLE <table_name> RECONFIGURE to apply the changes. For RT tables, this makes the new tokenization settings take effect for new documents (existing documents remain unchanged). For plain tables, rotation is required to pick up changes from modified dictionary files.
Complex Formatting: Very complex wordform or exception rules may be easier to edit in a dedicated file with proper formatting and comments.
Legacy Systems: If you already have well-maintained external dictionary files, there's no need to migrate unless you're facing the specific problems that inline configuration solves.

Format Details

Separator

All *_list options use semicolons (;) to separate entries. Spaces around semicolons are normalized, so 'word1; word2' and 'word1 ; word2' are equivalent.

Escaping

If you need to use a semicolon as part of the value itself (not as a separator), escape it with a backslash: \;. For example, if you want to map a source form that contains a semicolon:

exceptions_list = 'test\;value => testvalue; another => mapping'

This creates two mappings:

test;value (with a semicolon) → testvalue
another → mapping

The escaped semicolon (\;) is treated as a literal semicolon character, not as a separator between entries.

Wordforms Format

Wordforms support both > and => as separators:

wordforms_list = 'word1 > form1; word2 => form2'

Exceptions Format

Exceptions use => as the separator between source and destination forms:

exceptions_list = 'source form => destination form'

Note: When using exceptions_list, you may see warnings in the searchd log about mapping token (=>) not found in temporary exception files. These warnings are harmless and can be safely ignored—the exceptions function correctly despite these messages. The warnings occur during internal file processing and don't affect the actual exception mapping behavior.

Example: Stopwords, Wordforms, and Exceptions Together

Here's a practical example using inline stopwords, wordforms, and exceptions on a single table. Wordforms normalize variants to a single form (e.g. "learning" → "learn"); exceptions map shorthand to a normalized form (e.g. "JS" → "javascript") so that both "JS" and "JavaScript" match the same documents. Use lowercase in the exception destination so it matches the token form produced by charset_table.

-- Create a table with inline stopwords, wordforms, and exceptions
CREATE TABLE articles(id bigint, title text)
stopwords_list = 'a; the; an; and; or; but; in; on; at; to; for; of; with'
wordforms_list = 'learning > learn; programming > program; reference > refer; introduction > intro; complete > complet; basics > basic'
exceptions_list = 'JS => javascript; ML => machine learning';

-- Insert test data
INSERT INTO articles VALUES
  (1, 'The Quick Guide to Python Programming'),
  (2, 'A Complete Reference for JavaScript'),
  (3, 'An Introduction to Machine Learning'),
  (4, 'Python Programming Basics'),
  (5, 'Getting Started with JS');

Stopwords: queries with or without stopwords match the same documents.

SELECT * FROM articles WHERE MATCH('python');

id	title
1	The Quick Guide to Python Programming
4	Python Programming Basics

SELECT * FROM articles WHERE MATCH('the python');

id	title
1	The Quick Guide to Python Programming
4	Python Programming Basics

Phrase search: stopwords are skipped for matching but still affect positions (tunable with stopword_step).

SELECT * FROM articles WHERE MATCH('"the quick"');

id	title
1	The Quick Guide to Python Programming

Wordforms: "learn" matches "Learning" via the wordform.

SELECT * FROM articles WHERE MATCH('learn');

id	title
3	An Introduction to Machine Learning

Exceptions: the mapping JS => javascript normalizes "JS" to "javascript" when it appears in text or in the query. Because the destination is lowercase, it matches the token form that charset_table produces for "JavaScript", so both MATCH('JavaScript') and MATCH('JS') return the same rows.

SELECT * FROM articles WHERE MATCH('JavaScript');

id	title
2	A Complete Reference for JavaScript
5	Getting Started with JS

SELECT * FROM articles WHERE MATCH('JS');

id	title
2	A Complete Reference for JavaScript
5	Getting Started with JS

Benefits Summary

No File Management: Eliminates the need to create, manage, and clean up external files
Simplified Deployment: Configuration is part of the table definition, making deployments more straightforward
Permission Independence: No file system permission issues between web server and Manticore processes
Better for Automation: Easier to script and automate table creation
Self-Contained and Self-Documenting: Table configuration is complete in the CREATE TABLE statement, and SHOW CREATE TABLE shows the full dictionary content inline, so definitions are easy to share and version control without managing separate dictionary files

Migration Path

If you're currently using external files, you can easily migrate to inline configuration:

Read your existing file content
Convert the format to use semicolons as separators
Replace the file path with the *_list option in your CREATE TABLE statement

For example, if you have a stopwords.txt file containing:

a
the
an
and

You can convert it to:

stopwords_list = 'a; the; an; and'

Conclusion

The new inline tokenization dictionary configuration options (stopwords_list, exceptions_list, wordforms_list, and hitless_words_list) provide a cleaner, more maintainable way to configure tokenization settings. They're particularly valuable in environments where file management is challenging or when you want to simplify your deployment process and keep table definitions self-contained. While external files remain supported for large dictionaries, inline configuration offers a convenient alternative for most use cases.

Manticore Search 17.5.1

Sergey Nikolaev — Tue, 10 Feb 2026 06:03:44 +0000

Manticore Search 17.5.1 has been released. This maintenance release includes bug fixes, minor improvements, and updated recommended library versions.

Breaking Changes

Please review these if you are upgrading from older versions:

MCL 10.0.0: Added support for DROP CACHE. This updates the interface between the daemon and MCL. Older Manticore Search versions don't support the newer MCL. (Issue #4120)
Percolate query JSON responses now return hit _id and _score as numbers instead of strings, so they now match regular search; this is a breaking change for clients that relied on string type for these fields. (Issue #4019)

Recommended Versions

MCL (Manticore Columnar Library): 10.2.0
Manticore Buddy: 3.41.0

If you follow the official installation guide, you don't need to worry about this as the correct versions will be installed automatically.

New Features and Improvements

Highlights in this release:

The updated MCL adds support for Llama, Qwen, Mistral, Gemma, and other models for auto-embeddings.
Jieba morphology instances are now shared across tables with the same configuration, greatly reducing memory use when many tables use Jieba.
stopwords, wordforms, exceptions, and hitless_words can now be set inline in CREATE TABLE, so tables can be created without external files.

Bug Fixes

Notable fixes in this release:

Fixed JOIN results returning empty or duplicated values when a column was both a string attribute and a stored field; the attribute value is now returned correctly. (Issue #3498)
Fixed joins on JSON string attributes (e.g. j.s) returning no matches; they now work like joins on plain string attributes. (Issue #2559)
Fixed highlight() with html_strip_mode=strip corrupting content by decoding entities and altering tags; original entity form is now preserved. (Issue #1737)
Fixed ALTER TABLE REBUILD SECONDARY failing with failed to rename ... .tmp.spjidx when the table had multiple disk chunks. (Issue #3203)
Fixed distributed queries returning stored fields from the wrong local index when agent tables contain duplicate document IDs. (Issue #4148)
Fixed table rename breaking tables that use external stopwords, wordforms, or exceptions: ATTACH TABLE now migrates these files properly. (Issue #4176)
Fixed MATCH with OR over the same phrase in different fields returning matches from other fields. (Issue #4128)
Fixed ALTER TABLE with table-level settings failing on tables with auto-embeddings; serialization now omits knn_dims when model_name is set. (Issue #4131)

...and many more (47 bug fixes in total). For the complete list, see the Changelog.

Compatibility

Manticore Search 17.5.1 maintains strong backward compatibility with existing data and queries; see the breaking-change notes above.
To upgrade, follow the installation guide.

Need help or want to connect?

Join our Slack
Visit the Forum
Report issues or suggest features on GitHub
Email us at contact@manticoresearch.com

For full details, see the Changelog.

Manticore Search 14.1.0: Force Bigrams and Bug Fixes

Sergey Nikolaev — Wed, 12 Nov 2025 09:50:35 +0000

We're pleased to announce Manticore Search 14.1.0, a release that includes our work for October 2025. This update adds the force_bigrams option for spell correction, replication progress tracking, and various bug fixes.

❤️ Special thanks to @ricardopintottrdata for their contributions on HAVING total counts and filter error fixes, and to @jdelStrother for improving CJK segmentation handling when Jieba support isn't available.

⚠️ Important Replication Update

Version 14.0.0 updated the replication protocol. If you're running a replication cluster, you need to:

Cleanly stop all your nodes
Start the node that was stopped last with --new-cluster, using the manticore_new_cluster tool in Linux
Read about restarting a cluster for more details

New Features and Improvements

Force Bigrams Option

Added a force_bigrams option for fuzzy and autocomplete functionality. This option helps with spell correction for shorter words where trigram matching may not work as well. For example, when correcting "Geroge" to "George", bigrams can provide better matching than trigrams for such transposition cases.

Replication Progress Tracking

Added a progress meter for donor and joiner nodes in replication SST, visible in SHOW STATUS. This provides visibility into replication state synchronization progress.

Additional Improvements

LOCK TABLES support: Added for mysqldump compatibility
Buddy updated to 3.37.0: Various improvements and stability fixes

Bug Fixes

This release includes numerous bug fixes across multiple versions leading up to 14.1.0:

Critical Fixes

Fixed crash with max(ft field) - Resolved a critical crash when using max functions on full-text fields
Fixed empty filter name error - Resolved error when using filters with empty names
Fixed full-text query crashes - Addressed crashes caused by specific full-text query patterns
Fixed "(abc|def)" query handling - Full-text queries with this pattern now work as expected

Query and Search Improvements

Fixed HAVING total counts - Added ability to get total number of results for queries using HAVING
Enhanced CALL SUGGEST - SUGGEST can now use bigrams instead of trigrams when needed, improving spell correction for shorter words
Fixed CJK segmentation - Improved ParseCJKSegmentation when Jieba support isn't available
Added expansion phrase warning - New searchd.expansion_phrase_warning option for better query debugging

Replication and Clustering

Fixed replication transaction handling - Improved key generation and conflict resolution

System and Component Updates

Improved FreeBSD compilation - Fixed native FreeBSD build issues
Enhanced Filebeat compatibility - Added testing for Filebeat version 9.2
Better error handling - Improved error handling for right-joined JSON queries
KNN parameter validation - Added proper validation for KNN parameters

Compatibility

Manticore Search 14.1.0 maintains strong backward compatibility with important considerations:

General Compatibility

Fully compatible with existing data and queries

Replication Cluster Considerations

⚠️ Important: Version 14.0.0 introduced replication protocol changes. If upgrading from pre-14.0.0 versions with replication clusters:

Plan downtime for proper cluster restart procedure
Follow the cluster restart guide carefully
Test the upgrade in a staging environment first

To upgrade, follow the installation guide.

Need help or want to connect?

Join our Slack
Visit the Forum
Report issues or suggest features on GitHub
Email us at contact@manticoresearch.com

For full details, see the Changelog.

Auto Embeddings in Manticore Search: AI-Powered Search Made Simple

Sergey Nikolaev — Tue, 16 Sep 2025 06:54:10 +0000

We're excited to share a new feature that makes building semantic search apps as simple as writing SQL: Auto Embeddings.

With this addition, Manticore Search takes care of embedding generation for you—no extra pipelines, no external services, no hassle.

The Challenge Before

Until now, semantic search often meant wrestling with:

Setting up separate ML pipelines for embedding generation
Managing models and their dependencies
Syncing your app, embedding service, and search engine
Handling vector dimension mismatches and preprocessing
Making sure embeddings are always generated the same way

That overhead is now gone.

What Are Auto Embeddings?

With Auto Embeddings, you just insert text. Manticore automatically:

✨ Generates embeddings with state-of-the-art models

✨ Stores them efficiently in vector indexes

✨ Lets you query in natural language

✨ Hides the complexity so you can focus on features, not infrastructure

How It Works

Build a semantic search app in 3 steps:

1. Create a Table (SQL Example)

CREATE TABLE products (
    title TEXT,
    description TEXT,
    category STRING,
    price INT,
    vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
        MODEL_NAME='sentence-transformers/all-MiniLM-L6-v2'
        FROM='title,description'
);

Configured in one line: Manticore generates embeddings from title and description.

2. Insert Data (SQL Example)

INSERT INTO products(id, title, description, category, price) VALUES
  (1, 'green hiking backpack', 'Lightweight backpack suitable for hiking trails', 'outdoors', 5999),
  (2, 'laptop sleeve', 'Slim padded case for 15-inch laptops', 'electronics', 1999),
  (3, 'travel daypack', 'Compact daypack perfect for light travel or hiking', 'luggage', 3999),
  (4, 'black laptop backpack', 'Spacious backpack with padded laptop compartment', 'electronics', 6900),
  (5, 'mountain hiking bag', 'Durable trail-ready backpack for mountain hikes', 'outdoors', 8950),
  (6, 'everyday backpack', 'Versatile backpack for work, gym and school', 'general', 4900),
  (7, 'trail running shoes', 'Lightweight shoes with great grip for trails', 'footwear', 7500),
  (8, 'camping gear set', 'Complete set for weekend camping adventures', 'outdoors', 12000),
  (9, 'outdoor laptop pack', 'Trail-optimized backpack with laptop sleeve', 'outdoors', 7800),
  (10, 'compact hiking backpack', 'Light and foldable backpack for trail hikes', 'outdoors', 4200),
  (11, 'portable solar charger', 'Foldable solar panel charger for phones and USB devices', 'electronics', 3400),
  (12, 'reusable water bottle', 'Insulated stainless steel bottle keeps drinks cold or hot', 'lifestyle', 2500),
  (13, 'noise-cancelling headphones', 'Over-ear headphones with noise cancellation', 'electronics', 13900),
  (14, 'organic trail mix', 'Healthy mix of nuts and dried fruit, ideal for hikes', 'food', 899),
  (15, 'wireless mouse', 'Compact wireless mouse for laptops and desktops', 'electronics', 1599),
  (16, 'office chair', 'Ergonomic office chair with lumbar support and mesh back', 'furniture', 27900),
  (17, 'notebook and pen set', 'Elegant A5 notebook with smooth-writing pen', 'stationery', 1200),
  (18, 'children\'s adventure book', 'Illustrated storybook about outdoor exploration', 'books', 1299),
  (19, 'mini drone', 'Lightweight drone with HD camera and remote control', 'gadgets', 4599),
  (20, 'wooden puzzle box', 'Challenging mechanical puzzle made of natural wood', 'toys', 1899);

This diverse dataset spans outdoors, electronics, furniture, books, toys, and more. Notice: no vectors needed. All embeddings are generated automatically from the text.

Note: Prices are in cents (e.g., 5999 = $59.99).

3. Search with Natural Language (SQL Example)

SELECT id, title, description, price, knn_dist()
FROM products 
WHERE knn(vector, 5, 'lightweight laptop backpack for trail hiking')
LIMIT 5;

Results:

+------+-------------------------+--------------------------------------------------+-------+------------+
| id   | title                   | description                                      | price | knn_dist() |
+------+-------------------------+--------------------------------------------------+-------+------------+
|    9 | outdoor laptop pack     | Trail-optimized backpack with laptop sleeve      |  7800 | 0.35392243 |
|    1 | green hiking backpack   | Lightweight backpack suitable for hiking trails  |  5999 | 0.53113687 |
|    5 | mountain hiking bag     | Durable trail-ready backpack for mountain hikes  |  8950 | 0.62034285 |
|    4 | black laptop backpack   | Spacious backpack with padded laptop compartment |  6900 | 0.65785009 |
|   10 | compact hiking backpack | Light and foldable backpack for trail hikes      |  4200 | 0.68591022 |
+------+-------------------------+--------------------------------------------------+-------+------------+

The query "lightweight laptop backpack for trail hiking" found the most relevant item first: the "outdoor laptop pack" which combines both laptop and trail features, followed by hiking backpacks and laptop-oriented products.

Pick the Right Model

You can choose different models depending on your needs:

🏠 Local (Hugging Face models) — no API keys, unlimited use
🌐 OpenAI models — best-in-class semantic quality
🚀 Voyage & Jina models — domain- and language-optimized

Hybrid Search & Filtering (SQL Example)

Combine semantic, keyword, and structured filters in one query:

SELECT id, price, highlight()
FROM products
WHERE knn(vector, 7, 'lightweight laptop backpack for trail hiking')
  AND category = 'outdoors'
  AND MATCH('"lightweight laptop backpack for trail hiking"/0.5');

Results:

+------+-------+-----------------------------------------------------------------------------------------------+
| id   | price | highlight()                                                                                   |
+------+-------+-----------------------------------------------------------------------------------------------+
|    9 |  7800 | outdoor <b>laptop</b> pack | <b>Trail</b>-optimized <b>backpack</b> with <b>laptop</b> sleeve |
|    1 |  5999 | green <b>hiking backpack</b> | <b>Lightweight backpack</b> suitable <b>for hiking</b> trails  |
|    5 |  8950 | mountain <b>hiking</b> bag | Durable <b>trail</b>-ready <b>backpack for</b> mountain hikes    |
|   10 |  4200 | compact <b>hiking backpack</b> | Light and foldable <b>backpack for trail</b> hikes           |
+------+-------+-----------------------------------------------------------------------------------------------+

Note: highlight() returns markup (e.g., <b>...</b>).

This powerful combination filters by category (outdoors), ensures semantic relevance through embeddings, requires text-level keyword matches, and highlights the matching terms — all in one query!

Complete HTTP/JSON API Support

Auto Embeddings work seamlessly with Manticore's HTTP/JSON API, providing the same functionality as SQL but through REST endpoints.

Inserting Data via JSON (HTTP/JSON API Example)

Use the /insert endpoint - embeddings are generated automatically:

curl "http://localhost:9308/insert" -H "Content-Type: application/json" \
  -d '{
    "table": "products", 
    "id": 21, 
    "doc": {
      "title": "wireless headphones", 
      "description": "Bluetooth headphones with noise cancellation", 
      "category": "electronics", 
      "price": 15900
    }
  }'

Response:

{
  "table": "products",
  "id": 21,
  "created": true,
  "result": "created",
  "status": 201
}

Bulk Inserts with Auto Embeddings (HTTP/JSON API Example)

Insert multiple documents efficiently using /bulk:

curl "http://localhost:9308/bulk" -H "Content-Type: application/x-ndjson" \
  --data-raw $'{"insert": {"table": "products", "id": 22, "doc": {"title": "gaming laptop", "description": "High-performance laptop for gaming and work", "category": "electronics", "price": 159900}}}
{"insert": {"table": "products", "id": 23, "doc": {"title": "smartphone", "description": "Latest flagship smartphone with 5G", "category": "electronics", "price": 89900}}}
{"insert": {"table": "products", "id": 24, "doc": {"title": "tablet computer", "description": "Lightweight tablet for work and entertainment", "category": "electronics", "price": 49900}}}'

Response:

{
  "items": [
    {
      "bulk": {
        "table": "products",
        "_id": 24,
        "created": 3,
        "deleted": 0,
        "updated": 0,
        "result": "created",
        "status": 201
      }
    }
  ],
  "current_line": 3,
  "skipped_lines": 0,
  "errors": false,
  "error": ""
}

The bulk operation successfully inserted 3 documents with auto-generated embeddings.

Semantic Search via JSON (HTTP/JSON API Example)

Search with natural language queries using /search:

curl "http://localhost:9308/search" -H "Content-Type: application/json" \
  -d '{
    "table": "products",
    "_source": ["title"],
    "size": 5,
    "knn": {
      "field": "vector",
      "query": "outdoor hiking adventure",
      "k": 3
    }
  }'

Response:

{
  "took": 8,
  "timed_out": false,
  "hits": {
    "total": 24,
    "total_relation": "eq",
    "hits": [
      {
        "_id": 18,
        "_score": 1,
        "_knn_dist": 0.75467718,
        "_source": {
          "title": "children's adventure book"
        }
      },
      {
        "_id": 1,
        "_score": 1,
        "_knn_dist": 0.83226496,
        "_source": {
          "title": "green hiking backpack"
        }
      },
      {
        "_id": 5,
        "_score": 1,
        "_knn_dist": 0.89348459,
        "_source": {
          "title": "mountain hiking bag"
        }
      },
      {
        "_id": 10,
        "_score": 1,
        "_knn_dist": 0.92611158,
        "_source": {
          "title": "compact hiking backpack"
        }
      },
      {
        "_id": 3,
        "_score": 1,
        "_knn_dist": 0.98721427,
        "_source": {
          "title": "travel daypack"
        }
      }
    ]
  }
}

The query "outdoor hiking adventure" found the most relevant match to be the "children's adventure book" (0.754 distance), followed by hiking-related backpacks. This shows how semantic search can find conceptually related items beyond just literal keyword matches.

Filtering and Hybrid Search via JSON (HTTP/JSON API Example)

Combine semantic search with traditional filters:

curl "http://localhost:9308/search" -H "Content-Type: application/json" \
  -d '{
    "table": "products",
    "_source": ["title", "price"],
    "size": 5,
    "knn": {
      "field": "vector", 
      "query": "technology electronic device",
      "k": 5,
      "filter": {
        "range": {"price": {"gte": 15000}}
      }
    }
  }'

Response:

{
  "took": 10,
  "timed_out": false,
  "hits": {
    "total": 5,
    "total_relation": "eq",
    "hits": [
      {
        "_id": 24,
        "_score": 1,
        "_knn_dist": 1.31113040,
        "_source": {
          "title": "tablet computer",
          "price": 49900
        }
      },
      {
        "_id": 23,
        "_score": 1,
        "_knn_dist": 1.56920886,
        "_source": {
          "title": "smartphone",
          "price": 89900
        }
      },
      {
        "_id": 22,
        "_score": 1,
        "_knn_dist": 1.59042466,
        "_source": {
          "title": "gaming laptop",
          "price": 159900
        }
      },
      {
        "_id": 16,
        "_score": 1,
        "_knn_dist": 1.84979212,
        "_source": {
          "title": "office chair",
          "price": 27900
        }
      },
      {
        "_id": 21,
        "_score": 1,
        "_knn_dist": 1.88567829,
        "_source": {
          "title": "wireless headphones",
          "price": 15900
        }
      }
    ]
  }
}

The search for "technology electronic device" with price filtering (≥$150) correctly prioritized electronics items and excluded lower-priced products like hiking backpacks and smaller electronics. Notice how "tablet computer" ranks highest due to its strong semantic match to the query.

Direct Vector vs Auto-Embedded Text Queries

The HTTP/JSON API supports both:

Auto-embedded text queries: "query": "outdoor hiking adventure" (auto-embedded)
Direct vector queries: "query": [0.1, 0.2, 0.3, ...] (pre-computed vector)

This flexibility allows you to mix auto-generated embeddings with custom vectors in the same application.

OpenAI Integration (OpenAI API Example)

For even better semantic understanding, you can use OpenAI's embedding models:

-- Create table with OpenAI embeddings
CREATE TABLE products_openai (
  title TEXT,
  description TEXT,
  category string,
  price INT,
  vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='openai/text-embedding-ada-002'
    FROM='title, description'
    API_KEY='your-openai-api-key'
);

-- Insert data (embeddings generated via OpenAI API)
INSERT INTO products_openai(title, description, category, price) VALUES
  ('smartphone device', 'latest mobile technology with advanced features', 'electronics', 79900),
  ('laptop computer', 'portable workstation for developers and professionals', 'electronics', 129900);

-- Search with natural language
SELECT id, title, description, knn_dist()
FROM products_openai 
WHERE knn(vector, 2, 'mobile phone technology');

Results:

+---------------------+-------------------+-------------------------------------------------------+------------+
| id                  | title             | description                                           | knn_dist() |
+---------------------+-------------------+-------------------------------------------------------+------------+
| 2309215617435041807 | smartphone device | latest mobile technology with advanced features       | 0.20333229 |
| 2309215617435041808 | laptop computer   | portable workstation for developers and professionals | 0.40197325 |
+---------------------+-------------------+-------------------------------------------------------+------------+

OpenAI's models excel at understanding nuanced relationships — "mobile phone technology" correctly identified the smartphone as much more relevant than the laptop.

Built for Production

⚡ Fast: HNSW indexing, optional quantization, optimized storage
🛡️ Reliable: multiple model providers, empty-vector handling
🔧 Flexible: embed from any field(s) you choose

Use Cases

Auto Embeddings make it easy to build:

🛍️ E-commerce search: "waterproof hiking boots" → finds relevant products
📚 Document discovery: "contracts about data privacy" → surfaces legal docs
🎵 Content recommendations: "upbeat music for workouts" → matches by vibe
🏠 Real estate search: "cozy apartments near parks" → finds lifestyle-fit homes

More Real-World Examples

Let's see Auto Embeddings in action with different search scenarios:

Finding Work & Productivity Items

SELECT id, title, description, price, knn_dist()
FROM products 
WHERE knn(vector, 3, 'work productivity office')
LIMIT 3;

Results:

+------+----------------------+----------------------------------------------------------+-------+------------+
| id   | title                | description                                              | price | knn_dist() |
+------+----------------------+----------------------------------------------------------+-------+------------+
|   24 | tablet computer      | Lightweight tablet for work and entertainment            | 49900 |   1.306459 |
|   16 | office chair         | Ergonomic office chair with lumbar support and mesh back | 27900 | 1.44871426 |
|   17 | notebook and pen set | Elegant A5 notebook with smooth-writing pen              |  1200 | 1.48466742 |
+------+----------------------+----------------------------------------------------------+-------+------------+

The search understood "work productivity office" and returned office furniture, stationery, and work-appropriate gear.

Smart Category Filtering

Sometimes semantic search is too broad. Let's search for "usb charger for outdoor camping":

SELECT id, title, description, price, knn_dist()
FROM products 
WHERE knn(vector, 5, 'usb charger for outdoor camping');

Top results include many items: solar charger (0.888), outdoor packs (1.139), hiking gear (1.213), etc.

But when we add category filtering:

SELECT id, highlight()
FROM products 
WHERE knn(vector, 5, 'usb charger for outdoor camping')
  AND category = 'electronics'
  AND MATCH('"usb charger for outdoor camping"/0.5')
LIMIT 3;

Precise result:

+------+-------------------------------------------------------------------------------------------------------+
| id   | highlight()                                                                                           |
+------+-------------------------------------------------------------------------------------------------------+
|   11 | portable solar <b>charger</b> | Foldable solar panel <b>charger for</b> phones and <b>USB</b> devices |
+------+-------------------------------------------------------------------------------------------------------+

Note: highlight() returns markup (e.g., <b>...</b>). Bold in the table is for readability.

The combination of semantic understanding + category filtering + keyword matching gave us exactly what we wanted!

Finding Fun & Creative Items

SELECT id, title, description, price, knn_dist()
FROM products 
WHERE knn(vector, 3, 'fun creative play toys')
LIMIT 3;

Results:

+------+---------------------------+----------------------------------------------------+-------+------------+
| id   | title                     | description                                        | price | knn_dist() |
+------+---------------------------+----------------------------------------------------+-------+------------+
|    8 | camping gear set          | Complete set for weekend camping adventures        | 12000 | 1.30462146 |
|   20 | wooden puzzle box         | Challenging mechanical puzzle made of natural wood |  1899 |   1.305056 |
|   18 | children's adventure book | Illustrated storybook about outdoor exploration    |  1299 | 1.47192979 |
+------+---------------------------+----------------------------------------------------+-------+------------+

Auto Embeddings understood the concept of "fun creative play" and found adventure gear, puzzles, and children's books—all items that relate to creativity and play!

Behind the Scenes

Auto Embeddings rely on:

Sentence Transformers for semantic understanding
HNSW for fast similarity search
Smart caching for efficient inference
Multi-provider APIs for flexibility

Try It Today

As you've seen from our examples, Auto Embeddings deliver powerful semantic search capabilities with minimal setup. Whether you're building:

E-commerce platforms with natural language product search
Content management systems with intelligent document discovery
Recommendation engines that understand user intent
Knowledge bases with semantic question answering

Auto Embeddings remove the hardest part — managing embeddings — so you can focus on building great features that users love.

🚀 Ready to transform your search experience?

👉 Download Manticore Search and start building with Auto Embeddings today.

📚 Check out the KNN search documentation for detailed guides.

💬 Join our Slack community to share your success stories.

Questions or feedback? Join our community forum or follow us on Twitter.

Manticore Search 13.11.0: Introducing Auto Embeddings and Enhanced AI Search

Sergey Nikolaev — Mon, 15 Sep 2025 14:36:44 +0000

We're excited to announce the August 2025 release of Manticore Search 13.11.0, a major update featuring Auto Embeddings — our new way of making AI-powered semantic search simple and efficient. This version also includes bug fixes, and several improvements.

🚀 Auto Embeddings: AI Search Made Easy

The highlight of Manticore Search 13.11.0 is Auto Embeddings — a game-changing feature that makes semantic search as easy as SQL. No need for external services or complex pipelines: just insert text and search with natural language.

What Auto Embeddings Offer:

✨ Automatic embedding generation from your text

✨ Natural language queries that understand meaning, not just keywords

✨ Support for multiple models (OpenAI, Hugging Face, Voyage, Jina)

✨ Smooth integration with SQL and JSON APIs

Quick Example

-- Create table with auto-embeddings
CREATE TABLE products (
    title TEXT,
    description TEXT,
    vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
        MODEL_NAME='sentence-transformers/all-MiniLM-L6-v2'
        FROM='title,description'
);

-- Insert data (embeddings generated automatically)
INSERT INTO products(id, title, description) VALUES
  (1, 'wireless headphones', 'Bluetooth headphones with noise cancellation'),
  (2, 'hiking backpack', 'Lightweight backpack for outdoor adventures');

-- Search with natural language
SELECT id, title
FROM products 
WHERE knn(vector, 3, 'portable audio device for music');

Results:

+------+---------------------+
| id   | title               |
+------+---------------------+
|    1 | wireless headphones |
...
+------+---------------------+

Here, semantic search correctly matched "wireless headphones" with the phrase "portable audio device for music," even though no keywords overlapped.

Learn More

Want a full deep dive? Check out our dedicated article: Introducing Auto Embeddings: AI-Powered Search Made Simple

Other Improvements

Configuration

Boolean Simplify Support: Added boolean_simplify option for faster query processing
System Optimization: Sysctl config now auto-increases vm.max_map_count for large datasets
Package Management: RPM packages no longer own /run directory for better compatibility

Bug Fixes

Fixed scroll option with large 64-bit IDs
Fixed KNN crashes when using filter trees
Fixed /sql endpoint behavior (removed unsupported SHOW VERSION)
Fixed duplicate ID handling in columnar mode
Fixed crashes with joined queries using multiple facets
Fixed delete/update commits in bulk transactions
Fixed crashes when joining on non-columnar string attributes

System & Integration

Updated Windows installer script
Fixed local time zone detection on Linux
Improved JDBC+MySQL driver compatibility with transaction_read_only
Enhanced error reporting across components
Improved master-agent communication for embeddings

Compatibility

Manticore Search 13.11.0 is fully backward compatible:

No breaking changes in standard use cases
Smooth upgrades from 13.x versions
Auto Embeddings work alongside current search features
APIs are extended, not replaced

Everything is designed to work seamlessly with your existing data and queries.

Upgrade

To upgrade, follow the installation guide.

🚀 Ready to try Auto Embeddings? Start with the documentation.

Need help or want to connect?

Join our Slack
Visit the Forum
Report issues or suggest features on GitHub
Email us at contact@manticoresearch.com

For full details, see the Changelog.

DEV Community: Sergey Nikolaev

Prepared statements in Manticore Search

Why Use Prepared Statements?

How They Work

Parameter Placeholders: ? & ?VEC?

Example: prepared statements in PHP

Important Considerations & Limitations

Conclusion

KNN prefiltering in Manticore Search

The problem with postfiltering

What prefiltering does differently

Naive prefiltering and where it falls short

How Manticore solves it: ACORN-1

Automatic brute-force fallback

When to use postfiltering instead

Forcing brute-force

Summary

Hybrid search in Manticore Search

What is hybrid search?

How hybrid search fits into modern search pipelines

When should you use it?

How it works

Why RRF?

Why not just use one or the other?

Getting started

Full control: explicit MATCH + KNN

Tuning

Multi-vector fusion

Conclusion

Manticore Search 25.0.0

Upgrade Notes

Packaging Simplified

Highlights

Hybrid search is now a first-class option

Better vector search with KNN prefiltering

Faster RT maintenance with parallel chunk merging

Easier application integration with prepared statements

S3-compatible backup and restore

Auto-embeddings keep improving

Other Notable Improvements

Why 25.0.0 Matters

Need help or want to connect?

MCP-Manticore: Let Your AI Assistant Write Manticore Queries for You

Introduction

Two Ways This Helps You

The Problem: AI Without Context

Example: Creating a Table with Auto-Embeddings

The Solution: MCP-Manticore

Real Examples: With and Without MCP

Example 1: Schema Creation

Example 2: Semantic Search with Auto-Embeddings

Example 3: Fuzzy Search (Typo Tolerance)

Key Features

Intelligent Documentation Lookup

Schema-Aware Query Building

Safe Query Execution

Multiple Transport Options

Tutorial: Setting Up MCP-Manticore

Step 1: Ensure UV is Installed

Step 2: Configure Environment Variables (Optional)

Step 3: Add to Your MCP Client

Step 4: Verify Connection

Configuration Reference

The Future: Agents That Install Themselves

Conclusion

Manticore Search on Microsoft Azure: DX1's Story

Context

DX1 in One Paragraph

Search That Customers Actually Enjoy Using

Why DX1 Chose Manticore Search

Deployment on Azure VMs

Performance, Memory, and Scale

Day-to-Day Operations

Recommendation

Conclusion

Talk to Us About Migrating to Manticore

Azure AI Search vs Manticore Search

Where “generic search” stops working

Two ways to solve it

Cost comparison: managed vs self-hosted

Parameter Placeholders: `?` & `?VEC?`