eval

Run an FQL query.

Syntax

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]

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 you omit command line options, Fauna uses the configuration file options.

If the query returns an error, fauna-shell 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.

Arguments

Argument Description

DBNAME

Name of the database the query should be run against.

QUERY

Query you want to run.

Options

Option Description

--endpoint

Connection endpoint, from the ~/.fauna-shell file.

--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

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

--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 the \~/.fauna-shell file.

--version

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

Examples

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

QUERY argument

fauna eval "Collection.all()"
{
  data: [
    {
      name: "People",
      coll: Collection,
      ts: Time("2023-08-23T00:26:16.680Z"),
      indexes: {
        byEmail: {
          terms: [
            {
              field: "email"
            }
          ],
          queryable: true,
          status: "complete"
        }
      },
      constraints: [
        {
          unique: [
            "email"
          ],
          status: "active"
        }
      ]
    }
  ]
}

QUERY file

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

fauna eval --file=./query.fql

STDIN query

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

Database query

fauna eval my-test-db "Collection.all()"

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

fauna eval nonexistdb "Collection.all()"
{"data":[]}

Output to a file

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

Format the output in Fauna Shell format:

fauna eval Collection.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!