---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ydb.tech/docs/en/reference/ydb-cli/yql.md?version=v25.4
  - https://ydb.tech/docs/ru/reference/ydb-cli/yql.md?version=v25.4
  - href: en/reference/ydb-cli/yql.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
sourcePath: en/core/reference/ydb-cli/yql.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/en/llms.txt


# Running a script (with streaming support)

<!-- source: en/reference/ydb-cli/_includes/deprecated_command_warning.md -->
{% note warning %}

This command is deprecated.
The preferred way to run queries in YDB CLI is to use the [`ydb sql`](https://ydb.tech/docs/en/reference/ydb-cli/sql.md?version=v25.4) command.

{% endnote %}
<!-- endsource: en/reference/ydb-cli/_includes/deprecated_command_warning.md -->

You can use the `yql` subcommand to run a YQL script. The script can include queries of different types. Unlike `scripting yql`, the `yql` subcommand establishes a streaming connection and retrieves data through it. With the in-stream query execution, no limit is imposed on the amount of data read.

General format of the command:

```bash
ydb [global options...] yql [options...]
```

* `global options`: [Global parameters](https://ydb.tech/docs/en/reference/ydb-cli/commands/global-options.md?version=v25.4).
* `options`: [Parameters of the subcommand](#options).

View the description of the YQL script command:

```bash
ydb yql --help
```

## Parameters of the subcommand {#options}

#|
|| Name | Description ||
|| `--timeout` | The time within which the operation should be completed on the server. ||
|| `--stats` | Statistics mode.

Acceptable values:

* `none` (default): Do not collect.
* `basic`: Collect statistics for basic events.
* `full`: Collect statistics for all events.

     ||
|| `-s`, `--script` | Text of the YQL query to be executed. ||
|| `-f`, `--file` | Path to the text of the YQL query to be executed. ||
|| `--format` | Result format.

Possible values:

<!-- source: en/reference/ydb-cli/_includes/result_format_common.md -->
* `pretty` (default): Human-readable format.
* `json-unicode`: [JSON](https://en.wikipedia.org/wiki/JSON) output with binary strings [Unicode](https://en.wikipedia.org/wiki/Unicode)-encoded and each JSON string in a separate line.
* `json-unicode-array`: JSON output with binary strings Unicode-encoded and the result output as an array of JSON strings with each JSON string in a separate line.<li>`json-base64`: JSON output with binary strings [Base64](https://en.wikipedia.org/wiki/Base64)-encoded and each JSON string in a separate line.
* `json-base64-array`: JSON output with binary strings Base64-encoded and the result output as an array of JSON strings with each JSON string in a separate line;
* `parquet`: Output in [Apache Parquet](https://parquet.apache.org/docs/) format.
<!-- endsource: en/reference/ydb-cli/_includes/result_format_common.md -->

<!-- source: en/reference/ydb-cli/_includes/result_format_csv_tsv.md -->
* `csv`: Output in [CSV](https://en.wikipedia.org/wiki/CSV) format.
* `tsv`: Output in [TSV](https://en.wikipedia.org/wiki/Tab-separated_values) format.
<!-- endsource: en/reference/ydb-cli/_includes/result_format_csv_tsv.md -->

||
|#

### Working with parameterized queries {#parameterized-query}

<!-- source: en/_includes/parameterized-query.md -->
A brief help is provided below. For a detailed description with examples, see [Running parametrized YQL queries and scripts](https://ydb.tech/docs/en/reference/ydb-cli/parameterized-queries-cli.md?version=v25.4).

| Name | Description |
---|---
| `-p, --param` | The value of a single parameter of a YQL query, in the format: `$name=value`, where `$name` is the parameter name and `value` is its value (a valid [JSON value](https://www.json.org/json-ru.html)). |
| `--param-file` | Name of the file in [JSON](https://en.wikipedia.org/wiki/JSON) format and in [UTF-8](https://en.wikipedia.org/wiki/UTF-8) encoding that specifies values of the parameters matched against the YQL query parameters by key names. |
| `--input-format` | Format of parameter values. Applies to all the methods of parameter transmission (among command parameters, in a file or using `stdin`).<br/>Acceptable values:<ul><li>`json-unicode` (default):[JSON](https://en.wikipedia.org/wiki/JSON).</li><li>`json-base64`: [JSON](https://en.wikipedia.org/wiki/JSON) format in which values of binary string parameters (`DECLARE $par AS String`) are [Base64](https://en.wikipedia.org/wiki/Base64)-encoded.</li></ul> |
| `--stdin-format` | The parameter format and framing for `stdin`. To set both values, specify the parameter twice.<br/>**Format of parameter encoding for `stdin`**<br/>Acceptable values:<ul><li>`json-unicode`: [JSON](https://en.wikipedia.org/wiki/JSON).</li><li>`json-base64`: [JSON](https://en.wikipedia.org/wiki/JSON) format in which values of binary string parameters (`DECLARE $par AS String`) are [Base64](https://en.wikipedia.org/wiki/Base64)-encoded.</li><li>`raw` is binary data; the parameter name is set in `--stdin-par`.</li></ul>If the format of parameter encoding for `stdin` isn't specified, the format set in `--input-format` is used.<br/><br/>**Classification of parameter sets for `stdin` (framing)**<br/>Acceptable values:<ul><li>`no-framing` (default): Framing isn't used</li><li>`newline-delimited`: The newline character is used in `stdin` to end a given parameter set, separating it from the next one.</li></ul> |
| `--stdin-par` | The name of the parameter whose value will be sent over `stdin` is specified without a `$`. |
| `--batch` | The batch mode of transmitting parameter sets received via `stdin`.<br/>Acceptable values:<ul><li>`iterative` (default): Batch mode is disabled</li><li>`full`: Full-scale batch mode is enabled</li><li>`adaptive`: Adaptive batching is enabled |
| `--batch-limit` | A maximum number of sets of parameters per batch in the adaptive batch mode. The setting of `0` removes the limit.<br/><br/>The default value is `1000`.<br/><br/> |
| `--batch-max-delay` | The maximum delay related to processing the resulting parameter set in the adaptive batch mode. It's set as a number of `s`, `ms`, `m`.<br/><br/>Default value: `1s` (1 second).<br/><br/> |
<!-- endsource: en/_includes/parameterized-query.md -->

## Examples {#examples}

<!-- source: en/_includes/ydb-cli-profile.md -->
{% note info %}

The examples use the `quickstart` profile. To learn more, see [Creating a profile to connect to a test database](https://ydb.tech/docs/en/reference/ydb-cli/profile/create.md?version=v25.4#quickstart).

{% endnote %}
<!-- endsource: en/_includes/ydb-cli-profile.md -->

A script to create a table, populate it with data, and select data from the table:

```bash
ydb -p quickstart yql -s '
    CREATE TABLE series (series_id Uint64, title Utf8, series_info Utf8, release_date Date, PRIMARY KEY (series_id));
    COMMIT;
    UPSERT INTO series (series_id, title, series_info, release_date) values (1, "Title1", "Info1", Cast("2023-04-20" as Date));
    COMMIT;
    SELECT * from series;
  '
```

Command output:

```text
┌──────────────┬───────────┬─────────────┬──────────┐
| release_date | series_id | series_info | title    |
├──────────────┼───────────┼─────────────┼──────────┤
| "2023-04-20" | 1         | "Info1"     | "Title1" |
└──────────────┴───────────┴─────────────┴──────────┘
```

Running a script from the example above saved as the `script1.yql` file, with results output in `JSON` format:

```bash
ydb -p quickstart yql -f script1.yql --format json-unicode
```

Command output:

```text
{"release_date":"2023-04-20","series_id":1,"series_info":"Info1","title":"Title1"}
```

You can find examples of passing parameters to scripts in the [article on how to pass parameters to YQL execution commands](https://ydb.tech/docs/en/reference/ydb-cli/parameterized-queries-cli.md?version=v25.4).