Skip to main content

​
Overview

The query tool performs hybrid search (BM25 keyword + semantic vector search) across the code knowledge graph, returning execution flows (processes) ranked by relevance. Unlike traditional grep or IDE search that returns file matches, query returns how code works together through call chains and relationships.
When to use: Understanding how code works together. Use when you need execution flows and relationships, not just file matches. Complements grep/IDE search.Next step: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).

​
Parameters

​
query
string
required
Natural language or keyword search query describing what you’re looking forExamples:
  • "payment processing"
  • "user authentication flow"
  • "database connection setup"
​
task_context
string
What you are working on (e.g., “adding OAuth support”). Helps improve ranking by understanding your current task.
​
goal
string
What you want to find (e.g., “existing auth validation logic”). Helps narrow results to your specific intent.
​
limit
number
default:5
Maximum number of processes (execution flows) to returnRange: 1-20 recommended
​
max_symbols
number
default:10
Maximum number of symbols to include per processRange: 1-50 recommended
​
include_content
boolean
default:false
Include full source code for each symbol in results. Set to true when you need implementation details.
Enabling this significantly increases response size and token usage.
​
repo
string
Repository name or path. Required when multiple repos are indexed. Omit if only one repo is available.

​
Response

Returns results grouped by process (execution flow):
​
processes
array
required
Ranked execution flows with relevance priority
​
process_symbols
array
required
All symbols participating in the returned processes
​
definitions
array
Standalone types/interfaces not participating in any process but matching the query

​
Example Usage

​
Basic Query

query({
  query: "payment processing"
})

​
Query with Context and Goal

query({
  query: "authentication",
  task_context: "adding OAuth support",
  goal: "existing auth validation logic",
  limit: 3
})

​
Query with Full Source Code

query({
  query: "error handling",
  include_content: true,
  max_symbols: 5
})

​
Multi-Repo Query

query({
  query: "payment processing",
  repo: "my-app"
})

​
Example Response

{
  "processes": [
    {
      "name": "CheckoutFlow",
      "relevance": 0.94,
      "steps": 7,
      "module": "Payments"
    },
    {
      "name": "RefundFlow",
      "relevance": 0.82,
      "steps": 5,
      "module": "Payments"
    }
  ],
  "process_symbols": [
    {
      "uid": "func_processPayment_abc123",
      "name": "processPayment",
      "type": "Function",
      "filePath": "src/payments/processor.ts",
      "line": 42,
      "module": "Payments",
      "process": "CheckoutFlow"
    },
    {
      "uid": "func_validateCard_def456",
      "name": "validateCard",
      "type": "Function",
      "filePath": "src/payments/validator.ts",
      "line": 18,
      "module": "Payments",
      "process": "CheckoutFlow"
    }
  ],
  "definitions": [
    {
      "name": "PaymentIntent",
      "type": "Interface",
      "filePath": "src/types/payment.ts",
      "line": 12
    }
  ]
}

​
Ranking Algorithm

query uses Reciprocal Rank Fusion (RRF) to combine:
  1. BM25 keyword search - Traditional text matching
  2. Semantic vector search - Meaning-based similarity using embeddings
This hybrid approach ensures both exact matches and conceptually related code are surfaced.

​
Real-World Examples

​
Example 1: Understanding Payment Flow

// Task: "How does payment processing work?"
query({
  query: "payment processing",
  task_context: "understanding checkout flow",
  goal: "see how payments are validated and charged"
})

// Returns:
// - CheckoutFlow: processPayment → validateCard → chargeStripe
// - RefundFlow: initiateRefund → calculateRefund → processRefund

​
Example 2: Finding Auth Logic

// Task: "Where is user authentication handled?"
query({
  query: "user authentication validation",
  limit: 3,
  max_symbols: 8
})

// Returns:
// - LoginFlow: validateUser → checkToken → getUserById
// - TokenRefresh: refreshToken → validateRefreshToken → issueNewToken

​
Best Practices

query understands concepts, not just keywords. Use descriptive phrases like “payment processing flow” instead of just “payment”.
Adding task_context and goal significantly improves ranking by helping the tool understand what you’re trying to accomplish.
The default limit: 5 and max_symbols: 10 work well for most queries. Only adjust if you need broader or narrower results.
After identifying relevant symbols, use context() for a deeper 360-degree view including all callers, callees, and process participation.
Start without full source code to keep responses manageable. Enable include_content: true only when you need implementation details.

​
Use Cases

  • Code exploration: “How does X work?”
  • Feature location: “Where is the Y functionality?”
  • Debugging: “What code handles Z errors?”
  • Architecture understanding: “Show me the main components”
  • Onboarding: Understanding unfamiliar codebases
  • context - Deep dive on specific symbols from query results
  • cypher - Custom graph queries for advanced use cases
  • list_repos - Discover available repositories first
  • gitnexus://repo/{name}/processes - Browse all execution flows
  • gitnexus://repo/{name}/process/{name} - View full step-by-step trace

Build docs developers (and LLMs) love

Get started for freeTalk to us