---
metadata:
  - name: generator
    content: Diplodoc Platform v5.61.1
alternate:
  - https://ydb.tech/docs/en/dev/query-execution-optimization/parameterized-queries.md
  - https://ydb.tech/docs/ru/dev/query-execution-optimization/parameterized-queries.md
  - href: https://ydb.tech/docs/en/dev/query-execution-optimization/parameterized-queries.md
    type: text/markdown
    title: Markdown version
  - href: https://ydb.tech/docs/en/llms.txt
    rel: describedby
sourcePath: en/core/dev/query-execution-optimization/parameterized-queries.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/en/llms.txt

# Parameterized queries and recompilation

Query compilation takes time and resources, so YDB provides a [compile cache](https://ydb.tech/docs/en/concepts/glossary.md#compile-cache). The compilation result is stored in the cache on a cluster [node](https://ydb.tech/docs/en/concepts/glossary.md#node) and reused only when the query **text matches exactly**. If your application builds YQL with string concatenation or formatting, each new set of values produces a **different text**, and the server recompiles it even when the SQL structure is the same.

Consequences:

- higher latency at the compilation stage;
- increased CPU load on nodes;
- with many unique query texts, reuse of the limited per-node cache gets worse.

A **parameterized query** helps avoid extra compilation: the YQL text stays fixed, and input values are passed separately via [named parameters](https://ydb.tech/docs/en/yql/reference/syntax/declare.md) (for example, `$userId`). Below, both approaches are compared on the same example.

## Embedding values in the query text

The application inserts values directly into the query text:

```yql
SELECT id, name FROM users WHERE id = 123 AND status = "active";
SELECT id, name FROM users WHERE id = 456 AND status = "inactive";
```

The queries differ only in values, but the texts are different — for the server these are two different queries, and each one is compiled separately.

## Passing values as parameters

The application passes values separately from the text; the query text does not change:

```yql
DECLARE $userId AS Uint64;
DECLARE $status AS Utf8;

SELECT id, name FROM users WHERE id = $userId AND status = $status;
```

The server handles calls to such a query differently:

1. **First call** — the server compiles the query and stores the result in the cache on the node.
2. **Later calls** — if the text is already in the cache, the ready result is reused: only `$userId` and `$status` change; recompilation is not required.

Only values can be passed as parameters: you cannot parameterize a table name or sort order; changing them changes the query text.

See [Query compile cache](https://ydb.tech/docs/en/dev/system-views.md#compile-cache-queries) for cache contents, and [Top queries](https://ydb.tech/docs/en/dev/system-views.md#top-queries) for compilation time when queries run (the `CompileDuration` field).

Cache size and settings, the `KeepInCache` flag, [`DECLARE`](https://ydb.tech/docs/en/yql/reference/syntax/declare.md) syntax, and passing parameters from code are described in [Parameterized queries](https://ydb.tech/docs/en/reference/ydb-sdk/parameterized_queries.md) in the YDB SDK reference.

## See also

- [Using query plans for query optimization](https://ydb.tech/docs/en/dev/query-execution-optimization/query-plans-optimization.md)
- [Query compile cache](https://ydb.tech/docs/en/dev/system-views.md#compile-cache-queries)
- [Parameterized queries](https://ydb.tech/docs/en/reference/ydb-sdk/parameterized_queries.md) (SDK reference)
- [Executing parameterized queries](https://ydb.tech/docs/en/reference/ydb-cli/parameterized-query-execution.md) (CLI reference)
- [Application examples](https://ydb.tech/docs/en/dev/example-app/index.md#param-queries)
- [Query execution optimization overview](https://ydb.tech/docs/en/dev/query-execution-optimization/index.md)