eval

Summary

Runs the specified query.

fauna eval [DBNAME] [QUERY]

Description

The eval command runs the query that you specify. If you specify DBNAME, the query is executed in the specified child database. 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 specify the output format.

If you don’t pass any options at the command line, Fauna uses the options specified 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 - The name of a child database where the query should be executed.

QUERY

Optional - The query that you want to execute.

Options

Option Description

--domain=<domain>

Optional - The Fauna server domain, that is, the hostname where Fauna is running. Defaults to db.fauna.com.
Since the introduction of Region Groups, three cloud domains are available. You do not need to specify a domain, but connections work as expected if you do.
Classic (US and EU): db.fauna.com
United States (US): db.us.fauna.com
Europe (EU): db.eu.fauna.com

--endpoint=<endpoint>

Optional - The name of the endpoint to use for the command.

--port=<port>

Optional - The connection port. Defaults to 8443.

--scheme=<scheme>

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

--secret=<secret>

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

--timeout=<timeout>

Optional - The connection timeout, an integer number of milliseconds. When the specified period 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.

--file=<file>

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

--format=<format>

Optional - The output format. Must be one of:

  • json: JSON format.

  • shell: Fauna Shell format, a JavaScript-based notation that is aware of Fauna data types.

The default is json.

Examples

  1. The following invocation shows running a query passed as an argument:

    fauna eval "Paginate(Collections())"
{"data":[{"@ref":{"id":"FirstCollection","collection":{"@ref":{"id":"collections"}}}}]}

  2. The following invocation shows running a query that exists in a file. The query in the file is identical to the previous example:

    fauna eval --file=./query.fql
{"data":[{"@ref":{"id":"FirstCollection","collection":{"@ref":{"id":"collections"}}}}]}

  3. The following invocation shows passing a query via STDIN:

    echo "Paginate(Collections())" | fauna eval --stdin
{"data":[{"@ref":{"id":"FirstCollection","collection":{"@ref":{"id":"collections"}}}}]

  4. The following invocation shows a child database name and a query argument:

    fauna eval prydain "Paginate(Collections())"
{"data":[]}

  5. The following invocation shows what happens when the specified child database does not exist:

    fauna eval ystrad "Paginate(Collections())"
 ›   Error: Database 'ystrad' doesn't exist

  6. The following invocation shows sending query output to a file:

    fauna eval "Paginate(Collections())" --output=./output.json
    cat ./output.json
{"data":[{"@ref":{"id":"FirstCollection","collection":{"@ref":{"id":"collections"}}}}]

  7. The following invocation shows sending query output to a file in Fauna Shell format:

    fauna eval "Paginate(Collections())" --format=shell --output=./output.json
    cat ./output.json
{ data: [ Collection("FirstCollection") ] }

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!