> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/abhigyanpatwari/GitNexus/llms.txt
> Use this file to discover all available pages before exploring further.

# query

> Query the code knowledge graph for execution flows related to a concept

## 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.

<Info>
  **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).
</Info>

## Parameters

<ParamField path="query" type="string" required>
  Natural language or keyword search query describing what you're looking for

  **Examples:**

  * `"payment processing"`
  * `"user authentication flow"`
  * `"database connection setup"`
</ParamField>

<ParamField path="task_context" type="string">
  What you are working on (e.g., "adding OAuth support"). Helps improve ranking by understanding your current task.
</ParamField>

<ParamField path="goal" type="string">
  What you want to find (e.g., "existing auth validation logic"). Helps narrow results to your specific intent.
</ParamField>

<ParamField path="limit" type="number" default={5}>
  Maximum number of processes (execution flows) to return

  Range: 1-20 recommended
</ParamField>

<ParamField path="max_symbols" type="number" default={10}>
  Maximum number of symbols to include per process

  Range: 1-50 recommended
</ParamField>

<ParamField path="include_content" type="boolean" default={false}>
  Include full source code for each symbol in results. Set to `true` when you need implementation details.

  <Warning>Enabling this significantly increases response size and token usage.</Warning>
</ParamField>

<ParamField path="repo" type="string">
  Repository name or path. Required when multiple repos are indexed. Omit if only one repo is available.
</ParamField>

## Response

Returns results grouped by process (execution flow):

<ResponseField name="processes" type="array" required>
  Ranked execution flows with relevance priority

  <Expandable title="process properties">
    <ResponseField name="name" type="string">
      Human-readable process name (e.g., "LoginFlow", "CheckoutFlow")
    </ResponseField>

    <ResponseField name="relevance" type="number">
      Relevance score from hybrid ranking (0-1)
    </ResponseField>

    <ResponseField name="steps" type="number">
      Number of steps in this execution flow
    </ResponseField>

    <ResponseField name="module" type="string">
      Functional area/community this process belongs to
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="process_symbols" type="array" required>
  All symbols participating in the returned processes

  <Expandable title="symbol properties">
    <ResponseField name="uid" type="string">
      Unique identifier for zero-ambiguity lookups
    </ResponseField>

    <ResponseField name="name" type="string">
      Symbol name
    </ResponseField>

    <ResponseField name="type" type="string">
      Symbol type: Function, Class, Method, Interface, etc.
    </ResponseField>

    <ResponseField name="filePath" type="string">
      Relative path to the file containing this symbol
    </ResponseField>

    <ResponseField name="line" type="number">
      Line number where symbol is defined
    </ResponseField>

    <ResponseField name="module" type="string">
      Functional area this symbol belongs to
    </ResponseField>

    <ResponseField name="process" type="string">
      Name of the process this symbol participates in
    </ResponseField>

    <ResponseField name="content" type="string">
      Full source code (only when `include_content: true`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="definitions" type="array">
  Standalone types/interfaces not participating in any process but matching the query
</ResponseField>

## Example Usage

### Basic Query

```javascript theme={null}
query({
  query: "payment processing"
})
```

### Query with Context and Goal

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

### Query with Full Source Code

```javascript theme={null}
query({
  query: "error handling",
  include_content: true,
  max_symbols: 5
})
```

### Multi-Repo Query

```javascript theme={null}
query({
  query: "payment processing",
  repo: "my-app"
})
```

## Example Response

```json theme={null}
{
  "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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

<AccordionGroup>
  <Accordion title="Use natural language queries">
    `query` understands concepts, not just keywords. Use descriptive phrases like "payment processing flow" instead of just "payment".
  </Accordion>

  <Accordion title="Provide task context">
    Adding `task_context` and `goal` significantly improves ranking by helping the tool understand what you're trying to accomplish.
  </Accordion>

  <Accordion title="Start with defaults">
    The default `limit: 5` and `max_symbols: 10` work well for most queries. Only adjust if you need broader or narrower results.
  </Accordion>

  <Accordion title="Follow up with context()">
    After identifying relevant symbols, use `context()` for a deeper 360-degree view including all callers, callees, and process participation.
  </Accordion>

  <Accordion title="Avoid include_content initially">
    Start without full source code to keep responses manageable. Enable `include_content: true` only when you need implementation details.
  </Accordion>
</AccordionGroup>

## 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

## Related Tools

* [context](/api/tools/context) - Deep dive on specific symbols from query results
* [cypher](/api/tools/cypher) - Custom graph queries for advanced use cases
* [list\_repos](/api/tools/list-repos) - Discover available repositories first

## Related Resources

* `gitnexus://repo/{name}/processes` - Browse all execution flows
* `gitnexus://repo/{name}/process/{name}` - View full step-by-step trace