FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, review the migration guide. Contact support@fauna.com with any questions.

eval

Run the query.

Syntax

fauna eval [DBNAME] QUERY [OPTIONS]

Description

The eval command runs the QUERY in the optional DBNAME, the query is executed in the child database. If you specify a DBNAME, it must be the first argument. The QUERY can be read from STDIN, a file, or the command line. The query results can be output to STDOUT or a file, and you can define the output format.

If you don’t pass any options at the command line, Fauna uses the options in the fauna-shell configuration file.

If the query does not execute successfully and returns an error, fauna-shell exits with a non-zero exit code.

It is not possible to use this command to execute a query in a parent or peer database. To access a database outside of the current database, use the Fauna Dashboard.

Arguments

Argument Description

DBNAME

Optional name of a child database where the query should be executed.

QUERY

Optional query that you want to execute.

Options

Option Description

--file=<file>

Optional file to read the query (or queries) from.

--format=<format>

Optional output format. Must be one of:

- json: A simple JSON format. - json-tagged: Tagged format. In v4, this flag behaves the same as the json flag. - shell: Decorated format. This is a JavaScript-based notation that is aware of Fauna data types.

The default is shell when output is to a terminal and json when piping to another command.

--typecheck

Enable type checking.

--version

Enable type checking.

--domain=<domain>

Optional Fauna server domain, that is, the hostname where Fauna is running. Defaults to db.fauna.com.

--endpoint=<name>

Optional name of the endpoint to use for the command.

--port=<number>

Optional connection port. Defaults to 8443.

--scheme=<scheme>

Optional connection scheme. Must be one of https or http. Defaults to https.

--secret=<secret>

Optional secret to use. A secret authenticates your connection to Fauna, and connects you to a database.

--timeout=<integer>

Optional connection timeout, an integer number of milliseconds. When the interval has elapsed, fauna-shell stops waiting for a response and displays an error.

The default is zero, which means that fauna-shell waits until a response is received.

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

Child database query

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

When the child database does not 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!