fauna query

fauna eval [<fql>] [flags]

Run a provided FQL query.

You can provide the query as a positional <fql> query string. To read the query from stdin, use - as the query string. You can also use --input to provide the query as a file.

Queries run in the context of a single database, specified using --database or --secret. If using --secret, queries run in the database to which the secret is scoped.

By default, FQL v10 query results are output as copy-pastable FQL. To get results in JSON, use --format json or --json. JSON results are encoded using the simple data format.

Positional arguments

<fql>

FQL query string to run. Use - to read from stdin.

Flags

API
-u, --user <string>

CLI user to run the command as. You must first log in as the user using fauna login. Defaults to default. See Interactive login.

--local

Use a local Fauna container.

If not otherwise specified, this flag sets:

--url <string>

URL for Core HTTP API requests made by the command. Defaults to https://db.fauna.com.

--secret <string>

Secret used for authentication. Supports scoped keys. The command runs in the database to which the secret is scoped.

If the secret is a key secret with the admin role, you can pass this flag with --database and an optional --role to create and use a scoped key that impersonates a role on a child database. See Scoped keys.

--account-key <string>

Fauna account key used for authentication. If used, you must also provide a --database and an optional --role. See Account key authentication.

Can’t be used with --user or --secret. If --account-key and --user are specified, --user is ignored.

-d, --database <string>

Database, including the region group identifier and hierarchy, to run the command in. Supports shorthand region group identifiers. Separate path components using /. Examples: us/my_db, eu/parent_db/child_db, global/db. Can’t be used with --secret.

If using a local Fauna container, omit the region group.

-r, --role <string>

Role used to run the command. Defaults to admin. Can’t be used with --secret.

-v, --api-version <number>

FQL version to use. Accepts one of the following:

-f, --format <string>

Output format for query results. Accepts fql (Default) and json. Only applies to FQL v10 queries. --json overrides --format.

--typecheck

Enable query typechecking. Only applies to FQL v10 queries. If omitted, uses the typechecking setting of the database.

--timeout <number>

Maximum query runtime, in milliseconds.

--performance-hints

Output performance hints. Sets --include summary. Only applies to FQL v10 queries. If no performance hints are returned, no hints are output.

Output
--color

Enable color formatting for output. Enabled by default. Use --no-color to disable.

--json

Output results as JSON. This flag doesn’t affect error output.

--quiet

Suppress all log messages except fatal errors. Output only command results. Overrides --verbosity and --verbose-component.

Config
--config <string>

Path to a CLI config file to use. If provided, must specify a profile.

-p, --profile <string>

Profile from the CLI config file. A profile is a group of CLI settings.

Debug
--verbose-component <array>

Components to emit logs for. Overrides --verbosity.

Accepts the following values:

  • argv

  • config

  • creds

  • error

  • fetch

Pass values as a space-separated list. Example: --verbose-component argv config.

--verbosity <number>

Least critical log level to emit. Accepts integers ranging from 1 (fatal) to 5 (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged.

Options
-h, --help

Show help.

--version

Show the Fauna CLI version.

--include <array>

Include additional query response data in the output. Only applies to FQL v10 queries.

Accepts the following values:

  • all

  • none

  • txnTs

  • schemaVersion

  • summary

  • queryTags

  • stats

Defaults to only summary. Pass values as a space-separated list, such as --include summary queryTags. Each value corresponds to a field from the query response.

-i, --input <string>

Path to a file containing an FQL query to run. Can’t be used with the <fql> positional argument.

The file can use any file extension. .fql is recommended.

-o, --output <string>

Path to a file where query results are written. If omitted, writes to stdout.

Examples

# Run the query in the 'us/my_db' database and write
# the results to stdout.
fauna query "Collection.all()" \
  --database us/my_db

# Run the query in the 'us/my_db' database using the
# server role.
fauna query "Collection.all()" \
  --database us/my_db \
  --role server

# Run the query in the database scoped to a secret.
fauna query "Collection.all()" \
  --secret my-secret

# Run the query from a file.
fauna query \
  --input /path/to/query.fql \
  --database us/my_db

# Run the query from stdin.
echo "1 + 1" | fauna query - \
  --database us/my_db

# Run the query and write the results to a file.
fauna query \
  --input /path/to/query.fql \
  --output /tmp/result.json \
  --database us/my_db

Aliases

fauna eval
\