DEV Community: Sergey Nikolaev

UUID in Manticore: a single ID for the primary database and Manticore

Sergey Nikolaev — Wed, 05 Aug 2026 04:21:12 +0000

Suppose your product already has the ID 550e8400-e29b-41d4-a716-446655440000 in the primary database. It shows up in events, logs, and API responses. But when you load that same product into Manticore, the application still has to assign it another, numeric ID.

Before Manticore Search 28.5.0, the document ID was an unsigned 64-bit number. A UUID could be stored in a separate string attribute, but that did not make it the document ID. UPDATE, REPLACE, and DELETE still required a numeric id.

As a result, you had to keep a mapping between the UUID from the primary database and the numeric ID in the Manticore table. Now you can do without it: an RT table in Manticore can use a UUID as the document ID.

Why a second ID is a problem

A mapping table between IDs is not exactly complicated, but only as long as the application is loading data and searching. The problems start when documents change.

A worker receives an event with a UUID, finds the matching numeric ID, and only then sends the update to Manticore. Deletion follows the same path. If the mapping record is missing or stale, the wrong document may be updated, or the changes may never reach Manticore at all.

Another option is to turn the UUID into a 64-bit hash. Then the application itself has to account for possible collisions. You can also introduce a separate sequence counter, but then it has to be coordinated across all processes that create documents.

There is another subtle point with numeric IDs, and it appears at the API level. Inside Manticore it is a uint64, while SQL shows it as a signed BIGINT. Because of that, SQL can return values greater than 2^63-1 as negative numbers, and the client has to convert them carefully. A UUID is passed and returned as a string, so there is no need to worry about signed range or overflow.

id uuid solves the problem at the root: the object identifier no longer needs conversion. The same UUID is used in the primary DB, the queue, Manticore, logs, and the external API.

What a UUID is

UUID is essentially a 128-bit identifier that does not require a central registry to create. In text form, it usually consists of 36 characters: 32 hexadecimal digits and four hyphens.

550e8400-e29b-41d4-a716-446655440000

A UUID contains a version and a variant. The version defines how the remaining bits are formed. UUIDv4 is based on random or pseudorandom data. UUIDv7 includes a time component and preserves the chronological order of identifiers. In UUIDv8, the placement of the remaining bits is defined by a specific implementation.

The lack of a central registry makes it possible to assign an ID before writing to a shared database. For example, two independent services can create objects in parallel, and a mobile client with no LTE signal can prepare data without a server connection. After synchronization, the object keeps the same identifier.

However, a UUID should not be treated as an absolute guarantee of uniqueness. In practice, that depends on the correctness of the chosen generator. Also keep in mind that a UUID is not a secret and does not replace a password, token, or permission check.

What changed in Manticore 28.5.0

For an RT table, you can now explicitly set the document ID type:

CREATE TABLE products_uuid (
    id uuid,
    title text,
    sku string,
    price int
);

INSERT INTO products_uuid (id, title, sku, price)
VALUES (
    '550e8400-e29b-41d4-a716-446655440000',
    'Mechanical keyboard',
    'KB-001',
    149
);

After insertion, the same UUID can be used in equality and IN filters, as well as in UPDATE, REPLACE, and DELETE. SQL returns the ID as a string. You can also pass an explicit UUID or ask Manticore to generate an ID through the JSON API; we will cover detailed requests and responses in the next article.

If you run INSERT again with a UUID that already exists, Manticore rejects it, just as it used to with a numeric ID. Use REPLACE to overwrite a document by ID.

Note that the uuid type applies only to the document ID. You cannot declare a regular user attribute with the uuid type.

Who creates the UUID

There are two options:

How the document is written	Who creates the ID	What Manticore does
The `id` field is provided	The primary DB, a client library, or another system component	Validates the format, version, and `variant`, then stores the UUID in lowercase
The `id` field is missing	Manticore	Creates a UUIDv8 and encodes its internal numeric auto-ID into it

If your application already creates the UUID, you do not need to adapt it to Manticore. The format is standard: five groups of 8-4-4-4-12. The version can be any from v1 to v8, and the variant position must contain 8, 9, a, or b. Case does not matter: you can send the UUID in uppercase, but Manticore will store it in lowercase.

That is where validation ends: Manticore checks the UUID format, but not the quality of the generator. The client library is responsible for the randomness of UUIDv4 and the correct time component in UUIDv7.

Server-side generation works differently. If the id field is not provided, Manticore creates a UUIDv8 with its own structure and encodes the built-in numeric auto-ID into it. This is not a random UUIDv4 and it is not a secret value.

A UUIDv8 created by the application will be validated and stored by Manticore as is; the server will not reshape it according to its own scheme.

Technical note. The full UUID remains the external identifier: Manticore does not replace it with a 64-bit hash and does not require the application to store a mapping table. How the UUID is laid out inside the engine is an implementation detail and does not affect the external contract.

Where it works

You can use a UUID as the document ID in regular RT tables, RT tables with engine='columnar', and tables in a replication cluster. With such IDs, exact match search, IN filters, and the usual document operations are available: INSERT, REPLACE, UPDATE, and DELETE.

Keep these limitations in mind:

the uuid type is not suitable for regular attributes: Manticore will reject a declaration such as guid uuid;
in plain, percolate/PQ, and shard tables, UUIDs cannot be used as the document ID;
an existing table cannot be switched from a numeric ID to a UUID, or back, with ALTER TABLE;
range conditions <, <=, > and >=, as well as arithmetic operations on IDs of this type, are not supported;
the document ID cannot be changed through UPDATE - this applies to both UUIDs and numeric IDs;
for automatic generation, the id field must be omitted: the value 0 does not work here as a special marker.

This is easy to forget when porting legacy code. For a numeric RT table, 0 can mean “create the ID automatically.” In a UUID table, you simply need to leave out the id field.

UUIDv7 also does not make id suitable for time-based filters. You can use it as an external identifier, but Manticore does not yet support queries like id > ....

Summary

If the UUID already exists in the primary DB, you can now pass it to Manticore together with the document. If the document appears in Manticore first, do not specify id and take the generated UUID from the response.

From there, use the same UUID in UPDATE, REPLACE, and DELETE. There is no longer any need to give the document a separate numeric ID and keep a mapping between the two identifiers.

The full contract and current limitations are documented here: UUID document IDs. Support for UUID as a document ID appeared in Manticore Search 28.5.0.

In the next article, a practical guide to using UUIDs as document IDs, we will step through how to set and generate IDs with SQL and JSON, search, update, replace, and delete documents, and handle errors.

Manticore Search 28.6.6: UUID document IDs, ordered GROUP_CONCAT(), and 16 fixes

Sergey Nikolaev — Fri, 31 Jul 2026 09:33:57 +0000

Manticore Search 28.6.6 has been released. The headline additions are UUID document IDs for real-time tables and ordered, limited GROUP_CONCAT() for grouped queries. The release also includes 16 fixes for backups, replication, query processing, SQL compatibility, and secondary indexes.

This post covers everything shipped from 28.4.5 through 28.6.6.

Upgrade notes

There are no new mandatory data migrations in this release. UUID IDs are an opt-in table definition: existing numeric-ID tables keep working as they are. If you want UUID identifiers, create a real-time table with id uuid; ALTER TABLE cannot convert an existing table between numeric and UUID IDs.

