format

Available since: v3.3.0

Reformat a SurrealQL file, or a query read from standard input, without connecting to a server. The command parses each statement and prints it back out from the parsed syntax tree, so the result reflects what the statements are rather than how they were typed.

surreal format [OPTIONS] <FILE>

fmt is an alias for format, so surreal fmt query.surql runs the same command.

Example usage

Take a file written in lowercase, with double-quoted strings and a run of blank lines in the middle:

-- Set up the person table
define table person schemafull;
define field name on person type string;
define field age on person type int;


create person:tobie set name="Tobie", age=35;
select name, age from person where age>18 order by name;

Passing the path to surreal format prints the formatted file to standard output and leaves the file on disk untouched.

surreal format person.surql

-- Set up the person table
DEFINE TABLE person TYPE NORMAL SCHEMAFULL
	PERMISSIONS NONE;
DEFINE FIELD name ON person TYPE string
PERMISSIONS FULL;
DEFINE FIELD age ON person TYPE int
PERMISSIONS FULL;

CREATE person:tobie SET name = 'Tobie', age = 35;
SELECT name, age FROM person WHERE age > 18 ORDER BY name;

Each statement comes back with its keywords in uppercase, single-quoted strings, spaces around operators, and the clauses that were left implicit written out in full. DEFINE TABLE person SCHEMAFULL becomes DEFINE TABLE person TYPE NORMAL SCHEMAFULL PERMISSIONS NONE, which is the same definition the server stores and the same one INFO FOR DB reports.

Writing the result back to the file

The --write flag replaces the contents of the file with the formatted output and prints nothing.

surreal format --write person.surql

Running the command a second time on an already formatted file leaves it unchanged, so --write is safe to run repeatedly.

Formatting input from stdin

Pass - as the file to read the query from standard input and write the result to standard output.

echo 'select * from person where age>18 order by name desc limit 5;' | surreal format -

SELECT * FROM person WHERE age > 18 ORDER BY name DESC LIMIT 5;

--write has no file to write back to in this mode, so combining it with - reports The --write flag cannot be used when reading from stdin. and formats nothing.

What the formatter changes

• •

  Keywords are uppercased, and clauses left implicit in the source are written out.

• •

  Strings are rewritten with single quotes, and identifiers that collide with a keyword are escaped in backticks.

• •

  Operators get a space on each side, so age>18 becomes age > 18.

• •

  Nested values such as a multi-element array are broken across lines and indented with tabs.

• •

  Single-line comments keep their text and are rewritten with a leading #, whichever of #, -- or // the source used. Block comments written as /* ... */ pass through unchanged.

• •

  Blank lines between statements collapse to a single blank line.

Line structure between statements comes from the source. A statement spread over several lines is joined onto one, and two statements written on one line stay on that line, so the formatter does not impose one statement per line.

Comparison with surqlfmt

surqlfmt also formats SurrealQL, and the two tools are shipped and driven differently.

Reach for surreal format for a single file on a machine that already has the surreal binary, and for surqlfmt to sweep a tree of .surql files or to gate a CI job on formatting.

Command help

To see the help information and usage instructions, in a terminal run the surreal format --help command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the format command.

surreal format --help

The output of the above command:

Format SurrealQL query

Usage: surreal format [OPTIONS] <FILE>

Arguments:
  <FILE>  Path to the SurrealQL file to format. Use dash - to read from stdin.

Options:
  -w, --write  Overwrite the file with the formatted output instead of printing to stdout.
  -h, --help   Print help

Logging:
  -l, --log <LOG>
          The logging level for the command-line tool [env: SURREAL_LOG=] [default: info] [possible
          values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>
          The format for terminal log output [env: SURREAL_LOG_FORMAT=] [default: text] [possible
          values: text, json]
      --log-socket <LOG_SOCKET>
          Send logs to the specified host:port [env: SURREAL_LOG_SOCKET=]
      --log-file-level <LOG_FILE_LEVEL>
          Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL=] [possible
          values: none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>
          Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL=]
          [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>
          Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL=]
          [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>
          The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT=] [default: text] [possible
          values: text, json]
      --log-file-enabled
          Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED=]
      --log-file-path <LOG_FILE_PATH>
          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH=] [default: logs]
      --log-file-name <LOG_FILE_NAME>
          The name of the log file [env: SURREAL_LOG_FILE_NAME=] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>
          The format for log file output [env: SURREAL_LOG_FILE_FORMAT=] [default: text] [possible
          values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>
          The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION=] [default: daily]
          [possible values: daily, hourly, never]