eval

Run an FQL query.

Syntax

fauna eval [DBNAME] QUERY [OPTIONS]

Description

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

The query is executed in the child 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

(Optional) Name of the child database the query should be run against.

QUERY

Query you want to run.

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, which is the Fauna hostname.
Default = db.fauna.com

--endpoint=<name>

(Optional) Endpoint name to use for the command.

--port=<number>

(Optional) Connection port.
Default = 8443

--scheme=<scheme>

(Optional) Connection scheme. Must be one of:
       https (default)
       http

--secret=<secret>

(Optional) Secret to use to connect to a database.

--timeout=<integer>

(Optional) connection timeout, in milliseconds. When the interval elapses, fauna-shell times out and displays an error.
Default = 0, wait indefinitely until a response is received.

--version

(Optional) Fauna Query Language version
       v10 = (default) FQL v10
       v4 = FQL v4

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!