Forem: Sergey Nikolaev

Monitor Manticore Search in Grafana with One Command

Sergey Nikolaev — Wed, 08 Apr 2026 02:27:24 +0000

The most annoying kind of incident is when database doesn’t go down completely - it just gets slower.

Users start noticing it right away. Complaints come in. Everything is technically still running, but clearly something is off.

And that is usually the hardest part: not noticing the problem, but figuring out what is actually happening.

When everything looks fine, but search is still slow

Let’s take a pretty normal scenario.

Search starts slowing down. It is not crashing. It is not returning obvious errors. The service is up. From the outside, nothing looks broken in a dramatic way.

But users can feel it.

So you open your monitoring:

CPU looks fine.
Average latency does not look too bad.
No obvious alerts.

At first glance, nothing really explains the slowdown.

So you keep digging...

You check the queue. Nothing jumps out immediately.
You look at worker usage. They are busy, but not in a way that tells you much on its own.
You check the logs. Still nothing obvious.

And after a while you get to that frustrating point where you realize you have already checked the usual things, and you still do not know where the problem is.

Each metric, by itself, looks more or less okay. But together, the system is clearly degrading.

So now you are no longer following a clear line of investigation. You are just checking everything you can think of and hoping the pattern shows up.

Meanwhile, time is passing.

What was actually going on

A couple of hours later, the picture finally starts to make sense.

It turns out:

the request queue has been slowly growing;
workers have been sitting near 100% utilization;
one heavy query keeps blocking execution from time to time;
p99 latency is much worse than the average suggests;
and one of the nodes restarted recently.

So the signals were there all along.

The problem was that they were scattered across different places, and it took too long to connect them into one clear story.

The solution: see the whole picture right away

Instead of spending hours piecing all of that together by hand, it is much better to have one place where the important signals are already visible.

That is why we put together a ready-to-use dashboard for Manticore Search that starts with a single Docker command. It comes with Grafana, Prometheus, a preconfigured data source, and built-in alerts.

docker run -p 3000:3000 manticoresearch/dashboard

Environment variables

The container supports two environment variables:

MANTICORE_TARGETS - comma-separated list of Manticore Search instances (default: localhost:9308)
GF_AUTH_ENABLED - set to true to enable Grafana login (by default, anonymous admin access is enabled)

Example:

docker run -p 3000:3000 \
  -e MANTICORE_TARGETS=your-host:9308 \
  manticoresearch/dashboard

If you monitor multiple nodes, pass them as a comma-separated list:

docker run -p 3000:3000 \
  -e MANTICORE_TARGETS=node1:9308,node2:9308,node3:9308 \
  manticoresearch/dashboard

If Manticore is running on a remote server

By default, the dashboard expects Manticore at localhost:9308. If your instance is running on a remote machine, the simplest option is SSH port forwarding:

ssh -L 9308:localhost:9308 user@your-server

After that, local connections to localhost:9308 will be forwarded to the remote server, so the dashboard can connect without additional changes.

A minute later, you have a usable overview of your system.

Not just a pile of graphs, but a dashboard that helps you quickly answer the questions you actually care about when something feels wrong.

You can see queue growth, worker saturation, latency, process state, and query behavior in one place, instead of bouncing between tools and trying to stitch the story together in your head.

What the dashboard shows

The value here is not that there are a lot of panels. The value is that the panels answer the right questions quickly.

The first place to look is the overall system view:

This gives you the basic picture right away:

is the service up;
has it restarted recently;
is there queue pressure;
are workers already under load.

If this row looks healthy, maybe the issue is narrow and local. If it does not, you know right away that the system is under real pressure.

Then you move to load and query behavior:

This is where you can quickly see:

whether work is starting to pile up;
whether workers are saturated;
whether latency is getting worse, especially p95 and p99;
whether one slow thread is causing a disproportionate amount of trouble.

And if you need more context, you can drill down into the rest of the dashboard:

cluster state:

tables and data:

At that point, you are no longer looking at disconnected metrics. You are looking at the system as a whole.

Why this matters

