Run an FQL query.


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


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.

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.


Argument Description


Name of the database the query should be run against.


Query you want to run.


Option Description


Connection endpoint from ~/.fauna-shell.


Environment to use, from a Fauna project.


Name of file with queries to run.


Output format:


Help for run-queries command.


File to write output to.


Secret key. Overrides the secret in ~/.fauna-shell.


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


Connection timeout (milliseconds).


Enable typechecking.


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


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


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

QUERY argument

fauna eval "Product.all()"


  data: [
      id: "402315569179656258",
      coll: Product,
      ts: Time("2099-07-02T16:14:35.500Z"),
      name: "cups",
      description: "Translucent 9 Oz, 100 ct",
      price: 6.98,
      quantity: 90,
      store: Store("402315569175461954"),
      backorderLimit: 5,
      backordered: false

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!