Two fixes are particularly useful for production installations. Successful backups now always unfreeze real-time tables when they finish (previously in rare cases they didn't), rather than leaving writes blocked. And authenticated replication can again add an existing populated RT table with ALTER CLUSTER ... ADD.

UUID document IDs for real-time tables

Applications often already have UUID identifiers from the system of record. Until now, using them with Manticore Search meant maintaining a separate numeric ID mapping. Real-time tables can now use UUID document IDs directly:

CREATE TABLE products_uuid(id uuid, title text, price int);

Manticore accepts an explicit UUID string, or generates one when id is omitted from an insert or replace. UUID equality and IN filters work in queries, and UUID IDs can be used with REPLACE, UPDATE, and DELETE.

This is currently a real-time-table capability, including columnar and replicated RT tables. Plain, percolate, and sharded tables continue to use their existing ID models.

Ordered and limited GROUP_CONCAT()

Grouped results often need a compact preview of the most relevant values in each group. GROUP_CONCAT() can now sort values and retain only the requested number of them in explicit SQL GROUP BY queries:

SELECT category,
       GROUP_CONCAT(title ORDER BY price DESC SEPARATOR ', ' LIMIT 3)
FROM products
GROUP BY category;

The new ORDER BY, SEPARATOR, and LIMIT options let the query return the top values in the requested order instead of concatenating an arbitrary-sized set and sorting it again in application code. See the GROUP_CONCAT() reference for the full syntax.

Safer table, backup, and cluster maintenance

A few changes remove failures that tend to appear during routine operations rather than ordinary searches:

Manticore Backup 1.10.2 fixes a path where a successful backup could leave an RT table frozen and future writes blocked.
Authenticated replication state transfer now works when ALTER CLUSTER ... ADD is used to add a populated RT table.
RT lifecycle operations now remove obsolete external files after ALTER, TRUNCATE, chunk removal, and optimization. The same release preserves Jieba settings during unrelated ALTER TABLE operations and rejects unsupported effective setting changes explicitly.
OPTIMIZE TABLE accepts qualified system.<table> names, so physical sharded tables can be optimized.

Query processing and client compatibility

The fixes are broad, but several stand out for busy search services:

CALL SNIPPETS no longer spends seconds simplifying some complex boolean queries before highlighting them when boolean_simplify is enabled.
Long exact and phrase-like queries no longer risk a query-stack underestimate that could corrupt memory or crash searchd; repeated keyword statistics are also deduplicated for local_df work on multi-chunk RT and distributed tables.
The updated columnar library fixes a StreamVByte decoder over-read that could crash secondary-index queries, including GROUP BY on JSON fields. indextool --check now reports corrupted secondary-index files instead of crashing.
USER() remains usable after USER became an authentication keyword, restoring MySQL client status command compatibility. SHOW INDEX ... STATUS is also protected from a concurrent percentile-calculation race.
Document-ID IN(...) filters correctly accept valid unsigned 64-bit IDs above Long.MAX_VALUE, and a LEFT JOIN with multiple FACET clauses no longer crashes.

The release also fixes a SphinxQL SSL connection-handling race that could consume workers at 100% CPU, and fixes PHP API response parsing and the Ruby API fixture so valid response chunks ending in "0" are preserved.

For the complete list, see the Version 28.6.6 changelog.

Get Manticore Search 28.6.6

Install or upgrade Manticore Search with the installation guide. If you are upgrading an authenticated or replicated deployment, review the existing authentication rollout checklist before changing production traffic.

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

Faceted search under active filters

Sergey Nikolaev — Thu, 30 Jul 2026 04:54:21 +0000

Facets in an online store seem simple until the first filter is selected.

In a catalog, they are part of the navigation. A selected color should not disappear from the list. Other colors should remain available: the user may want to switch to one or broaden the selection. Options with no matching products are more useful when shown as unavailable. Within a single facet, OR usually applies: red or blue. Across different facets, it is AND: brand, color, and size at the same time.

The difficult part begins after the first selection. Imagine a product catalog where the user has selected a brand, color, and size. The main result set must remain narrow and show only products matching all three conditions. But the filter panel follows different rules. It needs to preserve the selected color while also showing the colors the user can switch to under the same brand and size.

If every facet inherits all filters from the main query, it quickly collapses to the values already selected. If the filters for every facet have to be rebuilt manually, you end up with separate query branches for color, size, brand, availability, seller, and every other attribute.

Manticore Search 25.12.0 introduced facet_filter_mode, which moves this behavior into the facet API. A query can now describe how the store's filter panel should behave, without the application manually building nearly identical queries for every facet.

What e-commerce facets need

For a filter panel, answering "how many products have this value?" is not enough. It needs statuses that the interface can use directly:

selected values remain visible and can be cleared quickly;
other values in the same facet remain available because they broaden the filter through IN (...);
values in other facets indicate whether selecting them would return at least one product;
counts remain predictable: the interface knows whether a number refers to the current result set or a broader selection;
search within long brand lists, categories, price ranges, SEO rules, and query analytics still matter; they are a separate part of search design.

facet_filter_mode handles the most common part of this problem: recalculating facets after the user has already selected several filters.

What changed

Facets now have three filter inheritance modes:

Mode	Behavior
`strict`	Applies all filters from the main query to the facet. This is the previous behavior and remains the default.
`auto`	Applies every filter except filters on the facet itself and adds `status`: selected values get `selected`, while other values get `available`.
`max`	Calculates buckets over a broad base result set and adds `status` to distinguish selected, available, and unavailable values.

You can also control this manually:

ALL FILTERS - apply all filters to the facet;
FILTERS color_id, size_id - apply only the listed filters;
EXCLUDE FILTERS color_id - apply every filter except those listed;
ZEROES - starting with Manticore Search 27.3.0, preserve buckets from the broad max scope in SQL max mode even when their count(*) in the current facet is 0.

The same options are available in the JSON API through facet_filter_mode, mode, filters, exclude_filters, and zeroes: true.

In short, strict answers "what is in the current result set?", auto answers "what happens if this particular filter changes?", and max shows a broad list of buckets with a status field: selected, available, or unavailable.

Minimal example

Consider a small catalog with a brand, color, size, and SKU:

CREATE TABLE products(
  title text,
  brand_id int,
  color_id int,
  color_name string,
  size_id int,
  size_name string,
  sku string
);

INSERT INTO products(id,title,brand_id,color_id,color_name,size_id,size_name,sku) VALUES
(1,'p1',7,1,'red',10,'small','sku1'),
(2,'p2',7,1,'red',20,'large','sku2'),
(3,'p3',7,2,'blue',10,'small','sku3'),
(4,'p4',7,3,'green',30,'xlarge','sku4'),
(5,'p5',8,1,'red',10,'small','sku5'),
(6,'p6',8,4,'black',20,'large','sku6'),
(7,'p7',9,5,'white',10,'small','sku7');

The user selected:

brand_id=7 AND color_id=1 AND size_id=10

Under these conditions, the result set contains one product: p1. Let's see what happens to the facets.

strict: the previous behavior

Without additional options, Manticore Search uses strict: every facet receives all filters from the main query.

SELECT count(*)
FROM products
WHERE brand_id=7 AND color_id=1 AND size_id=10
LIMIT 0
FACET color_id ORDER BY color_id ASC
FACET size_id ORDER BY size_id ASC;

Response:

+----------+----------+
| color_id | count(*) |
+----------+----------+
|        1 |        1 |
+----------+----------+
+---------+----------+
| size_id | count(*) |
+---------+----------+
|      10 |        1 |
+---------+----------+

This is an accurate SQL response, but it is often too narrow for an online store. The user sees only the already selected color_id=1 and size_id=10. It looks as if there are no other options, even though the data contains a product with the same brand and size but a different color (color_id=2), and another with the same brand and color but a different size (size_id=20).

auto: a facet ignores its own filter

The auto mode keeps every filter except the filter on the facet currently being calculated.

SELECT count(*)
FROM products
WHERE brand_id=7 AND color_id=1 AND size_id=10
LIMIT 0
OPTION facet_filter_mode='auto'
FACET color_id ORDER BY color_id ASC
FACET size_id ORDER BY size_id ASC;

Response:

+----------+----------+-----------+
| color_id | count(*) | status    |
+----------+----------+-----------+
|        1 |        1 | selected  |
|        2 |        1 | available |
+----------+----------+-----------+
+---------+----------+-----------+
| size_id | count(*) | status    |
+---------+----------+-----------+
|      10 |        1 | selected  |
|      20 |        1 | available |
+---------+----------+-----------+

Here is what happened:

FACET color_id applied brand_id=7 AND size_id=10, but not color_id=1;
FACET size_id applied brand_id=7 AND color_id=1, but not size_id=10.

This gives the interface alternative values without a separate query for every facet. Selected buckets are marked selected, while other values in the same facet are marked available: they can be added to the current filter as a broader selection through IN (...).

max: a broad bucket list with statuses

auto shows only values from the current filter scope for a particular facet. max goes further: it calculates buckets over the base result set and marks their status separately for the interface.

SELECT count(*)
FROM products
WHERE brand_id=7 AND color_id=1 AND size_id=10
LIMIT 0
OPTION facet_filter_mode='max'
FACET color_id ORDER BY color_id ASC
FACET size_id ORDER BY size_id ASC;

Response:

+----------+----------+-----------+
| color_id | count(*) | status    |
+----------+----------+-----------+
|        1 |        3 | selected  |
|        2 |        1 | available |
|        3 |        1 | available |
|        4 |        1 | available |
|        5 |        1 | available |
+----------+----------+-----------+
+---------+----------+-----------+
| size_id | count(*) | status    |
+---------+----------+-----------+
|      10 |        4 | selected  |
|      20 |        2 | available |
|      30 |        1 | available |
+---------+----------+-----------+

status comes directly from Manticore Search:

selected - the value is already present in the filter on this facet;
available - the value can be selected; for another value in the same facet, this broadens the filter through IN (...);
unavailable - the value exists in the facet's broad result set, but selecting it would return no documents under the current filters.

In this example, color_id=1 occurs in three products across the catalog, so its count in max is 3. It is marked selected because it already participates in the filter. The other colors are marked available: if the user selects one, the color filter becomes broader, for example color_id IN (1,2). Unavailable values appear when a bucket in the broad result set cannot return documents under the current filters; the sku example below demonstrates this case.

Manually setting the filter scope

The global facet_filter_mode covers most common cases, but sometimes different facets need different behavior. For example, color can remain strictly constrained by all filters, size can use max, SKU can be calculated using only color and size, and brand can be calculated without the color filter.

SELECT count(*)
FROM products
WHERE brand_id=7 AND color_id=1 AND size_id=10
LIMIT 0
OPTION facet_filter_mode='max'
FACET color_id ALL FILTERS ORDER BY color_id ASC
FACET size_id ORDER BY size_id ASC
FACET sku FILTERS color_id, size_id ORDER BY sku ASC
FACET brand_id EXCLUDE FILTERS color_id ORDER BY brand_id ASC;

Response:

+----------+----------+-----------+
| color_id | count(*) | status    |
+----------+----------+-----------+
|        1 |        1 | selected  |
+----------+----------+-----------+
+---------+----------+-----------+
| size_id | count(*) | status    |
+---------+----------+-----------+
|      10 |        4 | selected  |
|      20 |        2 | available |
|      30 |        1 | available |
+---------+----------+-----------+
+------+----------+-------------+
| sku  | count(*) | status      |
+------+----------+-------------+
| sku1 |        1 | available   |
| sku5 |        1 | unavailable |
+------+----------+-------------+
+----------+----------+----------+
| brand_id | count(*) | status   |
+----------+----------+----------+
|        7 |        2 | selected |
+----------+----------+----------+

How to read this query:

FACET color_id ALL FILTERS applies every filter and returns only the selected color;
FACET size_id inherits the query-level max mode;
FACET sku FILTERS color_id, size_id applies only the color and size filters;
FACET brand_id EXCLUDE FILTERS color_id applies every filter except color.

This mode is useful when a filter panel contains both regular and technical facets, and some values need to be calculated according to special rules.

ZEROES: zero-count buckets in max

ZEROES is useful when counts need to remain strict but the list of values needs to stay broad. It works with max, either through OPTION facet_filter_mode='max' or through MODE max on an individual facet.

Without ZEROES, a facet with ALL FILTERS shows only the bucket that passes every filter:

SELECT count(*)
FROM products
WHERE brand_id=7 AND color_id=1 AND size_id=10
LIMIT 0
OPTION facet_filter_mode='max'
FACET size_id ALL FILTERS ORDER BY size_id ASC;

Response:

+---------+----------+----------+
| size_id | count(*) | status   |
+---------+----------+----------+
|      10 |        1 | selected |
+---------+----------+----------+

With ZEROES, Manticore Search keeps the same visible counts but returns the remaining buckets from the broad max scope with a count of zero:

SELECT count(*)
FROM products
WHERE brand_id=7 AND color_id=1 AND size_id=10
LIMIT 0
OPTION facet_filter_mode='max'
FACET size_id ALL FILTERS ZEROES ORDER BY size_id ASC;

Response:

+---------+----------+-----------+
| size_id | count(*) | status    |
+---------+----------+-----------+
|      10 |        1 | selected  |
|      20 |        0 | available |
|      30 |        0 | available |
+---------+----------+-----------+

The interface can then show large and xlarge alongside the selected small: the number refers to the current strict result set, while status shows that these values can still be selected to broaden the filter.

The same query through the JSON API

SQL is shorter here and shows the mechanics more clearly, but the JSON API supports the same approach:

POST /search
{
  "table": "products",
  "limit": 0,
  "query": {
    "bool": {
      "must": [
        { "equals": { "brand_id": 7 } },
        { "equals": { "color_id": 1 } },
        { "equals": { "size_id": 10 } }
      ]
    }
  },
  "facet_filter_mode": "max",
  "aggs": {
    "colors": {
      "terms": { "field": "color_id", "size": 10 },
      "sort": [ { "color_id": { "order": "asc" } } ]
    },
    "sizes": {
      "terms": { "field": "size_id", "size": 10 },
      "sort": [ { "size_id": { "order": "asc" } } ]
    }
  }
}

Response:

{
  "took": 0,
  "timed_out": false,
  "hits": {
    "total": 1,
    "total_relation": "eq",
    "hits": []
  },
  "aggregations": {
    "colors": {
      "buckets": [
        { "key": 1, "doc_count": 3, "status": "selected" },
        { "key": 2, "doc_count": 1, "status": "available" },
        { "key": 3, "doc_count": 1, "status": "available" },
        { "key": 4, "doc_count": 1, "status": "available" },
        { "key": 5, "doc_count": 1, "status": "available" }
      ]
    },
    "sizes": {
      "buckets": [
        { "key": 10, "doc_count": 4, "status": "selected" },
        { "key": 20, "doc_count": 2, "status": "available" },
        { "key": 30, "doc_count": 1, "status": "available" }
      ]
    }
  }
}

In JSON aggregations, mode, filters, exclude_filters, and zeroes can also be set for each individual aggregation.

How this differs from Meilisearch, Elasticsearch, and OpenSearch

We tested the same scenario in Manticore Search, Meilisearch, Elasticsearch, and OpenSearch: the brand_id=7, color_id=1, and size_id=10 filters are active; the result set remains strict, while the facets need to show options that appear when their own filter is excluded.

Engine	Excludes its own filter in one query	Native bucket status	What remains for the application
Manticore Search	Yes, through `auto`/`max`	Yes, in `auto`/`max`; `unavailable` only in `max`	Rendering the interface, SEO, analytics, and custom rules.
Meilisearch	Not in this form	No	Run additional queries and assemble facets in the application.
OpenSearch	Yes, but manually through `global` + `filter` aggregations	No	Duplicate filter branches and calculate `status` in the application.
Elasticsearch	Yes, but manually through `global` + `filter` aggregations	No	The same: maintain separate aggregation branches and client-side logic.

Basic facets are easy to use in Meilisearch, but a query such as:

{
  "filter": ["brand_id = 7", "color_id = 1", "size_id = 10"],
  "facets": ["color_id", "size_id"]
}

returns counts for the already filtered result set. In our dataset, that means only color_id=1 and size_id=10. The alternative color_id=2 and size_id=20 values do not appear in this response. If the interface needs them, the application must make additional queries and merge the results.

In Elasticsearch and OpenSearch, similar behavior can be built in one query, but each facet needs its own explicit aggregation branch. For color, you keep brand_id and size_id; for size, you keep brand_id and color_id; and so on. This works, but the query grows quickly, and bucket statuses still have to be calculated in the application.

The main difference is where this logic lives. In Manticore Search, it is configured directly in the facet API; in other systems, it is usually assembled from several similar filter trees.

Performance and limitations

strict remains the default and preserves the previous behavior. If you only need facets within the current result set, nothing needs to change.

auto is usually the better fit for e-commerce filters: it shows alternative values within each facet, marks selected values as selected, and marks other values as available.

Use max when the interface needs value lists broader than the current result set and needs to show unavailable options. This mode costs more: Manticore Search calculates buckets over a broad scope and then determines their status separately. This is worth considering with large datasets and many facets.

There are also some limitations:

local filter rewriting for a facet supports only attribute filters combined with AND;
complex AND/OR trees are not rewritten automatically for individual facets;
selected values are currently matched reliably only for explicit value filters such as = and IN;
statuses are not yet calculated automatically for ranges such as prices.

For prices, discounts, and ratings, it is better to define separate ranges explicitly. For example, keep a numeric field for sorting and sliders, and add price_band or discount_band for the facet. This lets the interface show clear statuses for predefined ranges.

SEO for faceted URLs, A/B tests, merchandising rules, and query analytics remain the responsibility of the application or platform around search.

In practice, start with auto when you need alternative values, and move to max when the interface needs a broad bucket list with selected, available, and unavailable statuses.

Install Manticore Search with one command

Sergey Nikolaev — Wed, 29 Jul 2026 03:24:47 +0000

There is now a one-line installer for Manticore Search:

curl https://manticoresearch.com | sh

It is still a normal package-manager install. The script checks whether the machine uses APT, YUM/DNF, or Homebrew, configures the Manticore repository when needed, installs the manticore package, and starts the service unless you tell it not to.

Use it when you want to bring up Manticore Search quickly and do not need to walk through the package-manager steps by hand. If you prefer to control the repository setup, package install, service start, or deployment method yourself, the manual installation pages are still the right place to go.

After it runs

A successful run leaves Manticore installed through the system package manager. Upgrades, service management, uninstall, and host inspection use the usual system tools.

By default, the installer:

installs from the stable Manticore package repository
installs the manticore package
starts the manticore service
keeps the default listeners on 9306, 9308, and 9312
writes an install log for troubleshooting

Check the service

Once the service is started, a quick SQL-over-HTTP check is enough:

curl -sS "http://127.0.0.1:9308/sql?mode=raw" -d "SELECT VERSION()"

Or use the MySQL client:

mysql -P9306 -h0 -e "SELECT VERSION()"

If that returns a version, the package is installed and the service is answering.

Why add another install path?

The manual instructions are not going away. They are still better when you need Docker, Kubernetes, Windows, a pinned package-manager flow, or a deployment policy that does not allow remote shell scripts.

The one-line installer covers the shorter path. Instead of asking the reader to pick between APT, YUM/DNF, and Homebrew first, it detects the package manager and runs the same standard setup:

Debian or Ubuntu: add the APT repo, update metadata, install the package, start the service.
RHEL-compatible distribution: install the repository RPM, install the package, start the service.
macOS: use Homebrew, then start the service through brew services.
Other environments: stop and point to the manual options.

Small difference, but useful when you just want a running local or test instance.

What the script does

The installer is a shell script. If you want to read it first, the source is installer/bootstrap-standalone.sh in the Manticore Search GitHub repository.

On a system it supports, it:

detects APT, YUM/DNF, or Homebrew
checks that the CPU architecture is x86-64 or ARM64
installs the Manticore repository package when needed
installs the manticore package
starts the manticore service by default
checks the default listener ports before startup when ss or netstat is available
writes an install log to /var/log/manticore_install.log when possible, otherwise to /tmp/manticore_installer.log

The default listener ports are 9306, 9308, and 9312. If one of them is already occupied, Manticore is not already running, and the system has ss or netstat, the installer fails instead of editing the configuration for you. If neither utility is available, the pre-check cannot run; service startup may still fail if a port is already taken.

Port changes are left to you because changing them can affect clients, service files, and monitoring.

Where it applies

The installer currently supports:

Debian, Ubuntu, Linux Mint, and Debian-like systems using APT
RHEL, CentOS, Fedora, Rocky Linux, AlmaLinux, Amazon Linux, and RHEL/Fedora-like systems using YUM or DNF
macOS when Homebrew is installed
x86-64 and ARM64 CPUs

The command shown above uses curl. You can also fetch the script with wget:

wget -O- https://manticoresearch.com | sh

Bash must be installed. The downloaded script starts under /bin/sh, checks for Bash, and then runs the main installer payload with Bash. You also need the usual permissions to install packages and start services, either as root or through sudo.

If the operating system, package manager, or CPU architecture is not supported, the installer stops and prints a message pointing to the manual installation guide.

Default behavior

With no extra options, the installer uses the stable release channel, installs the package, starts the service, and keeps the standard listener ports:

stable packages are used unless you pass dev
the service starts unless you pass no-start
listener ports stay at 9306, 9308, and 9312
existing data is not removed

Other checks apply only in specific cases. Before an upgrade, the installer backs up configuration. It copies data directories only if you pass backup-data. During uninstall and purge, it keeps data in place. If it finds an existing searchd binary outside the package-managed install, it prints a warning.

The destructive option is still separate: purge-all removes packages, repository state, configuration, and data. Without non-interactive mode, it asks you to type DELETE before removing /etc/manticoresearch and /var/lib/manticore.

Common commands

Most installer behavior is controlled by passing options after sh -s:

# Install the latest stable package and start the service
curl https://manticoresearch.com | sh

# Install but do not start the service
curl https://manticoresearch.com | sh -s no-start

# Upgrade an existing package-managed installation
curl https://manticoresearch.com | sh -s upgrade

# Upgrade and include the data directory in the backup
curl https://manticoresearch.com | sh -s upgrade backup-data

# Choose where upgrade backups are written
curl https://manticoresearch.com | sh -s upgrade backup-data backup-dir /path/to/backups

# List available stable versions
curl https://manticoresearch.com | sh -s list-versions

# List versions from the development repository
curl https://manticoresearch.com | sh -s dev list-versions

# Install or switch to a specific version without starting the service
curl https://manticoresearch.com | sh -s version 25.0.0 no-start

# Show installer help
curl https://manticoresearch.com | sh -s help

Specific version selection is for Linux package-manager installs. Homebrew installs and upgrades follow the Homebrew formula and do not support version through this installer.

The dev option switches to the development repository. The default is the release channel.

CI and non-interactive use

For automation, use silent or yes only when you want the installer to run without prompts and accept the script's defaults:

curl https://manticoresearch.com | sh -s silent no-start

silent and yes are aliases for the same non-interactive mode. They do not mean "no output": the installer still writes progress and errors, but without interactive prompts and color. They also do not request an upgrade by themselves. If an existing installation should be upgraded, pass upgrade explicitly:

curl https://manticoresearch.com | sh -s upgrade silent

Be careful with cleanup commands in non-interactive mode. In the current installer, silent also skips the "DELETE" prompt for purge-all, so it can delete configuration and data without asking again.

Cleanup options

Uninstalling is split into levels:

# Remove packages, keep configuration, data, and repository state
curl https://manticoresearch.com | sh -s uninstall

# Remove packages and the repository bootstrap package
curl https://manticoresearch.com | sh -s purge

# Remove packages, repository state, configuration, and data
curl https://manticoresearch.com | sh -s purge-all

purge-all is the destructive option. Do not combine it with silent or yes unless you intentionally want to remove /etc/manticoresearch and /var/lib/manticore without a confirmation prompt:

curl https://manticoresearch.com | sh -s purge-all silent

Removing software and deleting data are not the same operation, so the installer keeps those paths separate.

If your policy forbids pipe-to-shell

Some environments do not allow curl | sh. That is fine. Use the manual package-manager instructions, or review the script source first and run it only after inspection.

For manual package-manager commands, Docker, Kubernetes, Windows, and separate packages, see the Manticore Search installation guide.

Manticore Search authentication rollout checklist for production

Sergey Nikolaev — Tue, 28 Jul 2026 06:15:49 +0000

In production, "turn it on and done" almost never works. On a standalone node, the technical sequence is short: enable auth, restart Manticore, create an admin user, and update clients. A topology with distributed tables or replication clusters needs extra preparation because nodes must authenticate to each other as well.

Handle the rollout like a small release. Inventory clients and nodes, prepare the auth data, rehearse the procedure for your topology, and then cut over. A rehearsal exposes failures before the maintenance window.

This checklist is for users who plan to enable authentication and want to roll it out as safely as possible in an existing system. Remember that authentication is disabled until you configure auth; after cutover, clients that still omit credentials will fail.

Choose the procedure by topology:

Topology	Migration requirement
standalone node	bootstrap the first administrator after enabling `auth`
distributed tables and remote agents	distribute one canonical auth store before authenticated remote queries begin
replication cluster	prepare the persisted cluster user and auth store before startup, then recover the cluster in a controlled order

Phase 1: inventory before changing anything

Start by listing every client that connects to Manticore Search, including each application and independently deployed application component. Do this before editing the config.

Common things to check:

application search frontends
ingest workers
cron jobs
dashboards and BI tools
support or admin tools
schema change/update scripts
backup and maintenance scripts
local scripts run manually

For each client, record something like this:

Client	Protocol	Tables or clusters	Needed actions	Notes
product search app	HTTP	`products`	`read`	will use Bearer token
catalog ingest worker	SQL	`products`	`write`	uses password auth
schema migration job	SQL	`products`	`schema`	run only during deploy
access administrator	SQL	`*`	`admin`	manages users and permissions

Then confirm the deployment basics:

Is this a standalone node, a distributed-table topology, a replication cluster, or a combination of them?
Are you running RT mode or plain mode?
In plain mode, where should the auth file live?
Is pid_file configured in the config? Bootstrap needs it.
Are all participating nodes running a version that supports the same authentication protocol?
Will SQL clients use SSL, and will HTTP clients use HTTPS when credentials cross a network?
Where will credentials, including temporary Bearer tokens, be stored safely?
Who is allowed to see the first admin password?

If replication is present, also record every cluster name and its persisted user in each node's <data_dir>/manticore.json. Back up the complete data directory, configuration, and any existing auth store before the rehearsal and again before production cutover.

Do not skip the credential-handling questions. CREATE USER returns a raw Bearer token; TOKEN generates a new token for the specified user. SHOW TOKEN later shows the stored token hash, not the raw token. If the raw token is lost, rotate it with TOKEN and update the token in your application.

Phase 2: set up least-privilege users

Create users based on specific workloads, rather than granting permissions based on what someone might need later.

Use a small matrix like this:

Workload	User	Permissions
search frontend	`app_read`	`GRANT read ON 'products' TO 'app_read'`
ingest worker	`app_ingest`	`GRANT write ON 'products' TO 'app_ingest'`
schema migration job	`schema_job`	`GRANT schema ON 'products' TO 'schema_job'`
auth operator	`security_admin`	`GRANT admin ON * TO 'security_admin'`
replication operator	`cluster_repl`	`GRANT replication ON 'posts' TO 'cluster_repl'`

Keep in mind that admin is a narrow permission. It only allows managing authentication and authorization state; it does not imply read, write, schema, or replication.

That matters because a person who manages credentials does not automatically need to read business data. A service that searches products does not need to write documents. A migration job does not need to manage users.

Plan negative permission tests as well. For every user you create, choose at least one thing it should be able to do and one thing it should not be able to do.

Examples:

app_read can search products.
app_read cannot insert into products.
app_ingest can write to products.
app_ingest cannot manage auth.
schema_job can change schema for products.
schema_job cannot read tables unless you grant read.

Phase 3: test in staging

Use a staging environment to rehearse the sequence of steps you plan to follow in production.

In RT mode:

searchd {
    data_dir = /var/lib/manticore
    auth = 1
    auth_log_level = info
    ...
}

To turn auth off explicitly in RT mode:

searchd {
    data_dir = /var/lib/manticore
    auth = 0
    ...
}

In plain mode:

searchd {
    auth = /var/lib/manticore/auth.json
    auth_log_level = info
    ...
}

Keep the auth file private. Before the first bootstrap, Manticore may create an empty auth file. After bootstrap, that file stores auth data and credential hashes.

This bootstrap sequence works on a standalone node or on an isolated temporary daemon that prepares auth data for several nodes. Never start an existing replication data directory with an empty auth store. Its persisted cluster user will be missing, and Manticore may skip the cluster descriptor.

Start searchd, then bootstrap the first administrator:

searchd --config /etc/manticoresearch/manticore.conf --auth

For scripted setup:

printf 'admin\nStrongPass#2026\nStrongPass#2026\n' | \
  searchd --config /etc/manticoresearch/manticore.conf --auth-non-interactive

⚠️ Warning: The command above includes the password in plain text. In production automation, feed the three input lines to standard input from your secret-management system.

Bootstrap creates the first administrator with all actions, including replication; no additional grant is needed. The command does not return a bearer token. If the administrator needs HTTP Bearer access, connect as that user and run TOKEN, or use the HTTP POST /token endpoint.

For a multi-node deployment, create the auth store once. Use a temporary daemon with its own empty data directory, PID file, and listeners. Bootstrap the administrator and shared service users, then stop the daemon cleanly. Copy the resulting auth store to every participating node before enabling authenticated node-to-node traffic. Do not recreate the same users independently: matching names and passwords can still produce different stored authentication material.

Next, create staging users based on the notes from the previous phases. For example:

CREATE USER 'app_read' IDENTIFIED BY 'ReadPass#2026';
GRANT read ON 'products' TO 'app_read';

CREATE USER 'app_ingest' IDENTIFIED BY 'IngestPass#2026';
GRANT write ON 'products' TO 'app_ingest';

CREATE USER 'schema_job' IDENTIFIED BY 'SchemaPass#2026';
GRANT schema ON 'products' TO 'schema_job';

CREATE USER 'security_admin' IDENTIFIED BY 'AdminPass#2026';
GRANT admin ON * TO 'security_admin';

Store the returned Bearer tokens in secure storage. Remember: raw tokens must not be left in logs, shell history, or unprotected files. If you need to rotate one, use:

TOKEN 'app_read';

SHOW TOKEN is not a way to recover the raw token:

SHOW TOKEN FOR 'app_read';

Review users and permissions:

SHOW USERS;
SHOW PERMISSIONS;
SHOW PERMISSIONS FOR 'app_read';

Run one allow and one deny test for every user. For the read-only user:

curl -H "Authorization: Bearer <app_read_token>" \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "SELECT * FROM products LIMIT 10"

Then verify that an unauthorized operation is denied:

curl -H "Authorization: Bearer <app_read_token>" \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "INSERT INTO products(id,title) VALUES(1,'test')"

For this HTTP request, expect a 403 Forbidden response. Over SQL/MySQL, a permission denial returns ERROR 1045 with a permission-denied message.

SQL clients should connect with a Manticore user name and password. The SQL/MySQL protocol in Manticore supports mysql_native_password.

MYSQL_PWD=ReadPass#2026 \
  mysql -h127.0.0.1 -P9306 -uapp_read \
  -e "SELECT * FROM products LIMIT 10"

HTTP clients can use Basic authentication or Bearer tokens:

curl -u app_read:ReadPass#2026 \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "SELECT * FROM products LIMIT 10"

HTTP authentication schemes (Basic, Bearer) are case-insensitive; user names are case-sensitive.

If you edit the auth file outside the daemon during maintenance, reload it:

RELOAD AUTH;

Phase 4: production rollout checklist

Use this checklist for every deployment, then follow the procedure for your topology.

[ ] Confirm you have a current configuration and data-directory backup.
[ ] Back up manticore.json and the existing auth store separately.
[ ] Confirm existing network protections stay in place.
[ ] Confirm pid_file is set in the config.
[ ] Confirm where the auth file will be created or loaded from.
[ ] Confirm password and token storage is ready.
[ ] Confirm every participating node runs a compatible Manticore version.
[ ] Rehearse the same topology and restart order in staging.
[ ] Prepare one canonical auth store for users shared across nodes.
[ ] Choose the standalone, distributed, or replication procedure below.
[ ] Enable auth during a planned maintenance window.
[ ] Expect unauthenticated clients to fail after auth is enabled.
[ ] Store tokens in a protected secrets store immediately after they are issued. Do not store raw tokens in files, shell history, or logs.
[ ] Update SQL connection code to send user names and passwords.
[ ] Update HTTP connection code to use Basic authentication or Bearer tokens.
[ ] Run the allow and deny tests from staging.
[ ] Verify internal node-to-node operations when the deployment has remote agents or replication.
[ ] Check the auth log.
[ ] Run application stress tests that cover search, ingest, dashboards, and maintenance scripts.
[ ] Rotate any temporary rollout credentials.
[ ] Keep the first admin credential out of normal application use.

Standalone node

For a standalone node, the direct bootstrap sequence is sufficient:

Stop Manticore cleanly and take the final backup.
Configure auth and start searchd.
Bootstrap the first administrator with searchd --config <path> --auth.
Create the production users and permissions.
Update clients and run the planned allow and deny tests.
Confirm that existing tables and known rows are still available.

Distributed tables and remote agents

Distributed queries send remote-agent requests as the current session user. Each remote node must have the same stored authentication material for that user and grant the required permission on the remote table.

For a new rollout across distributed nodes:

Create the shared users once in the isolated bootstrap daemon from Phase 3.
Stop the affected agents and masters for the coordinated cutover.
Configure auth and place the same canonical auth store on every participating node. Preserve restrictive ownership and permissions, and compare checksums.
Start remote agents before the masters that query them.
Test a direct authenticated query on each agent, followed by the equivalent distributed query through the master.
Create node-local users only after shared traffic works, and keep shared user records synchronized whenever their passwords, tokens, or permissions change.

Create shared users only once. Independently created accounts can have different stored authentication material even when their names and passwords match.

Existing replication cluster

Moving an existing unauthenticated replication cluster to auth requires a coordinated restart. Do not enable auth and bootstrap the first user against the existing cluster data. The empty store does not contain the persisted cluster user, so Manticore may skip the cluster descriptor.

Use this sequence:

While the unauthenticated cluster is healthy, choose its future replication identity and persist it:

   ALTER CLUSTER products UPDATE user 'cluster_repl';

UPDATE user writes the name to the cluster metadata. Authentication is still disabled, so Manticore neither creates nor checks the account at this point. Create it in step 3, before restarting any real cluster node with authentication enabled.

Verify that every node's <data_dir>/manticore.json now stores "user": "cluster_repl" for the cluster. If a node hosts several clusters, update each cluster to a user that will exist in the new auth store, or create and grant every persisted user before cutover.

Stop all cluster nodes cleanly and use the replication state to select the safe primary. After a clean shutdown, this is normally the node stopped last, with safe_to_bootstrap: 1 in its <data_dir>/grastate.dat. See Restarting a cluster.
Bootstrap cluster_repl as the first administrator in the isolated temporary daemon. The first administrator already has every action, including replication, so it needs no additional grant. If the cluster will use a separate least-privilege identity, create it once and grant replication before distributing the store.
Stop the temporary daemon. Configure auth on every real cluster node and copy the exact generated auth store to each one. Keep the files private and byte-identical. Do not start a real cluster node before this store is in place.
Restart a two-node cluster in this order:
1. Start the non-primary peer normally and wait only for its daemon listener. Its cluster can report closed at this point; do not write to it.
2. Start the recorded safe primary with --new-cluster, or use the corresponding manticore_new_cluster service action.
3. Wait for the safe primary to report cluster_products_status=primary and cluster_products_node_state=synced.
4. Stop the first peer cleanly and start it normally again. Wait for the same primary and synced values on that peer. Never use --new-cluster on it.

The safe primary reads the persisted cluster user from a descriptor peer during startup, so the initial peer must already be listening. Starting the safe primary alone can fail with failed to fetch donor user from any node even when the auth store is correct. For a larger cluster, rehearse the sequence in staging. Use one non-primary node as the initial metadata peer, establish the safe primary, and then start or restart the remaining peers normally.

On each node, check that the cluster component is primary, the local node is synchronized, and the pre-migration data is present:

   SHOW STATUS LIKE 'cluster_products_status';
   SHOW STATUS LIKE 'cluster_products_node_state';
   SELECT COUNT(*) FROM products:existing_table;

Wait until the two status values are primary and synced, respectively, before treating the node as writable.

Before returning traffic, make a disposable one-row table and add it to the recovered cluster:

   CREATE TABLE migration_control (id bigint, body text);
   INSERT INTO migration_control VALUES (1, 'post-auth control');
   ALTER CLUSTER products ADD migration_control;

Confirm that the peer returns one row from products:migration_control. If this check fails after the pre-migration data checks passed, investigate table transfer rather than the migration itself.

After the cluster is healthy, create the remaining administrative users and, if needed, a dedicated least-privilege replication user. Change the stored cluster identity only after the new user and its auth data are visible on every node:

CREATE USER 'repluser' IDENTIFIED BY '<strong-secret>';
GRANT replication ON * TO 'repluser';
ALTER CLUSTER products UPDATE user 'repluser';

Do not remove the bootstrap administrator until another administrator and the final replication identity have both been verified.

When a node joins an authenticated cluster, the donor's auth data replaces the joining node's local auth data. At info or a more verbose auth log level, Manticore writes the previous data to searchd.log.auth as a backup. The log can contain salts and credential hashes, so restrict access and redact it before sharing.

Authentication logging during cutover

Authentication events are written to a separate auth log when authentication is enabled. If the daemon log is /var/log/manticore/searchd.log, the auth log is /var/log/manticore/searchd.log.auth.

The auth_log_level values are:

disabled
error
warning
info
all
trace

The default is info. Start there unless you have a reason to reduce or increase the logging detail. Use trace only for diagnostics; it also includes all successful internal auth traffic.

Useful cleanup and maintenance commands:

SET PASSWORD 'NewReadPass#2026' FOR 'app_read';
REVOKE read ON 'products' FROM 'app_read';
DROP USER 'app_read';

SET PASSWORD changes the password used by SQL/MySQL and HTTP Basic auth. It does not revoke existing bearer tokens. To rotate Bearer access, create a new token with TOKEN or POST /token and update the client.

Phase 5: rollback and troubleshooting

For a standalone node, restore the previous configuration and network restrictions, restart Manticore, and revert the client configuration if necessary.

Roll back all communicating nodes together. A mix of authenticated and unauthenticated nodes will not work. Restore the same configuration and auth state on each node, then restart remote agents before their masters.

Keep the pre-cutover manticore.json backup for every replication cluster. If a node started with auth before the persisted cluster user existed, stop it and compare the current descriptor with the backup. A clean stop may have saved the skipped state without the cluster descriptor; restore the backed-up descriptor before retrying. Do not recreate clustered tables or delete their data.

Do not delete the rollout notes. They are usually the fastest way to see which client was updated, which token was stored where, and which permissions were created.

Symptom	Likely cause	Check
SQL access denied	Wrong user, wrong password, or client auth mismatch	Check the configured user and confirm the client can use `mysql_native_password`.
HTTP 401	Missing or invalid credentials	Check the `Authorization` header and whether the client uses Basic auth or Bearer token auth.
HTTP 403	User authenticated but lacks permission	Check `SHOW PERMISSIONS FOR '<user>'`.
Bearer token does not work	Token was lost, copied incorrectly, or already revoked	Run `TOKEN '<user>'`, store the returned token, and update the client.
User has fewer permissions than expected	Missing action grant	Check whether the operation needs `read`, `write`, `schema`, `replication`, or `admin`.
User has more permissions than expected	Broad target or missing explicit deny	Check wildcard grants, exact target grants, and any `WITH ALLOW 0` rules.
Distributed query is denied remotely	Shared user is missing, differs, or lacks permission on the agent	Compare the auth stores and permissions on the master and agent.
Existing cluster is skipped at startup	Persisted cluster user is missing from the auth store or lacks `replication`	Check `manticore.json`, `SHOW PERMISSIONS`, and the pre-cutover backup before restarting.
`failed to fetch donor user from any node`	No descriptor peer is available, or daemon-to-daemon authentication failed	Check the restart order, peer availability, and `searchd.log.auth` on both nodes.

Permission rules are determined by action type. When rules conflict, an explicit deny always takes precedence over an allow, even if the allow is more specific. If no matching allow exists, access is denied.

Final check

Before calling the rollout done, confirm that:

[ ] You used the procedure for the deployment's topology.
[ ] Every isolated part of the system that uses Manticore Search has its own user.
[ ] Every user has only the actions it needs.
[ ] Users shared between nodes have the same stored authentication material.
[ ] Bearer tokens are stored in a protected secrets store; raw tokens are not saved outside a controlled environment.
[ ] The operations team knows that SHOW TOKEN does not return the raw token, but shows its hash; use TOKEN or the HTTP endpoint to get a new token.
[ ] SQL and HTTP clients have been updated.
[ ] Expected denials were tested.
[ ] You tested distributed queries or replication operations when applicable.
[ ] Every migrated replication cluster is synced, and its existing data is present on every node.
[ ] Auth logs are visible.
[ ] The rollback procedure is clear and documented.

We wish you a smooth authentication and authorization rollout!

How to secure Manticore Search with built-in authentication and authorization

Sergey Nikolaev — Mon, 27 Jul 2026 05:54:33 +0000

Search is often treated as infrastructure. In production, though, it behaves much more like an application API. It accepts user traffic, exposes business data, powers dashboards, and often sits close to records that shouldn't be open to every client on the network.

Manticore Search now (since release 27.1.5 has built-in authentication and authorization for SQL over the MySQL protocol, HTTP/HTTPS endpoints, and replication-related operations.

Authentication answers "who is calling?" Authorization answers "what is this user allowed to do?"

Users who already work with Manticore can access the new functionality while keeping their familiar Manticore workflows. Existing SQL and HTTP clients retain their usual connection patterns. Applications require only minimal changes.

What Manticore Adds

SQL/MySQL password authentication with mysql_native_password.
HTTP Basic authentication with the same user name and password.
HTTP Bearer tokens for clients that shouldn't send a password on every request.
Permissions for five clear actions: read, write, schema, replication, and admin.
Targets such as products, logs_*, posts, and *.
SQL commands for managing users, tokens, and permissions.
Auth logging with disabled, error, warning, info, all, and trace levels. The default is info.

The access model is deliberately designed small. You just create users, grant the actions they need, update your app to send credentials, and test that denied operations are actually denied.

Enable Authentication

Authentication is controlled by the auth setting in the searchd section.

In RT mode, use auth = 1. Manticore stores auth data in auth.json under data_dir.

searchd {
    data_dir = /var/lib/manticore
    auth = 1
    auth_log_level = info
}

To disable authentication explicitly in RT mode, use auth = 0 or remove the setting.

In plain mode, set auth to the auth file path:

searchd {
    auth = /var/lib/manticore/auth.json
    auth_log_level = info
}

Use SSL for SQL connections or HTTPS for HTTP clients when passwords or bearer tokens cross a network.

Keep the auth file private. Before the first bootstrap, Manticore may create an empty auth file. After bootstrap, that file stores auth data and credential hashes.

Bootstrap the First Administrator

After enabling auth, start searchd. Then create the first administrator with the same configuration file:

searchd --config /etc/manticoresearch/manticore.conf --auth

For automation, use the non-interactive bootstrap mode:

printf 'admin\nStrongPass#2026\nStrongPass#2026\n' | \
  searchd --config /etc/manticoresearch/manticore.conf --auth-non-interactive

Bootstrap requires a running daemon. It creates the first administrator and grants that user all actions.

It doesn't return a bearer token. If the admin user needs HTTP Bearer access, connect as that admin and run TOKEN, or call the HTTP POST /token endpoint.

Create Users

After initializing the administrator, you can use the account to manage users and permissions through SQL commands. However, do not use it in the application. Instead, create separate users for specific tasks.

For example, a search frontend that only reads from products needs read, not write, schema, replication, or admin:

CREATE USER 'app_read' IDENTIFIED BY 'ReadPass#2026';
GRANT read ON 'products' TO 'app_read';

CREATE USER returns a raw bearer token for the new user. Store it immediately. Manticore won't show the raw token again.

To create or rotate a bearer token later:

TOKEN 'app_read';

TOKEN 'app_read' returns a new raw token that is ready to use. SHOW TOKEN shows the stored token hash, not the token to send in an HTTP request. This is useful for verification and audit: you can confirm that a token exists or changed after rotation without exposing the raw secret:

SHOW TOKEN FOR 'app_read';

SET PASSWORD changes the password used by SQL/MySQL and HTTP Basic auth:

SET PASSWORD 'NewReadPass#2026' FOR 'app_read';

It doesn't revoke existing bearer tokens. To rotate Bearer access, create a new token with TOKEN or POST /token:

TOKEN 'app_read';

An ingest pipeline can get write without broader access:

CREATE USER 'app_ingest' IDENTIFIED BY 'IngestPass#2026';
GRANT write ON 'products' TO 'app_ingest';

A table schema migration job can get schema:

CREATE USER 'schema_job' IDENTIFIED BY 'SchemaPass#2026';
GRANT schema ON 'products' TO 'schema_job';

An auth administrator can get admin privileges:

CREATE USER 'security_admin' IDENTIFIED BY 'AdminPass#2026';
GRANT admin ON * TO 'security_admin';

admin privileges only manage authentication and authorization state. They don't imply read, write, schema, or replication. Grant those separately when the same user really needs them.

Connect with SQL and HTTP

mysql clients authenticate with a Manticore user name and password:

MYSQL_PWD=ReadPass#2026 \
  mysql -h127.0.0.1 -P9306 -uapp_read \
  -e "SELECT * FROM products LIMIT 10"

HTTP/HTTPS clients can use Basic authentication:

curl -u app_read:ReadPass#2026 \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "SELECT * FROM products LIMIT 10"

They can also use a bearer token returned by the CREATE USER, TOKEN, or POST /token commands:

curl -H "Authorization: Bearer <app_read_token>" \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "SELECT * FROM products LIMIT 10"

The Basic and Bearer authentication schemes are case-insensitive. User names are case-sensitive.

The permission check is the same either way. The client authenticates, Manticore identifies the user, and checks the requested action against that user's permissions.

Testing After Enabling Authentication

Tip: when enabling access to Manticore, don't stop at confirming that the client can connect after authentication is enabled. Also test denied access and how your application reacts to it.

The app_read user should be able to read from products:

curl -H "Authorization: Bearer <app_read_token>" \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "SELECT * FROM products LIMIT 10"

The same user shouldn't be able to write to products:

curl -H "Authorization: Bearer <app_read_token>" \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "INSERT INTO products(id,title) VALUES(1,'test')"

That error is expected. Over HTTP, a valid user without permission gets 403 Forbidden. Over SQL/MySQL, Manticore reports ERROR 1045 with a permission-denied message.

How Manticore Checks What Is Allowed and Denied

Manticore permissions are action and target rules. If no rule allows the requested action on the requested target, access is denied.

The short version:

Rules are matched for the requested action only. admin doesn't satisfy read, write, schema, or replication.
WITH ALLOW 0 creates an explicit deny.
Any matching explicit deny wins, including over more specific allow rules.
If no matching allow exists, access is denied.

For example:

CREATE USER 'analyst' IDENTIFIED BY 'AnalystPass#2026';
GRANT read ON * TO 'analyst';
GRANT read ON 'private_logs' TO 'analyst' WITH ALLOW 0;

The analyst user can read other tables, but can't read private_logs.

A wildcard deny plus an exact allow can't be used as an exception pattern. If the deny matches the request, it still wins.

Roll Out Access on an Existing Deployment

For an existing Manticore deployment, handle auth as a staged rollout rather than switching everything at once:

Inventory SQL and HTTP clients that connect to Manticore.
Choose the auth file path: auth.json under data_dir in RT mode, or an explicit path in plain mode.
Enable auth in staging.
Bootstrap the first administrator.
Create least-privilege users for search, ingest, schema changes, replication, and auth administration.
Update your application's SQL connection code to send user names and passwords.
Update your HTTP/HTTPS connection code to use Basic authentication or Bearer tokens.
Verify expected success and expected denial for each application user.
Configure an appropriate auth logging level and make sure the log is stored safely with the rest of your operational logs.
Roll out gradually, and after cutover rotate credentials for extra safety and an additional test and training pass.

Distributed tables need one extra check. Remote-agent queries authenticate as the current session user, so the remote daemon needs matching auth material for that user and the required permission on the remote target table.

Replication clusters use the replication action. When auth is enabled, cluster joins can replace local auth data with auth data from the donor cluster, so keep auth material consistent across nodes before joining. During cluster work, handle the auth log (by default, the searchd.log.auth file) carefully because it can contain salts and credential hashes.

Full Reference

The manual page covers the full command set and operational details for the new functionality, including password policy, auth logging levels, SHOW USERS, SHOW PERMISSIONS, RELOAD AUTH, distributed remote agents, and replication clusters:

Authentication and authorization manual

But for most applications, the path is direct: enable auth, bootstrap an admin, create least-privilege users, update clients, and verify that the right requests are allowed while the wrong ones are denied.

Meilisearch vs Manticore: Setting the Record Straight

Sergey Nikolaev — Fri, 24 Jul 2026 13:41:44 +0000

A few days ago, Meilisearch published a comparison of Meilisearch and Manticore Search. We like comparisons — we published our own back in 2023, with benchmarks you can reproduce. And to be fair, parts of the Meilisearch's comparison are accurate and even generous toward Manticore.

But several claims about Manticore are outdated or simply not what you observe when you run the current version. So instead of arguing, we did what we always do: spun up the latest versions of both engines (Manticore Search 28.4.4 and Meilisearch 1.41/1.48) and tested the claims. Every command and response below is real — feel free to copy-paste and check us.

"Full-text search and real-time analytics" — that's maybe 1% of it

The article introduces Manticore like this:

Manticore Search is an open-source search engine built as a continuation of Sphinx, improving its functionality with full-text search and real-time analytics.

Sphinx already was full-text search, and real-time analytics is a small slice of what's been added since. Here's what "improving its functionality" actually looks like over the years:

RT mode — Sphinx had RT indexes, but now the whole engine runs without config files: CREATE TABLE, insert, and search on the fly
Replication — Galera-based synchronous cluster replication
A full HTTP JSON API — nearly everything SQL can do, plus Elasticsearch-compatible bulk endpoints
Auto-schema — insert data without creating a table first
Vector search with auto-embeddings, quantization, and filtered KNN
Hybrid search — full-text + semantic fused with Reciprocal Rank Fusion in one query
Fuzzy search and autocomplete — typo tolerance, keyboard-layout awareness, suggestions
Columnar storage and secondary indexes — for datasets larger than RAM
Sharded tables, authentication, and conversational search
Kafka integration, Kibana and Grafana support, an MCP server for AI assistants

"Sphinx plus real-time analytics" undersells that by a wide margin.

"Complex setup" and "advanced customization"? Let's count commands

The article's verdict on Manticore:

Best for: Large-scale projects and teams that need advanced customization, SQL familiarity, and high-performance querying at scale.

And among the cons: "Complex setup: Initial configuration and tuning can be time-consuming."

Here is the entire "complex setup" of Manticore, from zero to searching — three commands, no config files, no schema:

1. Install (and start — the one-line installer launches the service too):

curl https://manticoresearch.com | sh

2. Insert a document. Note there's no table yet — auto-schema creates it from the data:

curl -s 0:9308/insert -d '{
  "table": "products",
  "doc": {"title": "yellow travel backpack", "price": 4990, "color": "yellow"}
}' | jq

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

3. Search — full-text match plus a filter on a numeric field, immediately:

curl -s 0:9308/search -d '{
  "table": "products",
  "query": {"bool": {"must": [
    {"match": {"*": "backpack"}},
    {"range": {"price": {"lt": 6000}}}
  ]}}
}' | jq