In the kind of situation that used to cost you a couple of hours just to understand, now you can usually spot the direction in a few minutes.

You can see that the queue is growing.
You can see that workers are pinned.
You can see that p99 is climbing.
You can see that one node restarted.
You can see that one query is probably doing most of the damage.

That does not mean the dashboard magically fixes the issue for you.

What it does do is remove the slowest part of the whole process: figuring out where to look.

And in practice, that is often the difference between spending two hours trying to understand the incident and spending five minutes getting to the real problem.

Parallel chunk merging in Manticore Search

Sergey Nikolaev — Tue, 07 Apr 2026 03:52:38 +0000

Starting from Manticore Search 24.4.0, RT table compaction has a more capable execution model. Instead of merging chunk pairs one-by-one in a serial flow, optimization now supports two important improvements:

disk chunk merges can run in parallel
each merge job can merge more than two chunks at once
parallel_chunk_merges: how many RT disk chunk merge jobs may run at the same time
merge_chunks_per_job: how many RT disk chunks a single job can merge in one pass

The compaction docs were also updated to describe optimization as an N-way merge handled by a background worker pool rather than a single serial merge thread.

Why this matters

For RT workloads, the interesting number is often not just how fast you can insert documents, but how long it takes until compaction catches up and the table returns to its target chunk count.

That is especially noticeable when:

you ingest data at a sustained rate
optimize_cutoff is low enough that merges kick in early
you wait for compaction to finish before considering the load fully complete

This matters most in two common cases:

you are doing an initial bulk upload into a real-time table and want the table not just searchable, but already compacted to its steady state before putting more pressure on it
you regularly ingest large batches and want each batch to finish cleanly before the next one arrives

The table is searchable before compaction finishes, but "fully searchable" and "fully optimized" are not the same thing. A higher chunk count can still matter if you care about keeping the table close to its target shape, limiting background merge work before the next ingest wave, or reducing the window where storage is busy with post-load compaction.

To show the difference, we loaded 10 million documents into an RT table. Each document contains:

id bigint
name text with generated text between 10 and 100 words
type int

The table was created with:

CREATE TABLE test(id bigint, name text, type int) optimize_cutoff='16'

So the target was to compact the table back down to roughly 16 disk chunks.

For the benchmark we used manticore-load, our load generation and benchmarking tool. It is useful for reproducing scenarios like this, stress-testing ingestion, and comparing configuration changes without building custom scripts every time.

The data was loaded with:

manticore-load \
  --cache-gen-workers=5 \
  --drop \
  --batch-size=1000 \
  --threads=5 \
  --total=10000000 \
  --init="CREATE TABLE test(id bigint, name text, type int) optimize_cutoff='16'" \
  --load="INSERT INTO test(id,name,type) VALUES(<increment>,'<text/10/100>',<int/1/100>)" \
  --wait

Before: one merge job, two chunks at a time

With the old behavior forced explicitly:

mysql -P9306 -h0 -e "set global parallel_chunk_merges=1; set global merge_chunks_per_job=2"

the run looked like this:

merging started at 14 seconds, when about 1.8M documents had been inserted
all 10M documents were loaded after 1 minute 18 seconds
at that point the data was already fully searchable
compaction kept running in the background until 3 minutes 23 seconds

At 01:18, the table still had more than 50 chunks. Near the end of loading the status looked like:

17:14:50  01:17     98%         133      128.4K   21%     5          53        1         4.22GB      9.9M
17:14:51  01:18     100%        131      310.9K   15%     1          53        1         4.27GB      10.0M
...
17:16:55  03:22     100%        0        49.4K    4%      1          17        1         4.27GB      10.0M
...
Total time:       03:23

This is the classic pattern of a healthy ingest pipeline followed by a long merge tail.

After: parallel merges plus larger merge jobs

With the new settings:

mysql -P9306 -h0 -e "set global parallel_chunk_merges=3; set global merge_chunks_per_job=5"

the same workload finished much faster:

merging again started at about 14 seconds
all 10M documents were again loaded after about 1 minute 18 seconds
full compaction finished after only 1 minute 31 seconds

The end of the run looked like this:

