> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vrin.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK: Querying

> query, queryStream, queryEvents, response modes, and depth levels.

The `VrinClient` exposes three query methods, each tuned for a different integration pattern:

| Method          | Returns                                         | Use when                                                 |
| --------------- | ----------------------------------------------- | -------------------------------------------------------- |
| `query()`       | `QueryResult` (resolves once complete)          | You just want the final answer.                          |
| `queryStream()` | `AsyncGenerator<string>` (content deltas)       | You want token-by-token streaming.                       |
| `queryEvents()` | `AsyncGenerator<StreamEvent>` (full SSE frames) | You want progress, sources, and metadata, not just text. |

## `client.query(options)`

```typescript theme={null}
const result = await client.query({
  query: "What is ACME's Q4 revenue?",
  mode: "chat",               // "chat" | "expert" | "brainstorm" | "context" | "raw_facts"
  depth: "thinking",          // "basic" | "thinking" | "research"
  model: "gpt-5.2",
  sessionId: "sess_abc",
  maintainContext: true,
  includeSummary: true,
  webSearchEnabled: false,
  conversationUploadIds: ["upload_123"],
});

result.summary;       // "ACME Corp reported $50M in Q4 2025..."
result.session_id;    // "sess_abc" — echoed back for multi-turn
result.total_facts;   // 12
result.sources;       // [{ title, chunk_id, score, ... }, ...]
result.entities;      // ["ACME Corp", "Jane Smith"]
```

### QueryOptions fields

| Field                   | Type           | Default        | Description                                                                                |
| ----------------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `query`                 | `string`       | required       | The natural-language question.                                                             |
| `mode`                  | `ResponseMode` | `"chat"`       | Output shape. See [response modes](/agents#response-modes-when-using-sdk-or-mcp).          |
| `depth`                 | `QueryDepth`   | backend-chosen | `"basic"`, `"thinking"`, or `"research"`. Only applies in `context` mode.                  |
| `model`                 | `string`       | backend-chosen | LLM override, e.g. `"gpt-5.2"`, `"claude-4-haiku"`. Must be in your plan's allowed models. |
| `sessionId`             | `string`       | —              | Continue a multi-turn conversation.                                                        |
| `maintainContext`       | `boolean`      | `false`        | If true, a new `session_id` is created and returned.                                       |
| `includeSummary`        | `boolean`      | `true`         | Set false to skip LLM generation and return raw facts only.                                |
| `webSearchEnabled`      | `boolean`      | `false`        | Augment retrieval with live web search (brainstorm mode).                                  |
| `conversationUploadIds` | `string[]`     | —              | Scope retrieval to specific uploads.                                                       |

## `client.queryStream(options)`

Yields content deltas as strings. Use for chat UIs.

```typescript theme={null}
for await (const token of client.queryStream({ query: "Summarize ACME's year" })) {
  process.stdout.write(token);
}
```

## `client.queryEvents(options)`

Yields raw SSE events. Agents that render progress, show sources, or trace reasoning should use this.

```typescript theme={null}
for await (const event of client.queryEvents({ query: "..." })) {
  switch (event.type) {
    case "progress": {
      const d = event.data as { stage: string; step: number; total_steps: number };
      console.log(`[${d.step}/${d.total_steps}] ${d.stage}`);
      break;
    }
    case "content": {
      const d = event.data as { delta: string };
      process.stdout.write(d.delta);
      break;
    }
    case "sources": {
      const d = event.data as { sources: Array<{ title: string }> };
      console.log("\nSources:", d.sources.map((s) => s.title));
      break;
    }
    case "done":
      return;
    case "error": {
      const d = event.data as { message: string };
      throw new Error(d.message);
    }
  }
}
```

### Event types

| `type`      | Payload fields                                                   |
| ----------- | ---------------------------------------------------------------- |
| `progress`  | `stage`, `label`, `step`, `total_steps`, `elapsed_ms`            |
| `metadata`  | `session_id`, `total_facts`, `total_chunks`, `entities`, `model` |
| `content`   | `delta` (partial token text)                                     |
| `reasoning` | `chains` or `steps` (expert mode)                                |
| `sources`   | `sources: [{ title, chunk_id, score }]`                          |
| `done`      | —                                                                |
| `error`     | `message`                                                        |

## Response modes

See the [agent-facing mode table](/agents#response-modes-when-using-sdk-or-mcp) for guidance on which to pick. Short version:

* `chat` — concise prose answer. Default for chat UIs.
* `context` — structured facts for an **agent** to synthesize. Default for agent tools.
* `expert` — includes reasoning chain. Slower, more expensive.
* `brainstorm` — combines Vrin + web search. Use with `webSearchEnabled: true`.
* `raw_facts` — no LLM generation; just the graph facts.