The Fauna service will be ending on May 30, 2025.

For more information on the service wind down, see our announcement and the Fauna Service End-of-Life FAQ.

fauna eval

Run an FQL query.

Syntax

fauna eval [<DBNAME>] <QUERY> [--[no-]color ] [--endpoint <value>]
  [--environment <value>] [--file <value>]
  [--format json|json-tagged|shell] [--output <value>]
  [--secret <value>] [--stdin] [--timeout <value>]
  [--typecheck] [--url <value>] [--version 4|10]

Description

The eval command runs the QUERY against the optional DBNAME database.

The query is executed in the database. If you include a DBNAME, it must be the first argument.

The QUERY can be read from STDIN, a file, or the command line, and query results can be output to STDOUT or a file. You can also define the output format.

If the query returns an error, the Fauna CLI exits with a non-zero exit code.

By default, this command supports FQL v10 queries. For FQL v4 queries, use the --version 4 option.

FQL v4 access

Fauna accounts created after August 21, 2024 can’t use --version 4 or otherwise run FQL v4 queries.

You can’t use this command to execute a query in a parent or peer database. To access a database outside of the current database, log in to the Fauna Dashboard.

Arguments

Argument Description

<DBNAME>

Name of the database the query should be run against.

<QUERY>

Query you want to run.

Options

Option Description

--[no-]color

Enables or disables color formatting for the output. Color formatting is enabled by default if the terminal supports it (determined using chalk/supports-color). Use --no-color to disable.

--endpoint

Connection endpoint from .fauna-shell.

--environment

Environment to use, from a Fauna project.

--file

Name of file with queries to run.

--format

Output format:
     json
     json-tagged
     shell

--help

Help for run-queries command.

--output

File to write output to.

--secret

Authentication secret. Overrides the secret in .fauna-shell.

Use a scoped key to interact with a child database using a parent database’s admin key.

For example, with a parent database’s admin key secret of fn123, you can access a child database by appending the child database name and role: fn123:childDB:admin.

--stdin

Read file input from stdin. Write to stdout by default.

--timeout

Connection timeout (milliseconds).

--typecheck

Enable typechecking.

--url

Database URL. Overrides the URL in .fauna-shell.

--version

FQL Version:
     4 = FQL version 4
     10 = (default) FQL version 10

See FQL v4 access.

Examples

The following examples illustrate the many ways to use the eval command.

QUERY argument

fauna eval "Product.all()"

Response:

{
  data: [
    {
      id: "111",
      coll: Product,
      ts: Time("2099-07-30T22:55:21.670Z"),
      name: "cups",
      description: "Translucent 9 Oz, 100 ct",
      price: 698,
      stock: 100,
      category: Category("123")
    },
    ...
  ]
}

QUERY file

The query in the file is identical to the previous example:

fauna eval --file=./query.fql

STDIN query

echo "Product.all()" | fauna eval --stdin

Database query

fauna eval childDB "Product.all()"

If the database doesn’t exist, a query of this type returns an error:

fauna eval noChildDB "Product.all()"

Output to a file

fauna eval Product.all() --output=./output.json

Format the output:

fauna eval Product.all() --format=shell --output=./output.json
\