YMJake.ManticoreSearch.Client 1.2.1

ManticoreSearch .NET Client

Handcrafted C# SDK mirroring the official PHP client. Every endpoint, table helper, query builder, result wrapper, and admin API is handwritten.

Features

• Table CRUD, bulk, DDL, PQ search/management, cluster/nodes utilities.
• Fluent typed DSL (SearchRequestDescriptor<T>) + low-level SQL/CLI escape hatch.
• Result wrappers (ResultSet) with hits + metadata (took, timed_out, facets, profile).
• Pluggable node pools and transport hooks (ILogger, IHttpTransportFactory).
• Serializer customization with System.Text.Json context support.
• Schema mapping via TableSchemaBuilder + [ManticoreField].
• KNN naming aligned to Manticore (query_vector, doc_id, query).

Quick Start

var pool = new SingleManticoreNodePool(new Uri("http://127.0.0.1:9308"));
var client = new ManticoreClient(new ManticoreClientSettings(pool));
var table = client.Table("movies");

var schema = TableSchemaBuilder.FromType<Movie>(descriptor => descriptor
    .Column(m => m.Title, "text", opts => opts.Indexed().Stored())
    .Column("created_at", "timestamp"));

await table.CreateAsync(schema, silent: true);
await table.AddDocumentAsync(new { title = "Interstellar", rating = 8.5 }, id: 1);

var typed = await table.SearchAsync<Movie>(s => s
    .Match(m => m.Title, "Interstellar")
    .Range(x => x.Rating, gte: 8)
    .Limit(5));

Advanced Query Examples

await table.SearchAsync<Movie>(s => s
    .Match(m => m.Genre, "thriller")
    .Join(new JoinClause(
        type: "inner",
        table: "directors",
        leftField: "director_id",
        rightField: "id",
        leftFieldType: "int",
        query: new QueryStringQueryClause("country:US")))
    .ScriptFields(sf => sf.Add("score", "doc['rating'] * params.boost"))
    .Knn(k => k
        .Field("embedding")
        .K(5)
        .DocumentId(42)));

Multilingual SQL Sample

Inspired by liweinan/manticoresearch-example, the sample uses SQL + MATCH() + tokenization flow.

var table = client.Table("documents_idx_sample");
await table.DropAsync(silent: true);

var schema = TableSchemaBuilder.FromType<SampleDocument>(d => d
    .Column(x => x.Title, "text", opts => opts.Indexed().Stored())
    .Column(x => x.Content, "text", opts => opts.Indexed().Stored())
    .Column(x => x.Tags, "text", opts => opts.Indexed().Stored()));

await client.Tables().CreateAsync(
    "documents_idx_sample",
    schema,
    new Dictionary<string, object>
    {
        ["min_word_len"] = "1",
        ["min_infix_len"] = "1",
        ["expand_keywords"] = "1",
        ["morphology"] = "none",
        ["index_exact_words"] = "1",
        ["ngram_len"] = "2",
        ["ngram_chars"] = "cjk"
    },
    silent: true);

var matchExpression = "\"测试\" \"test\"";
var sql = $"SELECT id, title, content, WEIGHT() AS weight FROM `documents_idx_sample` WHERE MATCH('{matchExpression}') ORDER BY weight DESC LIMIT 10";
var response = await client.SqlAsync(sql, rawResponse: false);

Run standalone sample:

dotnet run --project ManticoreSearch.Sample

Transport & Authentication

var uris = new[]
{
    new Uri("https://node1.example.com:9308"),
    new Uri("https://node2.example.com:9308"),
    new Uri("https://node3.example.com:9308")
};

var pool = new StaticManticoreNodePool(uris);

var settings = new ManticoreClientSettings(
        pool,
        sourceSerializerFactory: _ => new DefaultManticoreSourceSerializer(MySourceContext.Default))
    .Authentication(new BasicAuthentication("elastic", "changeme"))
    .Proxy("http://proxy.internal:8080");

var client = new ManticoreClient(settings);

MySourceContext is your generated JsonSerializerContext.

Note: Manticore server itself does not enforce built-in HTTP Basic auth by default. Use .Authentication(...) when your deployment has an auth gateway/reverse proxy (Nginx/API gateway) that validates Authorization headers before forwarding to Manticore.

Error Handling

The low-level transport maps failures into explicit exception types:

• ManticoreConnectionException: network/connectivity failures.
• ManticoreTimeoutException: request timeout.
• ManticoreServerException: non-success HTTP status (includes StatusCode and ResponseBody).
• ManticoreSerializationException: response deserialization failure.

ManticoreClient/LowLevel stays low-level; TableClient/Search are thin wrappers over the same transport.

Release Notes

[1.2.0] - 2026-02-26

Changed:

• Refactored SQL internals into focused components: SqlText, SqlBuilder, and DocumentPayload.
• Unified SQL statement composition style across TableClient, ClusterClient, TablesAdminClient, and NodesClient.
• Aligned KNN payload naming with current Manticore conventions: query_vector, doc_id, and query.
• Updated README examples to match current multilingual SQL sample behavior.

Added:

• xUnit-based regression tests for KNN serialization, search response shaping, SQL builder formatting, and document payload normalization.
• InternalsVisibleTo setup for internal-component unit testing.

Notes:

• BasicAuthentication in client settings is intended for proxy/gateway authentication in front of Manticore.

[1.1.0] - 2026-02-26

Added:

• Initial public package release for .NET 8 / .NET 10 targets.