Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

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

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!