Skip to main content

Database Hosted Service

KnowledgeFlowDB’s hosted service is a managed graph database plus docs-driven query surface. The main user workflow is now:

  1. sign in with Privy
  2. mint a wallet-backed bearer token
  3. mint a sign-to-derive session
  4. query through the hosted docs UI or your own client

What the Hosted Docs Experience Does for You​

The docs app is no longer a generic “bring your own URL and API key” shell.

By default it now:

  • uses Privy login
  • signs the KFDB auth challenge with the embedded wallet
  • derives the user key session
  • sends the correct auth headers automatically for interactive queries

That makes the interactive KQL and SQL examples representative of the real product flow.

Authentication Model​

Primary end-user path​

  • Privy login
  • Bearer token from wallet signature
  • Sign-to-derive session for private data

Advanced programmatic path​

  • bearer token supplied directly
  • API key for service integrations

Legacy/internal compatibility path​

  • X-Wallet-Address only where older tooling still expects it

The compatibility path is not the recommended hosted-service onboarding flow.

Query Paths​

Query typeEndpointBackend
KQLPOST /api/v1/queryClickHouse analytics replica
SQLPOST /api/v1/query/sqlScyllaDB source of truth
EXPLAINPOST /api/v1/query/explainPlan only

KQL and SQL should reflect the same underlying data. If they diverge materially, CDC is unhealthy.

Discovery-First Workflow​

For a new tenant, start with:

HELP
SHOW LABELS
SHOW PROPERTIES
SHOW EDGE_TYPES
SHOW SCHEMA

That live HELP surface is the source of truth for the KQL docs refresh and the KQL HELP Audit.

Interactive Docs​

Pages with live query editors now assume the hosted auth flow:

The advanced connection drawer remains available for debugging custom deployments, but it is no longer the default narrative.

Programmatic Access​

Programmatic clients should use:

Architecture​

The hosted service is built on:

  • ScyllaDB for source-of-truth writes and SQL access
  • ClickHouse for analytics and KQL execution
  • CDC to keep both paths aligned
  • Privy for hosted wallet login
  • sign-to-derive for user-controlled private-data access