{
  "took": 0,
  "timed_out": false,
  "hits": {
    "total": 1,
    "total_relation": "eq",
    "hits": [
      {
        "_id": 8938969113712132097,
        "_score": 1356,
        "_source": {
          "title": "yellow travel backpack",
          "color": "yellow",
          "price": 4990
        }
      }
    ]
  }
}

Everything is queryable the moment it lands in the table: text fields are full-text searchable — per-field too, e.g. {"match": {"color": "yellow"}} — and attribute fields like price are filterable, sortable, groupable, and facetable, with no declarations and no re-indexing. Here's the schema Manticore inferred on its own:

+-------+--------+----------------+
| Field | Type   | Properties     |
+-------+--------+----------------+
| id    | bigint |                |
| title | text   | indexed stored |
| color | text   | indexed stored |
| price | uint   |                |
+-------+--------+----------------+

Now the same task in Meilisearch (we tested both the latest Docker tag, v1.41.0, and the newest release, v1.48.3). Meilisearch's installer downloads a binary into the current directory, which you then run yourself — and in production mode you'll also need to configure a master key before it starts. Adding documents and searching is just as easy as in Manticore — credit where due. But then you try to filter:

curl -s -X POST localhost:7700/indexes/products/search -H "Content-Type: application/json" \
  -d '{"q": "backpack", "filter": "price < 6000"}' | jq