17:19:22  01:17     99%         127      127.9K   28%     6          26        1         4.22GB      9.9M
17:19:23  01:18     100%        132      1883.8K  17%     1          23        1         4.25GB      10.0M
...
17:19:36  01:31     100%        0        110.2K   3%      1          17        1         4.25GB      10.0M
...
Total time:       01:31

What changed in practice

The ingest phase itself stayed roughly the same:

old settings: 1:18 to load all data
new settings: 1:18 to load all data

The big gain came from post-ingest compaction:

old settings: about 2:05 of additional merge time after loading finished
new settings: about 0:13 of additional merge time after loading finished

That is roughly:

55% lower total time overall, from 3:23 down to 1:31
about 90% less merge tail after the last document was inserted

Chunk pressure during ingest was much lower too. Near the end of loading:

old settings: 53 chunks
new settings: 23 chunks

So the improvement is not just that compaction finishes sooner. It also keeps the chunk count under control much more aggressively while data is still being inserted.

What about the new defaults?

On this server, with the new default settings and no explicit tuning at all, the same workload finished in:

Total time:       01:57

That already cuts the old 03:23 result substantially, while still leaving room for additional tuning with:

parallel_chunk_merges
merge_chunks_per_job

In other words, the new defaults already improve the out-of-the-box experience, and systems with enough I/O headroom can push compaction even further by increasing both settings carefully.

Broader benchmark results: row-wise and columnar storage

The 10M-document example above shows the mechanics clearly, but the larger picture is even more interesting. In a wider test matrix we measured the combined load + optimize time for both row-wise and columnar storage across multiple values of:

parallel_chunk_merges
merge_chunks_per_job

The headline result is that, in some cases, tuning these settings can reduce total load + optimize time by:

up to 4.6x for row-wise storage
up to 6.8x for columnar storage

Here is the best-vs-worst picture from that test set:

Storage	Best settings	Best time	Slowest settings	Slowest time	Improvement
Row-wise	`parallel_chunk_merges=4`, `merge_chunks_per_job=5`	14:35	`parallel_chunk_merges=1`, `merge_chunks_per_job=2`	67:15	4.61x
Columnar	`parallel_chunk_merges=4`, `merge_chunks_per_job=5`	15:10	`parallel_chunk_merges=1`, `merge_chunks_per_job=2`	99:14	6.80x

There is also a useful tuning pattern in the full results:

the best runs for both storage modes clustered around parallel_chunk_merges=4..5
the best runs also clustered around merge_chunks_per_job=4..5
the slowest results were consistently at parallel_chunk_merges=1 with merge_chunks_per_job=2

In other words, the old serial two-chunk pattern is not just a little slower. On large workloads it can become dramatically slower, especially with columnar storage.

How to think about the two settings

The new docs describe two separate levers:

parallel_chunk_merges increases how many merge jobs can run at once
merge_chunks_per_job increases how many chunks each job can consume

Lower merge_chunks_per_job values make it easier to schedule more jobs in parallel because each job consumes fewer chunks from the available pool. If a table has many chunks waiting to be compacted, smaller jobs leave more independent chunks available for other workers, so the scheduler can keep several merges active at once. Higher values reduce the total number of merge steps, but each job becomes heavier and grabs a larger portion of the available chunks, which can leave less room for concurrent jobs.

The right balance depends on your storage and workload, but the benchmark above shows that combining both approaches can dramatically reduce the time spent waiting for RT chunk compaction to finish.

Takeaway

If your RT workloads spend too long waiting for chunk compaction after bulk inserts, the new parallel merge model changes that equation significantly.

On this 10M-document test with optimize_cutoff=16:

Mode	Searchable at	Fully optimized at
Old settings: `parallel_chunk_merges=1`, `merge_chunks_per_job=2`	1:18	3:23
New defaults	1:18	1:57
Tuned new settings: `parallel_chunk_merges=3`, `merge_chunks_per_job=5`	1:18	1:31

the time until all data became searchable stayed the same
the time until chunk compaction completed dropped from 3:23 to 1:31
even the new defaults reduced the total time to 1:57

