Query Languages

KnowledgeFlowDB exposes both KQL and SQL. Both can surface live HELP content, and both are covered by the refreshed docs flow.

Authentication for Querying

The recommended hosted flow is:

Authorization: Bearer <token>
x-derive-session-id: <session_id>
x-derive-key: <derive_key_hex>
Content-Type: application/json

The interactive docs attach those headers automatically after Privy login.

KQL

KQL is the graph-native language and runs on:

POST /api/v1/query

Use it for:

• graph pattern matching
• discovery commands
• HELP topics
• temporal queries
• AI expressions
• window functions

Example:

curl -X POST https://api.knowledgedataflow.org/api/v1/query \
  -H "Authorization: Bearer <token>" \
  -H "x-derive-session-id: <session_id>" \
  -H "x-derive-key: <derive_key_hex>" \
  -H "Content-Type: application/json" \
  -d '{"query":"MATCH (f:File)-[:DEFINES]->(fn:Function) RETURN f.path, fn.name LIMIT 10"}'

Useful first commands:

HELP
HELP syntax
HELP clauses
HELP functions
SHOW LABELS
SHOW SCHEMA

See:

• KQL Syntax
• KQL HELP Audit

SQL

SQL runs on:

POST /api/v1/query/sql

It targets the source-of-truth path and is better for:

• relational-style reads
• direct table-oriented inspection
• source-of-truth count checks

Example:

curl -X POST https://api.knowledgedataflow.org/api/v1/query/sql \
  -H "Authorization: Bearer <token>" \
  -H "x-derive-session-id: <session_id>" \
  -H "x-derive-key: <derive_key_hex>" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT COUNT(*) FROM nodes_by_label WHERE label = '\''File'\''"}'

SQL also supports:

HELP
SHOW LABELS
SHOW EDGE_TYPES
SHOW PROPERTIES File
SHOW SCHEMA

EXPLAIN

Use the dedicated explain endpoint:

POST /api/v1/query/explain

Example:

curl -X POST https://api.knowledgedataflow.org/api/v1/query/explain \
  -H "Content-Type: application/json" \
  -d '{"query":"MATCH (n:File) RETURN COUNT(n)"}'

Routing Contract

Path	Language	Backend
/api/v1/query	KQL	ClickHouse
/api/v1/query/sql	SQL	ScyllaDB
/api/v1/query/explain	Explain	Planner only

If KQL and SQL produce conflicting counts for the same dataset, treat that as a CDC bug, not a normal difference in semantics.