query-pattern

Query Access Pattern Selection

What is the access scenario?

$ARGUMENTS

Three Access Patterns

Pattern	Best For	Key Property
GraphQL	External apps, web frontends, data exploration	Schema-validated, field selection, introspection
MCP	AI agents, LLMs, automated reasoning	Bounded capabilities, full audit trail, structured tools
NATS Direct	Internal services, low-latency paths	No gateway overhead, lowest latency

Quick Decision

Who is calling?

  External app / web frontend  --> GraphQL
  AI agent / LLM               --> MCP
  Internal service              --> NATS Direct
  Multiple caller types         --> Combine patterns (see below)

Decision Matrix

Factor	GraphQL	MCP	NATS Direct
Latency	Higher (HTTP)	Higher (HTTP)	Lowest (direct)
Schema control	Strong (SDL)	Strong (tool schemas)	Per-component
Auditability	Good (query logs)	Excellent (tool call audit)	Manual
Field selection	Yes (client picks fields)	Yes (tool parameters)	No (full response)
External access	Yes	Yes	No (internal only)
Discovery	Schema introspection	Tool list enumeration	Capability queries
NL query support	Yes (query classification)	Yes (query classification)	No

Common Combinations

System Type	Recommended Pattern
Web app backend	GraphQL (user-facing) + NATS Direct (background jobs)
AI-powered system	MCP (agent access) + GraphQL (dashboard/monitoring)
Microservice mesh	NATS Direct (service-to-service) + GraphQL (external API)
Full platform	All three: NATS internal, GraphQL external, MCP for agents

Key Points

• All three patterns read from the same underlying knowledge graph
• Consistency is eventually consistent regardless of access pattern
• GraphQL and MCP both include natural language query classification
• MCP wraps GraphQL capabilities with bounded tool definitions and structured audit
• GraphRAG (community search) and PathRAG (structural traversal) are available through GraphQL and MCP, not NATS Direct currently

GraphRAG vs PathRAG

When choosing query strategy (applicable to GraphQL and MCP):

Pattern	Use When	Returns
GraphRAG	Discovery, Q&A, "what do we know about X?"	Community-scoped results with summaries
PathRAG	Impact analysis, dependencies, "what's affected by X?"	Bounded traversal from known entity

Read docs/concepts/11-query-access.md for full documentation. Read docs/concepts/09-graphrag-pattern.md for GraphRAG details. Read docs/concepts/10-pathrag-pattern.md for PathRAG details.