This is exactly the kind of improvement that matters for operational RT indexing. The data is searchable as soon as it is loaded, and that point stayed about the same in both runs. The difference is what happens after that: how long the server keeps spending time compacting chunks in the background before the table returns to its target shape. If your workflow depends on the table becoming compact again before the next heavy ingest, before a maintenance window closes, or before you hand the system over to a search workload that should run with fewer chunks and less background merge pressure, the improvement is substantial.

S3 Streamable Backup: Direct-to-Cloud Backups for Manticore Search

Sergey Nikolaev — Mon, 06 Apr 2026 08:24:45 +0000

Since we introduced the backup tool in Manticore Search 6, backing up your data has become significantly easier. But we kept hearing the same question: "What about cloud storage?" Today, we're excited to announce that manticore-backup now supports S3-compatible storage with streaming uploads — no intermediate files, no local disk space headaches, just direct-to-cloud backups.

The Problem with Traditional Backups

When you're running Manticore Search in production, your datasets can grow quickly. Backing up to local storage has its limitations:

Disk space constraints: You need free space equal to your backup size on the same machine
Manual transfer steps: Backup locally, then upload to cloud storage
Time overhead: The copy-then-upload dance doubles your backup window
Complexity: Scripting reliable uploads with resume capability, encryption, and error handling

Streamable S3 Backup: How It Works

The new S3 storage support streams your backup data directly to S3-compatible storage. Here's what happens under the hood:

No intermediate files: Data streams from Manticore straight to S3
Automatic multipart uploads: Large files are automatically chunked and uploaded in parallel
Built-in encryption: SSE-S3 encryption is enabled by default for AWS S3 (configurable for other providers)
Compression support: Optional zstd compression reduces transfer time and storage costs
Manifest-based restore: No s3:ListBucket permission required for restores

Supported Storage Providers

We've tested with AWS S3, MinIO, and Cloudflare R2, but any S3-compatible storage should work. The implementation uses the standard AWS SDK for PHP, so if it speaks the S3 API, it should work.

Usage

Using S3 backup is as simple as changing your destination path:

CLI

# Set your credentials
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1

# Backup to S3
manticore-backup --config=/etc/manticore/manticore.conf --backup-dir=s3://my-bucket/manticore-backups

# With custom endpoint (MinIO, Wasabi, etc.)
export AWS_ENDPOINT_URL=https://minio.example.com
manticore-backup --config=/etc/manticore/manticore.conf --backup-dir=s3://my-bucket/backups

Environment Variables

Variable	Description
`AWS_ACCESS_KEY_ID`	Your S3 access key
`AWS_SECRET_ACCESS_KEY`	Your S3 secret key
`AWS_REGION`	S3 region (e.g., `us-east-1`)
`AWS_ENDPOINT_URL`	Custom endpoint for S3-compatible storage
`AWS_S3_ENCRYPTION`	Set to `0` to disable SSE-S3 encryption (for MinIO/custom endpoints)

Performance Considerations

S3 streaming backup performance depends primarily on your network bandwidth and the S3 provider's upload speeds. Unlike local disk backups where you're limited by disk I/O, S3 backups are network-bound. The key advantage is eliminating the "write locally, then upload" overhead — data streams directly from Manticore to S3 without touching the local filesystem.

For optimal performance:

Ensure adequate upload bandwidth to your S3 endpoint
Consider using compression (--compress) to reduce data transfer
Multipart uploads are automatic for files over 5MB, improving reliability for large datasets

Restore from S3

Restoring works seamlessly too. The tool downloads files to a temporary directory first, then performs the restore:

# List available backups
manticore-backup --backup-dir=s3://my-bucket/manticore-backups --list

# Restore a specific backup
manticore-backup --config=/etc/manticore/manticore.conf --backup-dir=s3://my-bucket/manticore-backups --restore=backup-20250115120000

Required S3 Permissions

For backup:

s3:PutObject
s3:PutObjectAcl (if using ACLs)

For listing backups:

s3:ListBucket

For restore:

s3:GetObject

