query method

Future<FaunaResponse> query(
  1. Object expression, {
  2. FaunaConfig? options,
})

Executes a query via the FaunaDB Query API.

expression must be either:

  • composed using functions from the query classes
  • serializable JSON representation of an FQL query.

Queries built using the query classes look very similar to real FQL. It was an aim to mimic FQL function names and arguments as closely as possible. Docs on all FQL functions can be found here.

Example query expression:

Paginate(Match(Index('all_customers')))

However some notable differences are:

  • Optional FQL arguments are named arguments in Dart. e.g. Repeat('x', number: 10)
  • FQL functions with a variable number of arguments (such as Sum, GT etc.) accept a Dart List instead.
  • Some FQL functions and arguments are reserved keywords in Dart; simply add a trailing underscore to them (Map -> Map_, Function -> Function_, default -> default_)

Any value serializable to valid JSON can also be passed as an expression.

Docs on JSON query syntax can be found here.

Example JSON expression:

{
  'paginate': {
    'match': {'index': 'all_products'},
  }
}

Throws TimeoutException if query response is not received within config.timeout.

Implementation

Future<FaunaResponse> query(Object expression, {FaunaConfig? options}) {
  final config = (options ?? this.config);
  return _httpClient
      .post(
        config.baseUrl,
        headers: config.requestHeaders,
        body: json.encode(expression),
      )
      .timeout(config.timeout)
      .then((Response response) => FaunaResponse.fromBody(response.body));
}