{
  "message": "Index `products`: Attribute `price` is not filterable. This index does not have configured filterable attributes.",
  "code": "invalid_search_filter",
  "type": "invalid_request"
}

Since we were re-checking everything for this post anyway, here's precisely what does and doesn't work out of the box in Meilisearch — each point verified against the docs and a live instance:

Searching works immediately. By default searchableAttributes is ["*"] — every field of every document is searchable, no declarations needed.
Filtering doesn't. Fields must first be declared in filterableAttributes. Meilisearch's documentation is upfront about the cost: "This step is mandatory and cannot be done at search time. … Updating filterableAttributes requires Meilisearch to re-index all your data, which will take an amount of time proportionate to your dataset size and complexity."
Faceting doesn't either. Facets are built on the same filterableAttributes list, so the same declare-and-reindex step applies. In Manticore, faceted search needs no manual filter building at all.
Sorting doesn't. Per Meilisearch's docs: "To allow your users to sort results at search time you must … add those attributes to the sortableAttributes index setting."
Tuning search fields re-indexes too. The order of searchableAttributes determines relevancy, so restricting or re-ordering it is a step most real projects take — and "updating searchableAttributes triggers a re-indexing of all documents in the index."

None of this is a bug — it's a design trade-off, and each step is one small API call. But it adds up to a model where you declare capabilities attribute by attribute and pay a full, dataset-proportional re-index every time you change your mind. Manticore's model is different: fields have types — text fields are full-text searchable, attributes (numbers, strings, JSON) are filterable, sortable, groupable, and facetable, vectors are KNN-searchable — and every capability of a type is available from the moment of insert. There's no per-attribute capability registry to maintain, and no re-indexing to change how you query. Deep customization — ranking formulas, tokenization, morphology, per-field weights — is absolutely there (the article's pros list is right about that), but it's opt-in, not a prerequisite. Which is why we're not sure "needs advanced customization" is pointing at the right engine.

"SQL familiarity" — optional, not required

The article frames Manticore as the choice for "teams with SQL familiarity." SQL support is a distinctive Manticore strength — you can talk to it with any MySQL client, mysqldump, or a BI tool (a capability the comparison's own integrations table marks as "Not supported" in Meilisearch).

But notice what you just read above: the entire quick-start demo was JSON over HTTP. Practically everything in Manticore is available both ways — SQL for those who like it, a JSON API very similar to what Meilisearch and Elasticsearch users are used to. You don't need to write a single line of SQL to use Manticore.

Vector search: Meilisearch's own table says it best

This is our favorite part. The use-cases table in Meilisearch's article rates the two engines on vector search:

Vector search. Meilisearch: Basic vector search. Manticore Search: Better suited for hybrid and advanced setups.

We agree with both columns. Here's what "hybrid and advanced setups" looks like in practice with auto-embeddings — no external embedding pipeline, no API keys, the model downloads automatically:

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

Insert documents as plain JSON — embeddings are generated for you (there's also a /bulk endpoint for batches):

curl -s 0:9308/insert -d '{
  "table": "products_ai",
  "id": 1,
  "doc": {
    "title": "green hiking backpack",
    "description": "Lightweight backpack suitable for hiking trails",
    "price": 5999
  }
}'

curl -s 0:9308/insert -d '{
  "table": "products_ai",
  "id": 3,
  "doc": {
    "title": "trail running shoes",
    "description": "Lightweight shoes with great grip for trails",
    "price": 7500
  }
}'

And run a hybrid search — full-text and semantic search fused with RRF — in a single request:

curl -s 0:9308/search -d '{
  "table": "products_ai",
  "hybrid": {"query": "gear for a mountain hike"},
  "_source": ["title", "price"],
  "size": 2
}' | jq

{
  "hits": {
    "hits": [
      {
        "_id": 1,
        "_knn_dist": 0.88308269,
        "_hybrid_score": 0.01639344,
        "_source": {
          "title": "green hiking backpack",
          "price": 5999
        }
      },
      {
        "_id": 3,
        "_knn_dist": 1.09160841,
        "_hybrid_score": 0.01612903,
        "_source": {
          "title": "trail running shoes",
          "price": 7500
        }
      }
    ]
  }
}

No document mentions the word "gear" or "mountain" — that's semantic understanding out of the box, two requests total. Under the hood there's vector quantization to cut RAM usage, KNN prefiltering so filters work inside the HNSW traversal, and continuous KNN performance work. "Better suited for hybrid and advanced setups" — yes, we'll take that.

And you don't have to take our word for it — these live demos all run on Manticore: catalog search with filters, facets, typo tolerance, and semantic search; reverse image search; and conversational search.

Relevance: measured, not argued

Search-quality claims can be tested empirically. We benchmarked Manticore Search and Meilisearch in full-text, vector, and hybrid modes across 14 public IR dataset/corpus-size groups: seven BEIR datasets, ACORD, MS MARCO Passage at 250K and 8.8M documents, TREC DL 2019/2020, Wayfair's WANDS product-search dataset, and the typo-focused DL-Typo. For each engine/mode pair, we select its best completed run in each group and compute an unweighted average across the groups. The first row then selects each engine's best mode per group before averaging. Vector and hybrid runs use the same Qwen3-Embedding-8B model on both engines. Quality is scored with each dataset's canonical metric: NDCG@10, or MRR@10 for MS MARCO.

Mode	Manticore	Meilisearch
Best mode per dataset (average)	0.543	0.527
Vector	0.530	0.527
Hybrid	0.515	0.475
Full-text	0.420	0.237

Comparing each engine's best result per group, Manticore leads on 11 of the 14. Vector quality is nearly tied at 0.530 and 0.527; both engines use the same embedding model, while their indexing and retrieval implementations still differ. The hybrid results show a wider difference, with Manticore's RRF averaging 0.515 against 0.475.

Full-text has the largest gap: 0.420 against 0.237. The wider benchmark helps explain why. The engines using BM25 or a BM25-family ranker cluster well above Meilisearch in full-text relevance. Meilisearch instead applies an ordered set of rules based on matching words, typos, proximity, attributes, and exactness. It therefore lacks BM25's combination of inverse document frequency, term-frequency saturation, and document-length normalization, which is the main reason it performs poorly on these standard IR datasets. Typesense, another engine in the wider comparison that does not use BM25, shows a similar pattern. Meilisearch's ten-word query limit can hurt longer queries further because the remaining words are ignored.

Manticore also leads on DL-Typo, which focuses specifically on typo robustness.

The same harness also tests Elasticsearch, OpenSearch, Qdrant, Typesense, Vespa, and Weaviate. Some engines could not complete the largest tests with the resources available on the benchmark server, so the report provides two coverage-controlled leaderboards. Recomputed over the ten-group subset covered by all eight engines, Manticore's best-mode average places second overall, behind Qdrant. Across all 14 groups, it also places second among the five engines with complete coverage. Meilisearch records a lower average in both comparisons.

The full comparison already includes coverage, per-dataset tables, and exact per-run configurations. This work is still in progress though. We'll publish the complete methodology and remaining details soon. We'll also release our new benchmarking tool as open source, making benchmarks like this much easier to run and extend.

"Primarily used for complex, large-scale workloads" — the data says otherwise

The article claims:

Manticore is primarily used for complex, large-scale search and analytics workloads that require high performance and deep customization.

And in the use-cases table, Manticore "may be overkill for simple CMS needs."

We checked our anonymized telemetry. Among Manticore instances that report data-size metrics:

29% hold less than 1 MB of data
about half hold less than 100 MB
only about one in eight exceeds 10 GB, and fewer than 1% exceed 1 TB

