Running a query

You can use the table query execute subcommand to run single ad-hoc queries of certain types, for the purposes of testing and troubleshooting.

General format of the command:

ydb [global options...] table query execute [options...]

View the description of the YQL query command:

ydb table query execute --help

Parameters of the subcommand

Name Description
--timeout The time within which the operation should be completed on the server.
-t, --type Query type.
Acceptable values:
  • data: A data query.
  • scheme: A scheme query.
  • scan: A scan query.
The default value is data.
--stats Statistics mode.
Acceptable values:
  • none: Do not collect statistics.
  • basic: Collect statistics for basic events.
  • full: Collect statistics for all events.
Defaults to none.
-s Enable statistics collection in the basic mode.
--tx-mode Specify the transaction mode (for data queries).
Acceptable values:
  • serializable-rw: The result of parallel transactions is equivalent to their serial execution.
  • online-ro: Each of the reads in the transaction reads data that is most recent at the time of its execution.
  • stale-ro: Data reads in a transaction return results with a possible delay (fractions of a second).
Default value: serializable-rw.
-q, --query Text of the YQL query to be executed.
-f, --file Path to the text of the YQL query to be executed.
-p, --param Query parameters (for data queries and scan queries).
You can specify multiple parameters. To change the input format, use the --input-format subcommand parameter.
--input-format Input format.
Acceptable values:
  • json-unicode: JSON input with binary strings Unicode-encoded.
  • json-base64: JSON input with binary strings Base64-encoded.
--format Input format.
Default value: pretty.
Acceptable values:
  • pretty: A human-readable format.
  • json-unicode: JSON output with binary strings 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.
  • json-base64: JSON output with binary strings 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.

Examples

Note

The examples use the db1 profile. To learn more, see Creating a connection profile.

Run the data query:

ydb table query execute \
  --query "SELECT season_id, episode_id, title \
  FROM episodes \
  WHERE series_id = 1 AND season_id > 1 \
  ORDER BY season_id, episode_id \
  LIMIT 3"

Result:

┌───────────┬────────────┬──────────────────────────────┐
| season_id | episode_id | title                        |
├───────────┼────────────┼──────────────────────────────┤
| 2         | 1          | "The Work Outing"            |
├───────────┼────────────┼──────────────────────────────┤
| 2         | 2          | "Return of the Golden Child" |
├───────────┼────────────┼──────────────────────────────┤
| 2         | 3          | "Moss and the German"        |
└───────────┴────────────┴──────────────────────────────┘