KynetraDB use cases

Patterns the build supports today.

Five ways to use what is reachable in the current build, each with the capabilities it relies on and the limits that come with it. These are patterns, not customer stories: none is a description of someone’s deployment.

Pattern 1

AI retrieval with hybrid search

For an assistant or retrieval pipeline that needs keyword and semantic results from the same records, filtered by who is asking.

How it fits together

  1. Write each passage or record as an entity with its text attributes and the embedding you computed. Use one kind per corpus.
  2. Query with POST /v1/hybrid: a text query, a query vector, weights and a metadata filter. The two ranked lists are fused with reciprocal-rank fusion, so the score scales are never compared.
  3. Call these routes from your own service with a project service key, which scopes every call to that project’s data. Service credentials bypass row-level policies, so filter for the end user yourself, for example on an owner or tenant attribute, and keep the key off clients.
  4. An MCP endpoint is also mounted for tools that speak it.

POST /v1/hybrid (vector shortened for display)

{
  "q": "refund policy for annual plans",
  "vector": [0.12, -0.03, 0.88],
  "top_k": 10,
  "kind": "doc_passage",
  "bm25_weight": 1.0,
  "vector_weight": 1.0
}

Built from

Where it stops

  • You supply the embeddings and the chunking. Server-side embedding is not part of the write path.
  • The vector leg is an exact scan, so latency grows with the number of embedded entities. Approximate indexes are roadmap here.
  • The raw /v1 search routes refuse publishable keys and end-user tokens. A browser cannot call them directly.
  • The keyword index covers every string value of an entity. There are no per-field weights, phrase queries or highlighting.
  • Results are ranked lists, not answers. Grounding, citation and evaluation are your application’s job.

Pattern 2

A multi-tenant SaaS backend

For a product that serves many customer organisations and wants tenant separation, per-tenant keys and an offboarding path built in.

How it fits together

  1. Create an organisation for each customer account and a project for each tenant environment. A project is the tenant.
  2. Ship the project’s publishable key to browsers and apps. Keep its service key on your servers.
  3. End-users sign up and sign in inside the project. Their tokens are signed with that project’s own secret and carry the project id.
  4. Express access in collection rules and row-level policies, for example auth.uid() == owner_id. End-user traffic goes through /rest/v1, KynQL, typed views and the WebSocket, which apply them.
  5. Offboard with a tenant export (credential material left out) and a purge.

Built from

  • Per-project prefix, platform and project credential planes, lifecycle, export and purge.

  • Collection rulesAvailable in preview

    Per-operation role lists and field visibility.

  • Per-row policies on the routes that serve end-users.

  • Per-project sign-inAvailable in preview

    Each project has its own user pool, signing secret and tokens.

  • Project API keysAvailable in preview

    A publishable key and a service key per project; rotation has no overlap.

Where it stops

  • Project data is namespaced by a kind prefix, and project-scoped credentials are confined to their project. Platform accounts and the global key are operator credentials with deployment-wide authority; keep them and operator endpoints away from tenants.
  • Tenants share one process, one log and one failure domain. A per-project request budget bounds a noisy tenant; it does not give it its own machine or its own encryption key.
  • No setting closes project sign-up. The first account in a project pool becomes its administrator, so create it yourself before the publishable key is public.
  • End-user accounts have no second factor. TOTP covers platform accounts.
  • Rotating a project’s keys replaces the publishable key, the service key and the token secret together, with no overlap.
  • A purge is tombstone plus compaction, not cryptographic erasure. See the Multi-tenancy page for what survives.

Pattern 3

A realtime application

For a collaborative or live-updating app where clients should see changes to the records they are allowed to read.

How it fits together

  1. Model the data as collections and attach row-level policies.
  2. Clients open a WebSocket at /realtime/v1, join a channel, and subscribe to change events on a collection. They can also use presence and broadcast on the same channel.
  3. Every change event is checked against the subscriber’s own row-level policy before it is delivered, so two subscribers on one channel can receive different rows.
  4. After a disconnect, the client re-reads the records it cares about, because delivery has no replay. An operator integration can catch up from a sequence number with the log-backed change feed.

Join message on /realtime/v1

{
  "type": "join",
  "channel": "room:1",
  "config": {
    "postgres_changes": [
      { "event": "*", "table": "messages", "filter": "room_id=eq.1" }
    ]
  }
}

Built from

Where it stops

  • Delivery is live and in process, with no replay. A client that disconnects or lags misses events, so re-read after reconnecting. Project credentials are refused on a read replica; connect to the primary.
  • Change events cover collection records. Other entity kinds, files and agents are not delivered through that feed, and the filter supports column=eq.value comparisons alone.
  • Browsers cannot set headers on a WebSocket, so the token travels as a query parameter. Use short-lived tokens and keep query strings out of proxy logs.
  • The change feed and the server-sent-events stream are operator interfaces, not client APIs. Clients subscribe through the realtime WebSocket.

Pattern 4

Mirror writes to a database you already run

For a team that keeps another system of record or analytics store and wants KynetraDB writes copied out to it.

How it fits together

  1. Turn on outbound sinks with KYNETRA_ENABLE_SINKS and give each target its own settings. Targets without settings are skipped.
  2. After each successful write, the upsert or delete is sent to every configured sink in a detached task. The primary write never waits for a sink.
  3. For a consumer you build yourself, use outbound webhooks or poll the operator change feed. Webhooks raise one event, record.created, with a single delivery attempt.
  4. To bring data in, use the migrators instead; mirroring runs outward.

Built from

Where it stops

  • Sink failures are logged and dropped. There is no retry and no backfill, so a mirror can lag or miss records.
  • A sink receives the entity as KynetraDB stores it. Mapping it onto your schema is yours.
  • Mirroring is one-way and not transactional with the primary write.

Pattern 5

Records, search and sign-in in one process

For a single service or a small team that wants an application database with search and authentication on one volume, run as one server.

How it fits together

  1. Run the server with the File backend on a persistent volume. Everything the engine needs is in that data directory.
  2. Store records as entities or typed collections. Add keyword and vector search over the same records without a second system.
  3. Use the built-in sign-in for your users and the admin console for operations.
  4. Back up with the backup command, and add a streaming read replica if you need a warm copy.

Built from

Where it stops

  • There is one writer. Write capacity is that of one node, and memory grows with the data because the default entity profile is in memory.
  • Failover is manual and the server does not encrypt data at rest. Plan volume encryption and backups from the start.
  • TLS is terminated in front of the server.

Check a pattern against your workload

Tell us which pattern is closest to yours, the size of your data and your recovery needs. We will say what the current build covers. See also the architecture, thesecurity overview and the FAQ.