Query data with FQL

Reference: FQL language reference, FQL API reference

Fauna Query Language (FQL) is a TypeScript-like language used to read and write data in Fauna:

// Calls the `all()` method on the `Product` collection.
// Returns all `Product` collection documents.
Product.all()

For a examples of covering basic operations using FQL queries, including document CRUD operations, see Basic operations. For other common FQL query patterns, see FQL query patterns.

For a quick reference of FQL methods, check out the FQL cheat sheet.

Method chaining

You typically compose an FQL query by chaining methods to one or more collections. Expressions are evaluated from left to right.

// `firstWhere()` gets the first `Product` collection document with
// a `name` of `cups`. `update()` updates the document's `name`
// field value to `clear cups`. The `?.` operator only calls
// `update()` if `firstWhere()` returns a non-null value.
Product.firstWhere(.name == "cups")?.update({ name: "clear cups" })
See Field accessors and method chaining

Static typing

FQL is statically typed. Every expression has a data type that’s checked before evaluation. If Fauna detects a type mismatch, it rejects the query with an error.

Type checking helps catch errors early and consistently, saving you time during development.

See Static typing

Indexes

An index stores, or covers, specific document field values for quick retrieval.

You can use indexes to filter and sort a collection’s documents in a performant way. Unindexed queries should be avoided.

See Indexes

Relationships

You create relationships by including a reference to a document in another document. This lets you model complex data structures without duplicating data across collections.

// Get a `Category` collection document.
let produce = Category.byName("produce").first()

// Create a `Product` collection document that references
// the `Category` collection document in the `category` field.
Product.create({
  name: "key lime",
  description: "Organic, 1 ct",
  price: 79,
  category: produce,
  stock: 2000
})
See Model relationships using document references

Projection

Projection lets you return only the specific fields you want from queries.

You can project results to dynamically resolve document relationships. This lets you traverse multiple deeply nested relationships in a single query.

// Uses projection to only return each document's `name`,
// `description`, and `category` fields. The `category` field
// contains a resolved `Category` collection document.
Product.byName("key lime") { name, description, category }
See Projection and field aliasing

Pagination

Fauna provides pagination for queries that return large datasets. Fauna client drivers include methods for iterating through paginated query results.

See Pagination

Query composition

The Fauna client drivers compose queries using template strings. You can interpolate variables, including other FQL template stings, to build dynamic queries.

For example, using the JavaScript driver:

import { Client, fql } from "fauna";

const client = new Client({
    secret: 'FAUNA_SECRET'
});

const minPrice = 5_00;
const maxPrice = 50_00;

const query = fql`
  Product.where(.price >= ${minPrice} && .price <= ${maxPrice})
`;

let response = await client.query(query);
console.log(response.data);
client.close();
See Query composition

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!