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!