So no — Manticore is not primarily used for large-scale workloads. Most real-world Manticore installations are small projects: sites, catalogs, blogs, internal tools. Exactly the "simple CMS needs" the table warns you about. A Manticore container idles at under 200 MB of RAM, and as you saw above, a working search takes three commands — it's hard to call that overkill for anything.

The nice part is that the same engine also holds up at the other end: Locally serves tens of thousands of queries per second on Manticore after migrating from Elasticsearch. Scaling down and scaling up aren't mutually exclusive.

Real-time analytics: we'll be honest here too

Curiously, the same table gives Manticore a compliment we'd soften ourselves: "Designed for real-time data and analytics." Manticore has solid analytics capabilities — columnar storage, aggregations, Kibana and Grafana integrations, log-pipeline integrations — and it's well-suited for log search. But it is first and foremost a search engine. Analytics is one of its use cases, not what it's "primarily designed" for, and not what most of our users run it for.

Where Meilisearch's article has a point

We promised facts, and facts cut both ways:

Typo tolerance by default. True: Meilisearch ships with typo tolerance on. In Manticore, fuzzy search is opt-in — min_infix_len='2' in the table definition and fuzzy=1 at query time. Two small settings, but Meilisearch's default is the friendlier one.
Querying straight from the frontend. Meilisearch's search API keys make backend-less search a first-class pattern. Manticore has traditionally lived behind a backend; authentication arrived in 27.1.5, so that gap is closing, but today the point goes to Meilisearch.
Documentation gaps. Every project has them, including us — and including Meilisearch. We'd just push back on "steep learning curve": if you know a bit of SQL or a bit of JSON, you know enough to start, and there are free interactive courses that walk you through everything from first table to vector search.

Client libraries: the table, completed

Since this post is a response to Meilisearch's comparison, let's fix its integrations table too. The original lists Go twice with contradictory answers ("supported via community" and "not supported"), gets several official/community statuses wrong — on both sides, in both directions — and skips two languages entirely. Here it is again, checked against Meilisearch's own SDK docs and Manticore's GitHub org:

Integration	Meilisearch	Manticore Search
JavaScript (Node.js)	Official client (TypeScript-based)	Official JavaScript client
TypeScript †	Same official TypeScript client	Official TypeScript client
Python	Official client (sync + async)	Official sync and asyncio clients ✱
PHP	Official client	Official PHP client
Java	Official client	Official Java client
Go	Official client ✱	Official Go client
Rust	Community-maintained client ✱	Official Rust client ✱
Elixir †	Not listed in Meilisearch's SDK docs	Official Elixir client
Dart/Flutter	Official client	No official client (HTTP JSON API)
.NET/C#	Official client ✱	Official .NET client
REST API	Core interface	Full HTTP/JSON API
SQL	Not supported	Native SQL (MySQL protocol)

† — language missing from the original table • ✱ — status corrected vs the original table (for the Meilisearch column, per Meilisearch's current SDK docs)

Adding it up across the ten languages above: Manticore ships official clients for nine — everything except Dart/Flutter. Meilisearch ships official clients for eight — everything except Rust (community-maintained) and Elixir (not listed). Both cover REST in full, and Manticore additionally speaks SQL over the MySQL protocol. So "a wide range of clients" — the one thing the original article does say about Manticore's integrations — is accurate; the details just needed refreshing.

The bottom line

Meilisearch is a good search engine, and the article gets a real thing right: it's polished for the instant-search, frontend-first use case. If you're choosing for the long haul, though, weigh the cons Meilisearch's own article lists too — for instance, that a search query "must involve no more than ten words; any more will be ignored." Limits like that tend to matter more in month six than on day one.

But the bigger issue is that the Manticore the article describes — a complex, SQL-only system for large-scale analytics teams — isn't the Manticore that exists in 2026, and most of it you can disprove in about five minutes of terminal time:

curl https://manticoresearch.com | sh

Then insert a JSON document and search it (more on the one-line installer). No schema, no config, no "advanced customization." If you want numbers rather than words, the relevance results above, our benchmark-backed comparison, and db-benchmarks.com are good places to start — and if we got anything wrong about Meilisearch here, we'll happily correct it. That's how we'd want to be treated, too.

Questions or disagreements? Come tell us in the forum or Slack.

Built-in authentication and authorization for Manticore Search

Sergey Nikolaev — Thu, 23 Jul 2026 04:57:42 +0000

Search is no longer just a box on a website. In many deployments, Manticore Search behaves more like an internal data service: applications query it, ingest workers update its tables, dashboards read from it, and operators change schemas. When all of that relies only on network-level trust, the access-control story gets weak quickly.

That is why Manticore Search now has built-in authentication and authorization. Introduced in the 27.x release line and published in the 27.1.5 release post, it lets Manticore check who is connecting and what that user is allowed to do.

The feature works across SQL, HTTP/HTTPS clients, distributed remote agents, and replication-related operations.

What Manticore adds

Manticore now supports authentication and authorization for the core access paths:

SQL/MySQL clients authenticate with a user name and password.
HTTP clients can use Basic authentication or Bearer tokens.
Permissions are granted by action and target.
Auth events can be logged at configurable levels.
Users and permissions are managed through dedicated SQL commands.

The authorization model uses five actions:

read for search and read-only access.
write for data changes.
schema for table and schema management.
replication for cluster operations.
admin for authentication and authorization management.

Targets are plain names and wildcards, for example products, logs_*, or *. That keeps the model close to how people already think about Manticore tables and clusters.

What changes for operators

It is common for a client application to be able to search a table without having permission to write to it. A data ingestion process may update documents without changing the schema. A schema migration task may run without being granted security administrator privileges. An operator can manage authentication and authorization without automatically gaining read access to business data.

Those permission boundaries matter once search becomes a part of shared infrastructure. The point is not just to keep outsiders out; it is to keep each trusted client limited to what it actually needs.

Manticore now gives those controls a native home. Users authenticate through the protocols they already use. Manticore checks permissions against actions and targets. Operators manage access with SQL commands. Applications keep their normal SQL or HTTP integration pattern.

Why this matters for SaaS and shared search

SaaS and shared-service teams often need one search layer to serve several products, teams, or tenants. Some integrations are customer-facing, some are internal tools, and some run in the background. They should not all inherit the same level of trust.

Before built-in auth, teams had to solve much of that outside Manticore. A common workaround was to put nginx in front of Manticore and rely on HTTP Basic authentication there. That could protect one entry point, but it did not give Manticore its own user and permission model. Now teams can model more of it directly where the data is served.

That makes Manticore easier to use for customer-facing search over sensitive data, internal tools with different permission levels, and shared search clusters used by multiple services.

Authentication and authorization are not a compliance program by themselves. Still, they are the kind of control reviewers expect to see. For GDPR, SOC 2, and internal security reviews, it helps to show named users, limited permissions, and authentication logs instead of a shared credential that can do everything.

Rollout notes

Operators can enable authentication, bootstrap the first administrator, and then manage users and permissions with familiar SQL commands. Applications do not need a new Manticore-specific gateway just to start sending credentials. SQL clients use usernames and passwords. HTTP clients use Basic authentication or Bearer tokens.

For existing deployments, treat the switch as a rollout, not just a config change. By default authentication is disabled until configured. Once it is enabled, clients that do not send credentials should fail, so update your application first and test expected denials before switching production traffic.

For distributed or replicated topologies, plan the rollout carefully. Upgrade remote agents and replication peers first, then upgrade the masters that query or manage them, and enable auth only after the whole topology is on a compatible version.

Learn more

For a hands-on walkthrough, see the practical launch post:

How to secure Manticore Search with built-in authentication and authorization

For existing deployments, see the rollout checklist:

Manticore Search authentication rollout checklist for existing deployments

For the full reference, see the manual page:

Authentication and authorization manual

Turbopuffer vs. Manticore Search on a couple of cheap VPS

Sergey Nikolaev — Thu, 16 Jul 2026 05:42:27 +0000

Serverless vector databases are marketed on a simple promise: you don't run anything, you don't tune anything, and someone else worries about storage, scaling and uptime. turbopuffer is one of the better examples of the category: a fast search engine built on object storage, used by Cursor, Notion, Linear and others.

The promise is real, but it isn't free. So the obvious question is: for a small, well-defined workload, how much of that do you actually need, and what does the same workload cost and perform like on two cheap VPS running Manticore Search?

This article answers that with numbers from an apples-to-apples benchmark on the same dataset.

The workload

We took a concrete, modest workload, the kind a lot of real applications actually have, and sized turbopuffer for it:

Parameter	Value
Dataset	DBpedia (OpenAI embeddings)
Stored documents	975k
Vector dimensions	1536 (cosine similarity)
turbopuffer latency P50 / P90 / P99 (advertised, warm namespace)	14 / 17 / 27 ms
turbopuffer estimated cost	$75 / month (July 2026)

The two turbopuffer numbers in that table are its advertised latency and its calculator-estimated cost, not measurements. The cost comes from turbopuffer's cost calculator, and the latency is turbopuffer's published target: specifically the warm-namespace P50/P90/P99 from its own benchmark:

Two caveats come straight from that screenshot. First, those 14/17/27 ms are for a warm namespace; the same benchmark reports 874 / 1214 / 1686 ms for a cold one. A namespace that has aged out of cache is ~50–60× slower on its first queries, a direct consequence of turbopuffer's object-storage tiering. Second, turbopuffer's benchmark runs a different workload (1024 dimensions, 10M docs) than ours (1536 dimensions, 975k docs). turbopuffer's actually measured latency and throughput on our dataset are reported further down, and they differ from these advertised figures. Our benchmark dataset is 975k docs (DBpedia); both systems were loaded with the same data.

That $75/month comes straight from turbopuffer's own cost calculator for 1536-dim vectors with no attributes (the calculator's "Attributes: None"). This matches our benchmark, which was pure vector search: no stored attributes and no metadata filtering on either side. Both engines support attribute filtering and full-text search (Manticore also adds hybrid search); we simply didn't exercise it here, so the comparison is like-for-like on plain KNN. The pricing is usage-based, and the breakdown is the interesting part:

Component	Rate	This workload	Cost
Storage	≤ $0.33 / GB	1M docs (~3 GB)	$1.01
Writes	≤ $2.00 / GB	10M writes, ~4 WPS (~61 GB)	$61.44
Queries	≤ $1.00 / PB	10M queries, ~4 QPS (~13 PB)	$12.80
Namespaces	n/a	100 × 10K docs	Included
Total			$75 / month (min $16 Launch plan)

The headline number is almost entirely writes: $61.44 of the $75 is the cost of ingesting ~61 GB of vector data, while storage (3 GB) is a rounding error.

The "~13 PB" against the query line looks alarming but is a billing abstraction, not bandwidth. turbopuffer meters queries by "GB queried" with a minimum billable of 1.28 GB per query, so the calculator simply computes 10M queries * 1.28 GB ≈ 13 PB. The data actually moving per query is tiny (a 1536-dim float32 query vector is ~6 KB in, a top-10 result is a few KB out), yet every query on a namespace this small just bills at the 1.28 GB floor. At ≤$1/PB that whole 13 PB costs only $13, so query pricing is trivial here.

This matters for the comparison because on a self-hosted engine none of these meters exist: writes are just CPU time, queries have no per-query floor, and there is no per-GB charge at all. (turbopuffer pricing, pricing changelog)

The contenders

turbopuffer is serverless for the user: storage lives on S3/GCS/Azure object storage (~$0.02/GB), with hot data tiered through NVMe and RAM caches. You never provision or patch a server, never manage replication, never do capacity planning. You pay per GB stored / written / queried, and query compute runs on turbopuffer's managed infrastructure rather than on hardware you provision.

Manticore Search is software you run yourself. For this comparison we used the cheapest realistic setup that still gives you redundancy:

