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.

--graphqlHost=<name>

Not supported.

--graphqlPort=<number>

Not supported.

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!