Note: While listing backups requires s3:ListBucket, restoring a specific backup does not. If you know the backup folder name (e.g., backup-20250115120000), you can restore directly using --restore with just s3:GetObject permission. The manifest file tracks all backup contents, so no directory listing is needed.

Use Cases

Cloud-Native Deployments

Running Manticore in Kubernetes or Docker? S3 backup fits naturally into cloud-native workflows:

# Kubernetes CronJob example
apiVersion: batch/v1
kind: CronJob
metadata:
  name: manticore-backup
spec:
  schedule: "0 2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: manticoresearch/manticore:latest
            command:
            - manticore-backup
            - --config=/etc/manticore/manticore.conf
            - --backup-dir=s3://my-backup-bucket/manticore
            env:
            - name: AWS_ACCESS_KEY_ID
              valueFrom:
                secretKeyRef:
                  name: s3-credentials
                  key: access-key
            - name: AWS_SECRET_ACCESS_KEY
              valueFrom:
                secretKeyRef:
                  name: s3-credentials
                  key: secret-key
          restartPolicy: OnFailure

Disaster Recovery

Store backups in a different region or even a different cloud provider:

# Primary backup to local S3-compatible storage
export AWS_ENDPOINT_URL=https://minio.internal.company.com
manticore-backup --backup-dir=s3://backups-primary/manticore

# Secondary backup to AWS S3 for DR
unset AWS_ENDPOINT_URL
export AWS_REGION=eu-west-1
manticore-backup --backup-dir=s3://company-dr-backups/manticore

Reducing Local Storage Requirements

For large datasets, local backup storage can be expensive. With S3 streaming:

No need to provision large backup volumes
Pay only for the S3 storage you use
Lifecycle policies can automatically move old backups to cheaper storage classes

Technical Details

Streaming Architecture

The S3 storage implementation uses a streaming approach:

File-by-file streaming: Each table file is read and uploaded as a stream
Automatic multipart: Files over 5MB automatically use multipart upload for reliability
Compression on-the-fly: If enabled, zstd compression happens during the stream
Checksum verification: Each file is checksummed to ensure integrity

Storage Interface

The S3 support is built on a new StorageInterface that abstracts storage operations. This means:

Local filesystem and S3 share the same code path
Future storage backends (GCS, Azure Blob) can be added easily
Consistent behavior regardless of storage type

Migration from Local Backups

Already using local backups? Migration is straightforward:

Set up your S3 credentials
Change --backup-dir from /local/path to s3://bucket/path
That's it! The same commands work exactly the same way

Your existing local backups remain accessible, and you can gradually transition to S3 or maintain both for redundancy.

Conclusion

S3 streamable backup brings Manticore Search backup capabilities to the cloud era. Whether you're running in a cloud-native environment, need cross-region disaster recovery, or simply want to reduce local storage overhead, direct-to-S3 streaming makes backups simpler and more efficient.

The feature is available now in manticore-backup. Check out the documentation for more details, and let us know what you think!

Ready to try it? Install Manticore Search and start backing up to S3 today. Questions or feedback? Join us on Slack or GitHub.

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.

Forem: Sergey Nikolaev

Monitor Manticore Search in Grafana with One Command

When everything looks fine, but search is still slow

What was actually going on

The solution: see the whole picture right away

Environment variables

If Manticore is running on a remote server

What the dashboard shows

Why this matters

Parallel chunk merging in Manticore Search

Why this matters

Before: one merge job, two chunks at a time

After: parallel merges plus larger merge jobs

What changed in practice

What about the new defaults?

Broader benchmark results: row-wise and columnar storage

How to think about the two settings

Takeaway

S3 Streamable Backup: Direct-to-Cloud Backups for Manticore Search

The Problem with Traditional Backups

Streamable S3 Backup: How It Works

Supported Storage Providers

Usage

CLI

Environment Variables

Performance Considerations

Restore from S3

Required S3 Permissions

Use Cases

Cloud-Native Deployments

Disaster Recovery

Reducing Local Storage Requirements

Technical Details

Streaming Architecture

Storage Interface

Migration from Local Backups

Conclusion

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

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