Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now GA.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Migrating from v3 of the CLI? See the CLI migration guide.

FSL collection schema

Learn: Schema

An FSL collection schema defines the structure and behavior of a user-defined collection and its documents.

collection Product {
  // Field definitions.
  // Define the structure of the collection's documents.
  name: String?
  description: String?
  price: Int = 0
  stock: Int = 0
  creationTime: Time = Time.now()
  creationTimeEpoch: Int?
  typeConflicts: { *: Any }?

  // Wildcard constraint.
  // Allows or disallows arbitrary ad hoc fields.
  *: Any

  // Migrations block.
  // Used for schema migrations.
  // Instructs Fauna how to handle updates to a collection's
  // field definitions and wildcard constraint.
  // Contains imperative migration statements.
  migrations {
    add .typeConflicts
    add .stock
    add_wildcard
    backfill .stock = 0
    drop .internalDesc
    move_conflicts .typeConflicts
    move .desc -> .description
    split .creationTime -> .creationTime, .creationTimeEpoch
  }

  // Index definition.
  // You use indexes to filter and sort documents
  // in a performant way.
  index byName {
    terms [.name]
    values [desc(.stock), desc(mva(.categories))]
  }

  // Unique constraint.
  // Ensures a field value or combination of field values
  // is unique for each document in the collection.
  // Supports multivalue attribute (`mva`) fields, such as Arrays.
  unique [.name, .description, mva(.categories)]

  // Check constraint.
  // Ensures a field value meets provided criteria
  // before writes. Written as FQL predicate functions.
  check posStock ((doc) => doc.stock >= 0)

  // Computed field.
  // A document field that derives its value from a
  // user-defined, read-only FQL function that runs on every read.
  compute InventoryValue: Number = (.stock * .price)

  // Controls whether you can write to the `ttl` field for collection
  // documents. If the collection schema doesn't contain field
  // definitions, `document_ttls` defaults to `true`. Otherwise,
  // `document_ttls` defaults to `false`.
  document_ttls true

  // Sets the default `ttl` for documents in days from their creation
  // timestamp. You can override the default ttl` during document
  // creation.
  ttl_days 5

  // Controls document history retention.
  history_days 3
}

You can create and manage schema using any of the following:

Fauna stores each collection schema as an FQL document in the Collection system collection.

FSL syntax

[@alias(<aliasId>]
collection <collName> {
  [<fieldName>: <field definition> . . .]
  [migrations <migrations block>]
  [history_days <history days>]
  [document_ttls <Boolean | Null>]
  [ttl_days <time to live days>]
  [index <index name> <index config block> . . .]
  [unique <unique constraint fields> . . .]
  [check <name> <predicateBody> . . .]
  [compute <name> [: <type>]
<anonymousFunction> . . .]
}

Name

collName String Required

Name of the collection. The collName must match the following regular expression but can’t be a single underscore or reserved word: [a-zA-Z_]+[a-zA-Z0-9_]*. A collName should be singular and PascalCased.

Properties

Parameter Type Required Description

<fieldName>

String

Document field names and definitions. See FSL collection schema: Field definitions.

migrations

String

See FSL collection schema: Migrations block.

history_days

Int

Number of days of document history to retain for all documents in the collection. If omitted or unset, defaults to 0 (retain no history). See Document history.

history_days also affects events available for event feeds and event streams. See event feeds and event streams.

document_ttls

Boolean | Null

If true, you can write to the ttl field of the collection’s documents.

If the collection schema contains field definitions, document_ttls defaults to false. Otherwise, document_ttls defaults to true.

document_ttls does not stop ttl-related deletions or affect ttl values set by the collection schema’s ttl_days field.

See Enable or disable ttl writes.

ttl_days

Int

Number of days that documents in the collection should be retained. See Set a default TTL.

index

String

See FSL collection schema: Index definitions.

unique

String

See FSL collection schema: Unique constraint definitions.

check

String

See FSL collection schema: Check constraint definitions.

compute

String

See FSL collection schema: Computed field definitions.

Annotations

aliasId String or Identifier

The optional @alias annotation defines a second identifier for the collection. The aliasId can be a String, "Foo", or an identifier, Foo.

Security and privileges

A user-defined role can assign privileges to a collection, including system collections.

Collection privileges grant access to a collection’s documents. A collection privilege can allow the create, delete, read, or write actions. read access includes the ability to call the collection’s indexes. An example FSL role schema:

role customer {
  // Grant read access to `Product` documents and indexes.
  privileges Product {
    read
  }
}

You can also grant access to system collections that store Fauna resources:

role manager {
  // Grant `create` and `read` access to the `Token` system collection.
  // Allows the role to create token secrets.
  privileges Token {
    create
    read
  }
}

To allow a role to create, delete, or manage user-defined collections themselves, grant access to the Collection system collection:

role manager {
  // Grant full access to the `Collection` system collection.
  // Allows the role to create, delete, read, and update
  // user-defined collections.
  privileges Collection {
    create
    delete
    read
    write
  }
}

Built-in roles also have collection privileges. See built-in roles.

Examples

collection Order {
  customer: Ref<Customer>
  status: "cart" | "processing" | "shipped" | "delivered"
  createdAt: Time

  compute items: Set<OrderItem> = (order => OrderItem.byOrder(order))
  compute total: Number = (order => order.items.fold(0, (sum, orderItem) => {
    if (orderItem.product != null) {
      sum + orderItem.product.price * orderItem.quantity
    } else {
      sum
    }
  }))
  payment: { *: Any }

  check oneOrderInCart (order => {
    Order.byCustomerAndStatus(order.customer, "cart").count() <= 1
  })

  index byCustomer {
    terms [.customer]
    values [desc(.createdAt), .status]
  }

  index byCustomerAndStatus {
    terms [.customer, .status]
  }
}

See also

FSL collection schema: Field definitions
FSL collection schema: Migrations block
FSL collection schema: Index definitions
FSL collection schema: Unique constraint definitions
FSL collection schema: Check constraint definitions
FSL collection schema: Computed field definitions

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!