Parameter	Value
Nodes	2 × Hetzner CX23 (region "eu-central") in a cluster
Cost per VPS	$8.25 / month
CPU per VPS	2 cores
Disk per VPS	40 GB (table data uses ~6 GB)
Role of 2nd node	Replica for redundancy
Manticore total cost	$16.50 / month (or $8.25 for a single node if you don't need redundancy)

Manticore stores vectors in an HNSW index (via the Manticore Columnar Library) and supports scalar quantization (8-bit and 1-bit) with oversampling and rescoring to trade memory and speed against recall. For this test we used 1-bit (binary) quantization with oversampling=2.0 and rescoring, settings chosen specifically to land at roughly the same recall as turbopuffer, so the latency and throughput numbers are compared at equal quality.

Bottom line first

	turbopuffer	Manticore (2× cheap VPS)
Monthly cost	$75	$16.50 (high-availability mode) / $8.25 (single node)
recall@10 (5k queries)	0.9622	0.9663
Query latency P50 / P90 / P99 (end-to-end)	21 / 24 / 30 ms (incl. network round-trip)	10 / 13 / 16 ms (local, no network hop, fully compacted)
Read (query) throughput ceiling	~300 QPS unbatched (concurrency=8); ~800–1,100 QPS with query batching	~330 QPS (concurrency=2, unbatched)
Sustained write throughput	~1150 docs/s (bulk load)	490-1100 docs/s (bulk load)
Ops burden	None (fully managed)	You run & maintain it

On this workload, Manticore on two $8.25 VPS is ~4.5× cheaper, matches turbopuffer on recall, and, once the table is compacted (its steady state), is actually faster end-to-end (~10–13 ms vs turbopuffer's ~21 ms in-region), because a local query skips the network round-trip turbopuffer always pays. turbopuffer, in turn, reaches a higher query-throughput ceiling, but only with query batching (~800–1,100 QPS vs ~330 on two 2-core VPS); unbatched from a single machine the two are comparable (~300 QPS each). For a 4 QPS workload both have enormous headroom regardless. What you give up with Manticore is the "zero operations" part, which is the whole point of the rest of this article.

Quality: matched recall

There's no point comparing latency or cost unless both systems return results of comparable quality. Using the DBpedia dataset (1536-dim OpenAI embeddings, cosine similarity, 975k docs) and 5,000 queries:

System	recall@10
turbopuffer	0.9622
Manticore	0.9663

The two are within ~0.4 points of each other, close enough that the rest of the comparison is fair. Manticore reached this with binary quantization + oversampling=2.0 + rescoring: the binary vector representation is 32× smaller than float32, while rescoring recomputes final distances on the full-precision vectors for the top candidates.

Latency

The number that matters is the one you actually observe: end-to-end, from issuing the query to getting the answer. turbopuffer is a remote service, so that includes the network round-trip to the namespace's region. Measured from a machine in the same region as the namespace (gcp-europe-west3, same country as the query host):

turbopuffer (in-region, end-to-end):   P50=21ms   P90=24ms   P99=30ms

Run your application farther from the region and this rises with the distance (easily 100 ms+ across continents), so co-locating the two matters, and you always pay at least the in-region round-trip.

turbopuffer also reports two of its own internal timers: the time it spent running the search (~12 ms, and stable even under heavy load), and the total time on its side including requests waiting in line for an execution slot. We lean on those only to diagnose the throughput results below (the engine's own run-time stays fast under load), not as a latency figure, because any time a request waits is real latency you pay. And one point keeps the comparison honest: that ~12 ms is turbopuffer's own self-reported, engine-only time, excluding its internal queuing. Manticore has query profiling too, but we didn't isolate a single engine-only number equivalent to it; every Manticore figure here is end-to-end and already includes any internal queuing it does. So throughout this section we compare end-to-end against end-to-end, never turbopuffer's engine-only figure against Manticore's total.

Manticore's latency (queried locally, so end-to-end with negligible network) under a mixed 4 QPS + 4 WPS load (10-minute run) depends heavily on how many disk chunks the table has been compacted into. A freshly bulk-loaded real-time table is split into many chunks; Manticore's auto-optimize merges them over time, and each KNN query has to consult every chunk, so fewer chunks means faster queries:

The 32 / 16 / 8 / 4-chunk states above were produced deliberately, by optimizing to a fixed chunk count, to map out the latency curve. A real bulk load lands at far fewer: at our benchmark's batch=1000 the table settled at 7 chunks (1 insert thread) or 8 chunks (2 threads), so a freshly loaded table sits around the 8-chunk mark (~28 ms). The number you end up with is really a race between two processes: inserts flush RAM chunks to disk, and auto-optimize merges those disk chunks in the background. The faster you ingest, the faster new disk chunks pile up, so a high-throughput load (batch=1000) out-runs the background merger and leaves more chunks behind (7–8), while slow single-document inserts (batch=1) produce chunks slowly enough that auto-optimize keeps pace and the table ends at just 3 chunks, at a far lower ingest rate. So it's ingest rate, not concurrency per se, that drives the final chunk count. From whatever the load leaves behind, Manticore's auto-optimize then continues compacting toward 2 chunks (~13 ms avg).

The takeaway: chunk count is the single biggest latency lever. At 32 chunks Manticore is several times slower than turbopuffer's ~21 ms end-to-end. But auto-optimized to its default floor of 2 chunks (~12–13 ms) it's already faster end-to-end than turbopuffer, and fully compacted to a single chunk (~10 ms) faster still, all on $8.25 hardware. The reason is mostly structural rather than a difference in engine speed: both do the core search in roughly the same ~10–12 ms, but Manticore runs on your own VPS and can be queried over localhost/LAN, so it pays no network round-trip, while turbopuffer always pays at least the ~9 ms in-region hop. The end-to-end gap is essentially that network hop.

Read (query) latency, not write latency, tracks how compacted the table is, and keeping it compacted is Manticore's job, not yours. Auto-optimize runs in the background and merges chunks down to a target it maintains automatically (our table settled at 2 chunks). That target is a setting, not a chore: the optimize_cutoff option (per-table via CREATE/ALTER, or globally in searchd) controls it, so if you want the very best latency you can set optimize_cutoff=1 and the background optimizer will keep the table at a single chunk for you, with no manual step in steady state. The only real catch is timing: right after a large bulk load the table is still at many chunks and queries are slower until auto-optimize catches up. In our run, with 8 chunks left after the concurrency=2 load, the background optimizer took about 15 minutes to compact down to 2 chunks, during which query latency steadily improved. turbopuffer has no equivalent step at all, which is part of what you're paying the premium for.

Throughput

Because each query costs the ~12 ms of engine time plus a network round-trip, a single connection is limited to roughly 1 / (engine + round-trip) queries per second, so throughput is recovered by issuing queries concurrently, and the in-region numbers below reflect that.

turbopuffer, in-region, plain single queries (no batching). Adding concurrent connections lifts throughput, but only up to a point:

Unbatched throughput peaks around 8 connections (~296 QPS) and then falls (233 QPS at 16, 153 at 32) while end-to-end latency climbs steeply (P90 33 → 108 → 423 ms at 8 → 16 → 32 connections). Through all of it, turbopuffer's own reported server-side time stays flat at ~12 ms. Because that reported time doesn't move while end-to-end latency rises, the extra delay isn't captured by turbopuffer's own timers: the bottleneck could be on our machine, the transport path, or some portion of request handling outside those timers, and this benchmark can't distinguish them. What it does show is that simply raising unbatched concurrency past 8 didn't improve throughput from this one machine.

We therefore treat ~300 QPS as the observed unbatched ceiling from this single machine, not a documented turbopuffer service limit. (Whether more machines would push higher depends on what's actually saturating, a per-machine resource versus the shared path, which we didn't test.) The lever that took the same single machine well past ~300 was query batching.

Query batching, packing several queries into one request, amortizes the network round-trip and lifts throughput much higher, with a clear quality-of-service gradient:

~800 QPS cleanly: concurrency=4 / batch=8 held 821 QPS with total server-side time P50=15 / P90=20 / P99=29 ms.
~1,000–1,100 QPS with higher tail latency: concurrency=8 / batch=8 reached 1,015 QPS but P99 rose to 58 ms; conc 4 / batch 16 hit 1,105 QPS at P99=61 ms.
~1,170 QPS oversaturated: concurrency=8 / batch=16 served 1,169 QPS, but the total time per request ballooned (P99=455 ms, avg ~70 ms) even though turbopuffer's reported server search time was still only ~12 ms, i.e. requests spent hundreds of milliseconds waiting in line on the server. Not a sustainable operating point.

So the practical batched ceiling we observed on this dataset is roughly ~800 QPS cleanly, rising to ~1,100 QPS with elevated server-side tails, comfortably above the two VPS either way.

Three caveats on batching, though:

It only helps if you have many independent queries arriving at once to bundle into a single request: a high-traffic search backend can, but a typical "one user, one query" path can't, so for many real apps the relevant number is the non-batched ceiling above (~300 QPS), not the ~1,000+ headline.
The per-query latencies in batched mode are amortized, not wall-clock. A query that has to wait for a batch to fill experiences the batch-formation delay plus the request's own latency, so end-user latency under batching is higher than the amortized figure suggests.
It pushes complexity onto your application. You have to collect queries, hold them briefly to form a batch, fan the combined response back out to the right callers, and reason about partial failures, often inconvenient enough that teams simply don't do it.

Manticore, on the two 2-core VPS, after the initial load, serving queries while also taking 4 WPS of writes (queried locally, so no network round-trip):

Concurrent connections	Queries per second
1	154
2	329
4	287

Manticore tops out around 329 QPS at 2 connections; beyond that you're oversubscribing the 2 cores, so 4 connections is slightly slower. Unlike turbopuffer's unbatched decline, this is a hard ceiling: it's the engine on 2 cores, and the only way past it is more cores or more nodes, which costs more money.

These Manticore figures are unbatched, plain one-query-per-request, the same shape as turbopuffer's unbatched sweep above. Batching wouldn't lift Manticore's ceiling the way it does turbopuffer's: batching helps turbopuffer mainly by amortizing its ~9 ms network round-trip across many queries, but a local Manticore query has no such round-trip to amortize, and the real limit here is CPU on 2 cores, which batching doesn't relieve. So the fair like-for-like is unbatched-vs-unbatched, and there the two land close: turbopuffer ~296 QPS vs Manticore ~329. What differs is what each number means: Manticore's ~329 is a hard 2-core ceiling, while turbopuffer's ~296 is simply where our single machine topped out. Adding concurrency only made it worse, and we couldn't localize the cause (turbopuffer's self-reported engine time stayed flat, but that's its own number, not something this benchmark can verify). So ~300 was the practical unbatched limit in our setup, and the proven path beyond it on turbopuffer was query batching (~800–1,100 QPS from the same machine); on Manticore it's more hardware.

So on query throughput, turbopuffer's batched ceiling (~800–1,100 QPS, on its managed compute) is higher than two 2-core VPS (~330 QPS), while unbatched the two are comparable, and turbopuffer's query pricing is cheap (the whole workload's query bill was ~$13). Manticore scales by buying hardware; turbopuffer scales on infrastructure you don't manage. The one nuance in Manticore's favor: at low concurrency Manticore is actually faster per connection (154 QPS at 1 connection vs turbopuffer's 40), because a local query has no ~9 ms network round-trip to pay.

But for this workload the throughput axis is close to irrelevant. The target is 4 QPS, and both systems clear it by a huge margin: ~200× headroom for turbopuffer at clean latency, ~80× for Manticore. Throughput only becomes a deciding factor if you expect sustained query volume in the hundreds of QPS, at which point turbopuffer's higher batched ceiling is the safer bet and Manticore needs a bigger (pricier) cluster.

On the write side the two land closer together:

turbopuffer bulk load: 975k docs at ~1150 docs/s. This is the end-to-end rate we observed; what bounds it (its ingestion path, the network, or its own indexing) we can't tell from the outside.
Manticore bulk load (batch=1000): 750–1100 docs/s until the first disk chunk is flushed. Here the bottleneck is visible: HNSW graph construction on 2 cores, since adding insert workers barely helps (451 → 490 docs/s from 1 → 2 threads).

Ingestion in practice

Loading the full DBpedia set into Manticore (975k docs, 1536 dims, building the HNSW graph) took:

Concurrency	Batch	Rate	Wall time
1	1	365 docs/s	~45 min
1	1000	451 docs/s	~36 min
2	1000	490 docs/s	~33 min

For comparison, turbopuffer loaded the same data at ~1150 docs/s, roughly 2.3x faster than Manticore on these two cheap VPS. That's expected: turbopuffer builds the index on its own (larger, managed) compute, while Manticore is doing the HNSW graph construction on the 2 inexpensive CPU cores. So turbopuffer wins clearly on raw ingest speed, though for a one-time initial load, the difference is ~14 minutes vs ~33–36 minutes, a one-off cost either way.

After the initial load at batch=1000 the Manticore table sat at 7 disk chunks (1 insert thread) or 8 chunks (2 threads); adding insert workers doesn't help on a 2-core VPS. The final chunk count is driven by ingest rate rather than concurrency: inserts flush disk chunks while auto-optimize merges them in the background, so the faster you load, the more chunks the background merger is left behind by. A fast batch=1000 load leaves 7–8 chunks; slow single-document inserts (batch=1) produce chunks gently enough that auto-optimize keeps up and the table ends at only 3 chunks, but at a lower 365 docs/s instead of ~450–490. From there, Manticore's auto-optimize keeps compacting toward 2 chunks (its default target); lowering optimize_cutoff to 1 makes it maintain a single chunk, the lowest-latency state, automatically.

Storage and headroom

Manticore's table data for this workload is ~6 GB, against 40 GB of disk on each cheap VPS, so a single node has room for several times this dataset before you'd need a bigger plan. On turbopuffer, storage is billed at ≤$0.33/GB and came to just $1.01 for this dataset, genuinely negligible. As the cost breakdown above shows, the difference between $75 and $16.50 is not about storage; it's the per-GB write charge ($61.44) that Manticore simply doesn't have.

What you actually trade

The numbers favor Manticore on cost and on latency when the table is compacted. But the comparison isn't only numbers: turbopuffer's price buys things that don't show up in a latency table.

You give up (by self-hosting Manticore):

Zero operations. turbopuffer has no servers to patch, no replica to fail over, no disk to outgrow. With Manticore, that's your job (though compaction itself is automatic, see below).
Elastic scale and a higher throughput ceiling. turbopuffer separates storage and compute and scales each independently; you can go from 1M to 1B docs without re-architecting, and its managed compute reached ~800–1,100 QPS with batching where two 2-core VPS cap at ~330. Two fixed VPS have a fixed ceiling: raising it means buying more hardware.
Scale-to-zero economics. For spiky or tiny workloads, usage-based billing can undercut even a $16.50/month fixed cost: you pay for what you query.
A managed SLA (uptime guarantees, support) on the higher tiers.

You gain (with Manticore):

~4.5× lower cost on this workload: a fixed, predictable bill with no per-GB write charge and no per-query metering.
No network round-trip. Querying over localhost/LAN avoids the round-trip a remote service always costs you (a ~9 ms floor even when co-located, more across regions), so a compacted table is faster end-to-end.
Full control and data locality: your data on your servers, plus full-text search, filtering, hybrid search and SQL in the same engine.
Security and data sovereignty: your vectors and source documents never leave infrastructure you control, so nothing is sent to or stored by a third party. For teams with data-residency, GDPR, or confidentiality requirements that's often decisive: you own the encryption, network isolation, and access policy, and there's no external service to vet, trust, or breach. With a managed service the same data lives in the provider's cloud by design.
Dedicated compute on your own VPS: fixed, predictable resources that aren't shared with other tenants.

Conclusion

For a large, elastic, or bursty workload, or for a team that simply doesn't want to operate a database, turbopuffer's $75/month (and the managed, serverless model behind it) is easy to justify.

But for the very common case of a bounded workload (around 1M vectors, a few QPS/WPS) where someone is willing to run a couple of servers, two $8.25 VPS running Manticore deliver the same recall, comparable latency after auto-optimize (and better latency when compacted to one chunk, with no network round-trip), ample throughput headroom for the workload, and a ~4.5× lower bill. The catches are that you run and keep the cluster healthy, and that if you ever need many hundreds of QPS, turbopuffer's managed compute scales past two fixed cores.

The serverless premium is real value, not a markup. The question this benchmark answers is just how much of that value a small, well-understood workload actually consumes, and the answer is: often, not $75 worth.

Manticore Search 28.4.4: Faster KNN, better conversational search, easier installs and more faceting controls

Sergey Nikolaev — Tue, 14 Jul 2026 11:24:55 +0000

Manticore Search 28.4.4 has been released. This release brings faster KNN rescoring, more flexible conversational search, a simpler install and upgrade path, better faceting controls, per-table relevance defaults, and fixes across authentication, replication, SQL compatibility, distributed queries, and columnar/KNN internals.

This post is a catch-up for everything shipped from 27.2.0 through 28.4.4.

Upgrade Notes

Please review these before upgrading:

28.0.0 bumps the plugin ABI version SPH_UDF_VERSION to 12. External UDF, ranker, and token-filter plugin binaries must be rebuilt before loading them into this version. The change lets token-filter plugins receive long dict=keywords_32k tokens instead of silently bypassing values above the old 126-byte plugin limit. Existing table data and configuration remain compatible, and no index migration is required. Downgrade is possible if you also restore plugin binaries built for the older ABI and do not rely on the new long-token plugin behavior. (Issue #4667, PR #4668)
If authentication is enabled, prioritize the 28.4.x update. 28.4.2 fixes an authentication/authorization permission-check bypass in MySQL multi-statement execution. 28.3.4 also improves authenticated MySQL startup compatibility for Connector/J and PyMySQL, and 28.4.1 fixes authenticated replication-cluster restart recovery by persisting the stored replication user in cluster metadata. (PR #4713, Issue #4691, Issue #4705)
If you manage MCL separately from the daemon, upgrade it together with Manticore. This release includes MCL 13.7.0, the new embeddings_threads setting, and several columnar/KNN build, packaging, and cleanup fixes. Mixing an older library with a newer daemon is not recommended. (PR #169, PR #186, PR #4676)

Highlights

Faster KNN rescoring

KNN search now batches distance calculations during the rescore pass. After HNSW returns the candidate set, Manticore recomputes final full-precision distances and re-sorts the results. Batching that work reduces per-candidate overhead in the final stage of vector search.

For vector-heavy workloads, this takes work out of the part of the query that runs after candidate selection. Results do not change; the final ranking pass just has less overhead when many candidates are rescored.

Conversational search through SQL and HTTP

Conversational search is now available through the /search JSON API as well as SQL CALL CHAT. That makes it easier to use Manticore's chat flow from applications that already talk to the HTTP API and do not want to add a separate SQL path just for chat requests.

CREATE CHAT MODEL also gained custom_prompt support, so answers can follow application-specific instructions such as citation rules, tone, response length, or formatting. The feature is still built on the same Manticore Search flow: retrieve relevant documents from an existing vectorized table, build context, keep conversation history, and return an answer with supporting sources.

One-line installation

The quick-start install path is now simpler:

curl https://manticoresearch.com | sh

The same installer can also upgrade an existing installation, list available versions, switch between stable and development repositories, and install a selected version. Package managers still remain the source of truth for installed files, repositories, services, and dependencies; the new path just removes the manual setup steps around them.

For all options, run:

curl https://manticoresearch.com | sh -s help

Facets can keep zero-count buckets visible

Faceted search now supports zero-count facet buckets through SQL ZEROES and JSON "zeroes": true.

This is a small but important UI feature. In e-commerce-style filtering, you often want to keep an option visible even when the current filter combination gives it a count of 0. Combined with max-mode facet behavior, zero-count buckets make it easier to show selected, available, and currently unavailable choices without hiding part of the filter vocabulary from the user.

Better defaults for search relevance

Manticore now supports CREATE TABLE ... profile='relevance', plus stored per-table defaults for ranker and boolean_mode.

Based on our search quality tests, profile='relevance' and the ranking settings it enables improve relevance in many cases. The application also no longer needs to repeat the same ranking parameters in every request.

More control over embedding CPU usage

embeddings_threads caps the CPU threads used for auto-embedding inserts, ALTER TABLE ... REBUILD KNN, and text-to-vector KNN queries.

This matters on shared hosts and mixed workloads. Embedding generation and KNN rebuilds can be CPU-heavy; a server-level cap makes those jobs easier to schedule without letting them take over the whole machine.

Bug Fixes

This release includes 17 bug fixes. The most important ones are:

28.4.3 fixed incompatible multi-statement handling around COUNT(DISTINCT ...).
28.4.2 fixed an authentication/authorization permission-check bypass in MySQL multi-statement execution, so each statement in a multi-statement request is validated correctly under auth.
28.4.1 and 28.3.1 fixed replication-cluster recovery edge cases: authenticated cluster restart recovery and startup when a node was left alone in the cluster.
Distributed queries with remote stored fields now fail on remote GETFIELD fetch errors or malformed replies instead of returning apparently successful rows with empty or untrusted stored-field values.
Interrupted columnar/KNN merge cleanup now removes temporary component files, preventing orphaned .tmp.spc.* files from breaking later table rename, attach, or drop operations.
DBeaver compatibility improved by accepting simple single-table aliases in SELECT queries.
Connector/J and PyMySQL clients can now complete authenticated native-password login flows, and harmless session SET statements no longer fail under auth.
The built-in Ukrainian lemmatizer now normalizes apostrophe words correctly, so forms such as здоров'ям match здоров'я under lemmatize_uk_all.
Blended-keyword handling now honors the configured blend_mode, restoring separator-stripped variants consistently for indexing and keyword extraction.
RT auto-optimization no longer compacts a table below two disk chunks unless that lower cutoff is explicitly requested.
A crash involving percentiles aggregations together with terms aggregations in the same /search request on multi-chunk RT tables was fixed.
Long SQL parse errors now preserve UTF-8 character boundaries, so invalid queries containing Cyrillic and other multibyte text no longer produce truncated or corrupted error messages.

For the complete list, 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

Sharding in Manticore Search: automatic distribution and replication

Sergey Nikolaev — Fri, 03 Jul 2026 03:32:41 +0000

Search systems often start simple: one table on one server. That works until one of two things happens. Either a single query stops being able to use all the CPU you paid for, or a single server stops being enough — for capacity, for throughput, or for the simple fact that a server can fail and take your data with it.

The automatic sharding built into Manticore Search, available since release 27.1.5, addresses both issues by splitting a table into several smaller physical pieces (shards), that can be searched in parallel and placed on different nodes:

On a single node, sharding spreads concurrent writes across independent pieces and keeps each one small enough to stay fast.
Across a cluster, sharding distributes data over multiple nodes and — this is the main point — automatically replicates each shard and keeps that replication factor intact as nodes fail and recover.

The second part is the real reason most people reach for sharding: high availability. You declare how many shards you want and how many copies of each should exist, and Manticore handles placement, replication, and rebalancing. You don't script failover.

Below: both use cases, the machinery without drowning in internals, the commands you'll run, and the current limits.

Short glossary

Key terms:

Term	Meaning
Shard	One physical piece of a table — a real table that Manticore creates and manages for you. A table with `shards='4'` has four of them.
Replica	A copy of a shard on another node. Replicas are how data survives a node failure.
Replication factor (RF)	How many nodes hold a copy of each shard. `rf='2'` means every shard exists on two nodes.
Distributed table	The table you actually query. It has the name you gave it and transparently fans queries out to all shards.
Cluster	A Manticore replication cluster — the group of nodes between which data is replicated.
Master	The node that currently coordinates sharding operations (placement, rebalancing). Elected automatically.
Rebalancing	The automatic process that moves or copies shards when the set of nodes changes.

How to create a sharded table

Sharding in Manticore is driven entirely by two simple options on CREATE TABLE:

CREATE TABLE products (id bigint, title text, price float) shards='4' rf='2'

shards='N' — split the table into N physical pieces.
rf='M' — keep M copies of each piece across the cluster (the replication factor).

In the common case, that one CREATE TABLE is all you write. There is no separate "make this distributed" step, no manual agent= lists as in older manual sharding setups, and no per-node table creation. Manticore creates the physical shards, places them, sets up replication, and creates a distributed table named products on every node, so the application can use the same table name from any cluster node.

Use case A: sharding on a single node

Start with the case where you have a single server — perhaps a big, many-core one — and no cluster yet. In this setup, sharding is not about storage durability; it helps use that one machine more effectively. If all writes go into one real-time table, concurrent INSERTs contend on the same internal table locks. As the table grows, RAM-chunk merges get heavier and can slow down ingestion. Splitting that table into several independent shards helps on both fronts: writes spread across the shards, and each piece stays small. High availability isn't part of the picture yet — that needs more than one node — so this is purely a performance play.

The simplest form has no cluster and rf='1':

CREATE TABLE logs (id bigint, message text, ts timestamp) shards='8' rf='1'

This creates eight physical shards on the one node and a distributed table logs that points at all of them. How does that help on a single machine?

More concurrent ingestion. Each shard is an independent real-time table, so concurrent writes spread across them instead of serializing on one table's locks — the win the benchmarks below measure directly.
Smaller pieces stay fast. Real-time tables periodically merge their internal RAM chunks. A table split into shards keeps each shard's chunks smaller, so those merges use fewer resources and are less likely to slow inserts down.
Query parallelism (usually a small gain on one node). A distributed table searches its shards in parallel across the server's worker thread pool, so a single query can use several cores instead of one — bounded by searchd.threads and the number of physical cores. On a single node, though, this overlaps with pseudo-sharding, and the gain is usually small (~5–12%) — see the read benchmarks below.

If you've used Manticore's pseudo-sharding before, the goal may be familiar — use all the cores for one query — but the mechanism is different. Pseudo-sharding parallelizes a single physical table automatically at query time. Explicit sharding creates real shards you control: you decide how many, they're separate tables you can reason about, and — crucially — the same sharded table can later be spread across nodes without changing how your application talks to it.

The two are complementary, but they don't stack for free. Physical sharding — a distributed table over several local tables — already keeps the worker threads busy, so if you've explicitly sharded a table, enabling pseudo_sharding on top usually adds little and can even cost a bit of throughput. Test it both ways with manticore-load: run your workload with and without pseudo_sharding, and if it adds nothing on top of explicit shards, turn it off.

On a single node the replication factor must be 1: there's only one node, so there's nowhere to put a second copy. That's also the catch — single-node sharding gives you parallelism, not durability. For durability you need more than one node.

Use case B: multi-node sharding and automatic replication

This is what sharding is really for. Start from a replication cluster of several nodes (see Setting up replication for how to create one), then create the table inside that cluster with the cluster: prefix and an RF greater than 1:

CREATE TABLE mycluster:products (id bigint, title text, price float) shards='4' rf='2'

Here's what Manticore does for you:

Creates four shards.
Places them across the cluster's nodes in a balanced way.
Creates a second copy of every shard on a different node, because rf='2'.
Wires up replication between each shard and its replica.
Creates a distributed table products on every node, so any node can serve reads and accept writes.

From the application's point of view, nothing changed — you still INSERT INTO products … and SELECT … FROM products. Reads fan out across the shards and the results are merged; writes are routed to a shard. But now every shard lives on two nodes, and that's the property you care about: any single node can fail and the table stays fully available with no data loss.

The replication factor scales with your durability needs and your node count:

RF	Copies per shard	Survives	Typical use
1	1	nothing — a lost node loses its shards	single-node parallelism, dev/test, data you can rebuild
2	2	one node failure	the common production choice
3+	3 or more	multiple simultaneous failures	mission-critical, frequent-failure environments

The constraint is simple: you can't ask for more copies than you have nodes. rf='3' needs at least three nodes in the cluster. Manticore checks this when you create the table and tells you if the cluster is too small.

-- 6 shards, 3 copies each, across a 3+ node cluster
CREATE TABLE mycluster:events (id bigint, body text) shards='6' rf='3'

Putting it together: a multi-node walkthrough

Say you have a three-node replication cluster called mycluster (if you don't yet, Setting up replication walks through CREATE CLUSTER and JOIN CLUSTER). Create a sharded, replicated table from any node:

CREATE TABLE mycluster:products (id bigint, title text, price float) shards='4' rf='2'

Manticore creates four shards, puts two copies of each across the three nodes, and a distributed table products on every node. Check the placement:

SHOW SHARDING STATUS products;

-- illustrative output (abbreviated columns)
+-------+-------+--------+----+-----------+
| shard | node  | status | rf | rf_status |
+-------+-------+--------+----+-----------+
|     0 | node1 | active |  2 | ok        |
|     0 | node2 | active |  2 | ok        |
|     1 | node2 | active |  2 | ok        |
|     1 | node3 | active |  2 | ok        |
|     2 | node1 | active |  2 | ok        |
|     2 | node3 | active |  2 | ok        |
|     3 | node1 | active |  2 | ok        |
|     3 | node2 | active |  2 | ok        |
+-------+-------+--------+----+-----------+

Every shard appears on two distinct nodes — that's rf=2 — and every rf_status is ok. (The full result also includes table, cluster, and replication_cluster columns.) Now use it like any other table, from any node:

INSERT INTO products (id, title, price) VALUES (1, 'Wireless mouse', 19.99);
SELECT * FROM products WHERE MATCH('mouse');

The write is routed to a shard and replicated to that shard's other copy; the read fans out across all four shards and merges the results. Your application never names a shard.

Maintaining the replication factor

Setting rf='2' is easy. The hard part in any distributed system is honoring that condition over time, as machines fail and come back and as you add capacity. But you no longer have to worry about that. Manticore Search automates this work.

How it works in Manticore is that the cluster elects a master node that runs a coordination loop. It monitors the cluster's topology — which nodes are alive — and reacts to changes:

A node fails

Its shards now have fewer copies than RF requires. The master detects the missing node and tries to rebuild the missing replicas. If the cluster still has at least rf active nodes after the failure, it places new copies on active nodes that don't already hold them, restoring the replication factor. Queries keep working as long as at least one copy of each shard is still available.

Continuing the walkthrough above — if node3 goes down, SHOW SHARDING STATUS products shows the affected shards as degraded (one copy down, one still up):

-- illustrative: node3 is down
+-------+-------+----------+----+-----------+
| shard | node  | status   | rf | rf_status |
+-------+-------+----------+----+-----------+
|     1 | node2 | active   |  2 | degraded  |
|     1 | node3 | inactive |  2 | degraded  |
|     2 | node1 | active   |  2 | degraded  |
|     2 | node3 | inactive |  2 | degraded  |
|   ... | ...   | ...      |    | ...       |
+-------+-------+----------+----+-----------+

There are still two active nodes (node1, node2) and rf=2, so the master creates the missing copies of shards 1 and 2 on the active node that lacks them. While a new copy is being built it shows up as pending; once replication catches up it becomes active and rf_status returns to ok.

The important caveat: Manticore can only restore RF if there is somewhere to put the new copy. If the active node count drops below rf, the requested RF cannot be met yet: affected shards stay degraded with their surviving copy until a node returns or you add one. Manticore won't create another copy of the same shard on the same node, and it won't silently pretend RF is met. If no live copy of a shard remains, its status becomes broken; that case is covered below. For rf='1', a failed node's shards are simply gone — there was never a second copy.

A node joins

New capacity should be used. The master rebalances so the new node takes its share of the load. How it does this depends on the RF:

RF = 1: shards must be moved (there's only one copy, so it can't just be duplicated). Manticore moves them safely using a temporary internal cluster: it copies the data to the new node first and removes it from the old one only after that, so the shard always has an available copy.
RF ≥ 2: shards are replicated to the new node using the cluster's existing replication, then the distribution is rebalanced. No risky data movement, because another copy always exists.

Every copy of a shard is down

If all nodes holding a given shard are lost at once, that shard's rf_status becomes broken — there's no surviving copy to serve or to replicate from. The rest of the table keeps working; the broken shard recovers when one of its nodes returns. RF reduces the chance of this case: with rf='2' it takes two simultaneous failures of the right nodes, with rf='3' three.

All of this happens through an internal, ordered, rollback-aware operation queue, so a rebalancing operation either completes or is cleanly rolled back — even if the master node itself dies mid-operation, the next master cleans up the half-finished work. The point for you as an operator: you set RF once, and the cluster works to keep it true.

How it works under the hood (the short version)

You don't need this to use sharding, but it helps to know what's happening.

Physical shards are real tables. A table with four shards is backed by four real tables that Manticore creates and manages for you. You normally never touch them directly.
Your application talks to a distributed table. Manticore creates one named products on every node. In its internal definition, local shards are listed directly, and shards on other nodes are connected through agent. That's what makes SELECT … FROM products transparently hit everything.
Coordination state lives in the cluster. Manticore tracks its own internal metadata — shard placement, coordination state, and the pending-operation queue — so it always knows who holds what and what work is still outstanding. In a multi-node setup this state is replicated across the cluster, so every node shares the same view.
The master drives changes. Placement, replication setup, and rebalancing are computed by the master and pushed onto the queue as ordered commands with rollback instructions, then executed across nodes.
Replication reuses Manticore's clustering. The same proven replication mechanism Manticore already uses for clusters keeps shard replicas in sync.

Architecturally:

            CREATE TABLE ... shards='4' rf='2'
                          │
                          ▼
                  ┌────────────────┐
                  │ Manticore      │  computes placement,
                  │ elected master │  enqueues ordered ops
                  └────────┬───────┘
                          │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
    ┌──────────┐     ┌──────────┐     ┌──────────┐
    │  node1   │     │  node2   │     │  node3   │
    │ s0 s2 s3 │◄───►│ s0 s1 s3 │◄───►│  s1 s2   │   (each shard on 2 nodes = rf 2)
    └──────────┘     └──────────┘     └──────────┘
    distributed table "products" exists on every node
    (same placement as the SHOW SHARDING STATUS output above)

Operating a sharded table

Everything you'd expect to work, works — and there are a couple of sharding-specific commands for visibility.

Inspect the schema. DESC and SHOW CREATE TABLE work on the logical table; Manticore resolves them through the underlying shards:

DESC products;
SHOW CREATE TABLE products;

See where every shard lives and whether the RF is healthy. This is the command you'll watch during failures and rebalancing:

SHOW SHARDING STATUS products;

+-------+-------+--------+----+-----------+
| shard | node  | status | rf | rf_status |
+-------+-------+--------+----+-----------+
|     0 | node1 | active |  2 | ok        |
|     0 | node2 | active |  2 | ok        |
|   ... | ...   | ...    |    | ...       |
+-------+-------+--------+----+-----------+

It reports one row per shard copy, with these columns:

Column	Meaning
`table`	the logical table name
`shard`	shard number
`node`	the node holding this copy
`status`	`active`, `inactive` (node down), or `pending` (being created)
`cluster`	the replication cluster the table belongs to
`replication_cluster`	the internal cluster that keeps this shard's copies in sync
`rf`	how many copies this shard currently has
`rf_status`	`ok` (RF satisfied), `degraded` (some copies down but at least one up), or `broken` (no copies up)

rf_status is the at-a-glance health signal: all ok means the cluster is meeting the replication factor you asked for; degraded means it's working but exposed; broken means a shard is down.

Find the coordinator:

SHOW SHARDING MASTER;

Drop it cleanly. Dropping a sharded table works exactly like dropping a regular table — DROP TABLE removes the table and all its shards across the cluster:

DROP TABLE products;

Scale by changing the cluster. Because rebalancing is automatic, the way you scale a sharded table out is by adding nodes to the cluster (Adding a new node). The master notices the new node and rebalances onto it without any action on the table itself.

Choosing the shard count and replication factor

A few rules of thumb:

Shards for faster writes: a handful of shards is usually enough, well below your core count — in the benchmarks below a 16-core / 32-thread box peaked at 4–8 shards and by 32 shards was slower than no sharding at all. Start small (4–8), measure, and only add more if your own numbers say so. More shards than that rarely helps and adds per-shard overhead.
Shards for distribution: with multiple nodes, you want enough shards that they divide evenly across nodes and leave room to grow — a multiple of your node count is a good default. Don't go wild: each shard is a real table with its own overhead. (Manticore caps the shard count at 3000.)
RF for durability: rf='2' is the standard production choice — it survives any single node failure at 2× storage. Use rf='3' only when you genuinely need to survive simultaneous failures or have strict availability requirements, and remember it costs 3× the storage and more replication traffic.
RF=1 is for performance or throwaway data only. It has no fault tolerance. Use it on a single node for parallelism, or in a cluster only when you have an external way to rebuild lost data.

Benchmarks: does sharding actually speed up inserts?

A feature is only worth using if it earns its keep, so we measured. The question we wanted answered honestly: for the same workload, does sharding make ingestion faster — and if so, when? The methodology was simple: compare every sharded run against the same baseline — a regular table without sharding.

In short: on a 16-core box with 32 concurrent writers, sharding raised insert throughput by about 1.5× at its best — from ~163k to ~253k docs/s — but only when the shard count stayed small. The best results came at 4–8 shards; by 32 shards, throughput had fallen below the unsharded baseline. The binary log cost roughly 25% of write performance, and rf=2 replication across two real machines cost about 30% more — fair prices for durability, but not free.

Setup. A dedicated server with no other significant CPU load — AMD Ryzen 9 5950X (16 cores / 32 threads), 128 GB RAM. Everything ran inside a single Docker container running a recent dev build with the sharding feature. Manticore ran with stock settings — no performance tuning: only listener ports, the data directory, and the binary log path were set; the thread pool, RT memory limits, and binary log behaviour were left at their defaults. Load came from manticore-load. Each run inserts the same documents — (id bigint, name text, type int) where name is 10–100 random words — in batches of 1000 into a real-time table. Only the shard count, the replication factor, and the binary log change between runs; the "no sharding" baseline is a plain RT table. We run the full single-node shard sweep twice — once with the binary log on (the default), once with it off — inserting 20,000,000 docs per run with 32 concurrent writers.

# the exact shape of every insert run (shards/rf vary)
manticore-load --batch-size=1000 --threads=32 --total=20000000 \
  --init="create table test(id bigint, name text, type int) shards='8' rf='1'" \
  --load="insert into test(id,name,type) values(<increment>,'<text/10/100>',<int/1/100>)"

Single node: throughput vs shard count

Docs inserted per second, 20M docs, 32 writers — both binary log modes:

Shards	binary log on (default)	binary log off
none (baseline)	162,920	218,079
2	191,976	246,288
4	252,807	290,665
8	251,008	265,015
16	175,848	182,288
32	108,006	111,381

The chart plots the full sweep twice — binary log on (blue, the default) and off (orange). Three things stand out:

Concurrent inserts get a real boost. With 32 writers, splitting the table lifts throughput by ~1.5× at the peak — from 163k to 253k docs/s on the default (binary-log-on) line. Each shard is an independent real-time table, so spreading writes across several sharply cuts the lock contention a single RT table hits under concurrency, and lets the inserts use more cores.
The best range is small — 4–8 shards. The gain peaks there and then falls off fast. By 16 shards it's barely above baseline, and at 32 shards throughput is below the unsharded table (0.66×) — past that range, per-shard and coordination overhead outweighs the extra parallelism. More shards is emphatically not better. Both lines have the same shape and the same best range — the binary log doesn't move it.
Durability costs most where you're fastest. Turning the binary log off (orange) lifts the whole curve, but the gap is widest in the high-throughput region — 253k → 291k at 4 shards — and nearly vanishes once the shard count is too high (108k vs 111k at 32 shards), where coordination overhead, not durability, is the bottleneck. We measure the binary-log impact separately below.

One caveat worth stating plainly: this speedup comes from concurrent writes. A single, strictly-sequential writer can't exploit parallel shards and will see no speedup (and a touch of distributed-layer overhead). Sharding pays off when many clients or consumers write at once — which is what real ingestion pipelines do.

The cost of durability: the binary log

Manticore's binary log makes inserts crash-safe (it can replay un-flushed transactions after an unclean shutdown). It's on by default. You can already see its cost in the chart above — the orange (binary-log-off) line runs above the blue one. Isolating it on the plain unsharded baseline, with only binlog_path changing:

Disabling the binary log raised baseline throughput from 162k to 218k docs/s — so crash-safe inserts cost roughly 25%. That's the price of not losing un-flushed writes on a hard crash; leave it on in production unless you can rebuild the data from source and want the extra speed during bulk loads.

The cost of replication on writes

Durability across machines isn't free either — and this is the one test that's only honest on real, separate hardware. So unlike the single-node benchmarks above, we ran the two replication tests on two distinct physical machines: two 4-core / 7 GB cloud VMs joined as a Manticore cluster. That way rf=1 and rf=2 never fight over the same cores or memory — the fair comparison a single box simply can't give.

rf=1 keeps a single copy on one machine; rf=2 keeps a full copy on both, so every insert is synchronously replicated across the network before it's acknowledged. Same 1M-doc load, 4 writer threads:

Replication cost about 30% of insert throughput (112k → 78k docs/s) — the price of copying every write to the second machine before acking. That's the rf trade-off in one number: write a bit slower, survive losing an entire machine.

Do sharding and replication speed up reads?

Reads are easy to measure wrong, so first the method. A trivial query — fetch 20 rows, no ranking — runs in well under a millisecond, so its cost is all fixed overhead; a distributed table that hops to an agent then looks ~3× slower (≈7,700 vs 2,400 q/s here) purely because the network round-trip dwarfs the near-zero work. That's not a real query. A realistic full-text query (a few terms to match and rank, ~10–30 ms) tells the truth: the distribution overhead shrinks to a few percent, because now real work dominates the fixed cost. The numbers below all use realistic queries on the 2-node cluster, read from a single entry node.

# realistic read — what the numbers below use: full-text match-and-rank, ~10–30 ms each
manticore-load --threads=4 --total=5000 \
  --load="select id from <table> where match('<text/1/5> <text/1/5>')"

# trivial read — sub-ms, all fixed overhead, exaggerates distributed cost ~3x
manticore-load --threads=4 --total=20000 \
  --load="select id from <table> limit 20 option ranker=none"

<table> is one of: a plain RT table (no sharding), a type='distributed' table over local shards (single-node sharding — local='s0' local='s1' …), or a sharded table with shards='4' rf='1'/rf='2'. Every read is issued to one node — we never query both nodes as separate clients.

Sharding across nodes speeds reads up. A 4-shard rf=1 table spread over both machines does ~516 q/s vs ~315 for a single unsharded node — about 1.6× — because each query runs across both nodes' cores at once.
Replication keeps reads fast. rf=2 (every shard on both nodes) does ~410 q/s — a touch below rf=1. The reason is not that the load sticks to one node (it spreads across replicas); it's that with rf=2 every shard is reached through the agent/mirror path — even the copies that happen to be local — and that path costs the few percent noted above, whereas rf=1 reads its on-node shards in-process. Either way reads stay well above a single node, and the data now survives a machine loss.
On one box, sharding's read win is small. Splitting a table into 2–4 shards on a single node adds only ~5–12% (query parallelism), and only when there are spare cores — heavier queries help (≈12% vs ≈3% for light ones), but a fully-loaded box is a wash. The real read scaling comes from adding machines, not shards on one box.

Method note: the read and replication tests run on a separate pair of cloud VMs — 4 vCPU / 7 GB RAM each, two distinct physical machines — joined as a 2-node Manticore cluster, same recent dev build, stock settings, 1.5M docs. They are a different, much less powerful setup than the 16-core / 32-thread server used for the insert sweeps above, so draw conclusions within each test, not across them. The small core count is also why single-node sharding's read gain is modest here — there are few spare cores for a query to parallelize across.

Bottom line

On one box, sharding gives a ~1.5× concurrent insert speedup (163k → 253k docs/s here at 20M).
The best range here is 4–8 shards on this 16-core / 32-thread CPU. Too many shards hurts: at 32 shards throughput fell below the unsharded baseline. Match shard count to cores and write concurrency, not to a big round number.
The binary log costs ~25% of write throughput (and the gap shrinks to near-zero once the shard count is too high), and rf=2 replication ~30% on writes (measured on two separate machines) — both fair prices for crash safety and node-failure survival, respectively.
With realistic full-text queries, sharding across a 2-node cluster reads ~1.6× a single node, and rf=2 keeps reads fast while surviving a node loss. Trivial id-lookup queries exaggerate distributed overhead ~3× — always benchmark reads with realistic queries.
Absolute numbers depend on hardware and document shape; what travels between setups is the shape of these curves — so benchmark your own workload before committing to a shard count.

Limitations and things to know

There are sharp edges worth knowing up front:

rf is required. A sharded CREATE TABLE must specify rf=. If you omit it, CREATE TABLE fails.
rf greater than 1 requires a cluster. You can't create a multi-copy sharded table on a standalone node — there's nowhere to put the copies. Multi-copy tables must use the cluster:name form.
Local sharded tables can't be created on a node that's already in a cluster. If a node belongs to a replication cluster, create the table in that cluster (CREATE TABLE cluster:name …) rather than as a local table, or the sharding metadata won't be tracked correctly. Manticore detects this and tells you.
Maximum 3000 shards per table.
RF=1 means no fault tolerance. A lost node's shards are gone. This is inherent, not a bug — it's the trade-off you accept for rf='1'.
You need at least RF nodes. rf='M' requires a cluster of at least M nodes; creation fails otherwise.
Creation is synchronous up to a timeout. CREATE TABLE waits for the distribution to complete (default 30s). For very large shard counts, raise it with timeout='N' (seconds), e.g. shards='3000' rf='3' timeout='60'.

Where this leaves you

Sharding in Manticore covers a wide span with a deliberately small interface. With shards='N' rf='1' on a single box, sharding spreads concurrent writes across independent pieces and keeps each one small. With shards='N' rf='M' inside a cluster, it gives you a distributed, replicated table that survives node failures and rebalances itself when the cluster changes — without you writing a line of failover logic. The same table definition grows from one node to many, and your application keeps talking to it the same way throughout. In practice, this means you can start by improving write throughput on one node and later move to a fault-tolerant cluster without changing the application.

To go deeper into the building blocks sharding stands on:

Have a sharding question or a workload you'd like us to benchmark? Let us know.

Faster KNN index builds in Manticore

Sergey Nikolaev — Thu, 02 Jul 2026 08:48:19 +0000

TL;DR

Building a KNN index used to be the slow part of saving and merging tables with vector attributes. As of release v27.1.5, Manticore can use several CPU cores for this work during chunk saves, OPTIMIZE merges, auto-optimize, and ALTER TABLE ... REBUILD KNN. On a 16-core Ryzen 9 5950X, building a KNN index for 1 million 1536-dimensional vectors dropped from 8 minutes to 39 seconds.

Why HNSW build speed matters

Manticore uses HNSW graphs to power KNN search over float_vector attributes. You can think of an HNSW graph as a map that helps Manticore quickly find vectors that are close to the query vector.

Building that map can take a long time. For tables without KNN, saving or merging data is mostly about writing ordinary table data. For tables with KNN, Manticore also has to insert every vector into an HNSW graph, and that extra work can dominate the total time.

This matters most after large inserts and during maintenance. Fresh data is saved from memory to disk chunks. Existing chunks are later merged by OPTIMIZE or auto-optimize. Each saved or merged chunk needs its own HNSW graph, so faster graph building means shorter waits after bulk loading, faster background optimization, and less time spent on maintenance operations.

Disk chunk count matters for search too. Manticore stores RT tables as disk chunks, and each chunk has its own HNSW graph. A KNN query searches every chunk and merges the results, so fewer chunks usually mean faster KNN queries. The fastest layout is often one chunk with one graph.

Auto-optimize does not go all the way to one chunk by default. It merges chunks in the background, but stops when the table reaches a target chunk count. For ordinary tables, the target is 2 * num_logical_cpus; for tables with a KNN attribute, it is lower: num_physical_cpus / 2. On a 32-thread / 16-core host, that means 8 chunks for a KNN table instead of 64 for an ordinary table. The KNN target is lower because extra chunks hurt KNN search latency more, but the default still leaves more than one graph. To make auto-optimize converge to a single chunk, set optimize_cutoff to 1 server-wide, per table, or at runtime with SET GLOBAL optimize_cutoff = 1. You can also do it manually with OPTIMIZE TABLE ... OPTION cutoff = 1.

What used to happen

Freshly inserted documents first accumulate in a RAM chunk. When that RAM chunk reaches rt_mem_limit, which defaults to 128MB, Manticore saves it as a new disk chunk. For a table with a KNN attribute, that save includes building a fresh HNSW graph from the vectors in the RAM chunk.

The same kind of HNSW build happens when disk chunks are merged. OPTIMIZE TABLE and auto-optimize read live rows from existing chunks, write a new merged chunk, and build a new HNSW graph for that merged result. ALTER TABLE ... REBUILD KNN, and ALTER operations that add or drop a float_vector column, also rebuild the graph.

Before this change, the HNSW part of each individual save, merge, or rebuild used one worker:

A RAM-to-disk chunk save walked all live rows from the RAM chunk's segments one by one and inserted their vectors into one HNSW graph.
A chunk merge walked all live rows from the input disk chunks one by one and inserted their vectors into the new graph.
ALTER TABLE ... REBUILD KNN rebuilt each graph in one worker.

Manticore already had some parallelism around these operations. Up to 2 RAM-chunk saves can run at the same time. The optimizer can also run several chunk merges at once, controlled by parallel_chunk_merges. The default is 2 when the host has enough CPU cores. But inside each individual save or merge, the KNN graph build was still single-worker. On KNN-heavy tables, that single worker often determined how long the whole operation took.

What changed

Manticore now splits one KNN graph build across several workers. Each worker gets part of the rows, inserts its vectors into the same destination graph, and finishes independently. The graph-building library coordinates those concurrent inserts so the graph remains valid.

The exact split depends on the operation:

During RAM-to-disk saves, workers take RAM segments from a shared queue until all segments are processed.
During chunk merges and ALTER TABLE ... REBUILD KNN, Manticore divides the live rows into similarly sized ranges so the work is spread evenly.

Single-thread improvements

The same release also improves the single-worker path. Even when knn_parallel_build is set to 1, the benchmark below shows a 10% improvement before adding parallelism. That comes from three changes:

Two-pass neighbor processing. When inserting a vector, the algorithm walks through candidate neighbors and computes distances to them. The new code splits that into two passes: the first pass walks the neighbor list and prefetches the vector data, and the second pass computes the distances. This gives the CPU time to bring the vectors into cache before they are used.
Two comparisons at a time. Some distance calculations now process two candidate vectors together. This reduces repeated work in the inner loop where most of the build time is spent.
Compile-time distance dispatch in build mode. The builder now picks the right distance function once for the build, such as inner product vs. L2 and raw float vs. binary-quantized vectors. That avoids a function-pointer lookup on every distance call and lets the compiler optimize the inner loop more aggressively.

The default and the config

A new searchd setting, knn_parallel_build, controls how many workers one KNN build may use. The default is min(4, threads / 4), where threads is Manticore's threads setting - the size of the worker pool that runs queries and background tasks, which defaults to the number of logical CPU cores on the host.

In practical terms, that means one worker on small hosts and up to four workers by default on larger hosts: a 4-thread host gets one worker, an 8-thread host gets two, a 16-thread host gets four, and anything above that is also capped at four. The default is conservative because production machines often need to handle searches, inserts, and background work at the same time.

You usually do not need to change it. Consider raising it when you are rebuilding or optimizing a KNN-heavy table on a host that is not serving live traffic:

SET GLOBAL knn_parallel_build = 16;

Set it to 1 if you need the old single-worker behavior:

SET GLOBAL knn_parallel_build = 1;

The value can also be set in the searchd config and checked with SHOW VARIABLES.

CPU usage

Multiple saves and merges can be active at the same time, and each one can use up to knn_parallel_build workers. These workers use Manticore's existing threads pool. They do not create an unlimited number of extra operating-system threads; if all pool threads are busy, extra work waits in the queue.

This is why the default leaves headroom. On a 32-thread host, the default is 4 workers per KNN build. If two chunk saves overlap, the KNN build work can use up to 8 workers, leaving the rest of the thread pool available for other work.

Benchmark

Setup:

AMD Ryzen 9 5950X (16 physical / 32 logical cores)
Dataset: dbpedia-openai-1M - 1M vectors, 1536 dimensions, cosine distance
Quantization: 1-bit (binary) quantization
Data inserted into an RT table, then OPTIMIZE to a single disk chunk
Measurement: ALTER TABLE knn_data REBUILD KNN, three runs per setting, single-chunk so timings are stable
HNSW settings: defaults

ALTER TABLE ... REBUILD KNN was used because it exercises the same parallel build path as chunk saves and chunk merges, while giving stable timings that are easy to reproduce.

Results:

With one worker, the new code is already 10% faster than the old code: 492 seconds dropped to 442 seconds.
With 16 workers, rebuild time dropped to 39 seconds, about 11x faster than the new one-worker result.
Going from 16 to 32 workers helped only a little: 39 seconds became 36 seconds. On this machine, the useful limit is close to the 16 physical CPU cores.
The default is meant for shared production hosts. For maintenance work on a dedicated host, raising knn_parallel_build can be worth it.

Migration

No action is required. Existing tables keep working, and KNN graphs built by the parallel path are functionally equivalent to graphs built by the old single-worker path.

One detail can matter for strict reproducibility: parallel workers may insert vectors in a different order, so Manticore's on-disk KNN graph file, stored with the .spknn extension, is not guaranteed to be byte-for-byte identical to a single-worker build. Search quality and query speed are expected to be the same. If byte-for-byte reproducibility matters, set knn_parallel_build = 1.

Conclusion

This change speeds up one of the slowest maintenance steps for KNN tables. Parallel graph building reduces the time needed to save chunks, merge chunks, and rebuild KNN data, while the improved single-worker path also speeds up builds on smaller systems. Existing tables continue to work without changes. When CPU resources are available during maintenance, knn_parallel_build can be raised to build KNN graphs faster.

DEV Community: Sergey Nikolaev

UUID in Manticore: a single ID for the primary database and Manticore

Why a second ID is a problem

What a UUID is

What changed in Manticore 28.5.0

Who creates the UUID

Where it works

Summary

Manticore Search 28.6.6: UUID document IDs, ordered GROUP_CONCAT(), and 16 fixes

Upgrade notes

UUID document IDs for real-time tables

Ordered and limited GROUP_CONCAT()

Safer table, backup, and cluster maintenance

Query processing and client compatibility

Get Manticore Search 28.6.6

Need help or want to connect?

Faceted search under active filters

What e-commerce facets need

What changed

Minimal example

strict: the previous behavior

auto: a facet ignores its own filter

max: a broad bucket list with statuses

Manually setting the filter scope

ZEROES: zero-count buckets in max

The same query through the JSON API

How this differs from Meilisearch, Elasticsearch, and OpenSearch

Performance and limitations

Further reading

Install Manticore Search with one command

After it runs

Check the service

Why add another install path?

What the script does

Where it applies

Default behavior

Common commands

CI and non-interactive use

Cleanup options

If your policy forbids pipe-to-shell

Manticore Search authentication rollout checklist for production

Phase 1: inventory before changing anything

Phase 2: set up least-privilege users

Phase 3: test in staging

Phase 4: production rollout checklist

Standalone node

Distributed tables and remote agents

Existing replication cluster

Authentication logging during cutover

Phase 5: rollback and troubleshooting

Final check

How to secure Manticore Search with built-in authentication and authorization

What Manticore Adds

Enable Authentication

Bootstrap the First Administrator

Create Users

Connect with SQL and HTTP

Testing After Enabling Authentication

How Manticore Checks What Is Allowed and Denied

Roll Out Access on an Existing Deployment

Full Reference

Meilisearch vs Manticore: Setting the Record Straight

"Full-text search and real-time analytics" — that's maybe 1% of it

"Complex setup" and "advanced customization"? Let's count commands

"SQL familiarity" — optional, not required

Vector search: Meilisearch's own table says it best

Relevance: measured, not argued

"Primarily used for complex, large-scale workloads" — the data says otherwise

Real-time analytics: we'll be honest here too

Where Meilisearch's article has a point

Client libraries: the table, completed

The bottom line

Built-in authentication and authorization for Manticore Search

What Manticore adds

What changes for operators

Why this matters for SaaS and shared search

Rollout notes

Learn more

Turbopuffer vs. Manticore Search on a couple of cheap VPS

The workload