Sylin.Koan.Data.Connector.OpenSearch

Sylin.Koan.Data.Connector.OpenSearch

OpenSearch vector storage and similarity search for Koan Entities. Reference the package, keep the application's normal AddKoan() bootstrap, and use Vector<TEntity>; the connector owns discovery, index provisioning, native kNN requests, filtering, naming, source isolation, and readiness participation.

• Target framework: net10.0
• License: Apache-2.0

Install

The generated product surface owns support maturity; this page owns OpenSearch setup and limits.

dotnet add package Sylin.Koan.Data.Connector.OpenSearch

Meaningful result

With OpenSearch reachable, no provider registration or repository scaffold is required:

builder.Services.AddKoan();

public sealed class Article : Entity<Article>
{
    public string Title { get; set; } = "";
}

float[] embedding = [0.12f, 0.42f, 0.88f];
await Vector<Article>.Save("article-1", embedding, new { category = "docs" });

var nearest = await Vector<Article>.Search(
    embedding,
    topK: 5,
    filter: Filter.Eq("category", "docs"));

When OpenSearch is the intended vector provider, it participates in the shared automatic election policy. If more than one durable provider is referenced, pin business-critical placement with [VectorAdapter("opensearch")] or Koan:Data:VectorDefaults:DefaultProvider.

Configuration

auto is the default and uses Koan's health-checked discovery pipeline, then the local endpoint fallback. Use exact provider configuration for secured or explicitly placed clusters:

{
  "ConnectionStrings": {
    "OpenSearch": "https://search.example.net:9200"
  },
  "Koan": {
    "Data": {
      "OpenSearch": {
        "Username": "koan-app",
        "Password": "use-your-secret-provider",
        "IndexPrefix": "catalog",
        "Dimension": 1536
      }
    }
  }
}

Koan:Data:OpenSearch:Endpoint is the exact endpoint alternative to the connection-string entry. API-key authentication is also available through ApiKey. Credentials belong in the platform's secret store.

Capabilities

• automatic OpenSearch knn_vector mapping and index provisioning;
• single and bulk vector upsert/delete, clear, count, scroll export, and index statistics;
• native OpenSearch kNN search with caller-owned topK;
• metadata filtering pushed into the native kNN query, with unsupported operators rejected rather than ignored;
• source, partition, container, and tenant-aware index naming;
• selection-aware readiness and redacted startup reporting.

Boundaries

• This connector stores vector representations and metadata; it is not a general OpenSearch Entity data adapter.
• Embedding retrieval and hybrid text/vector search are not supported.
• All named sources share the configured cluster endpoint and isolate through generated index names. Per-source cluster endpoints are not supported.
• Setting IndexName explicitly pins all contexts to one index and may defeat active isolation. Koan reports this conflict but honors the explicit name.
• Automatic discovery probes without credentials. Configure secured clusters explicitly.
• OpenSearch index mappings fix the vector dimension at creation. Changing models normally requires a new index or a controlled reindex.

References

• Technical reference
• Vector runtime