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. Defaults to 0 (retain no history). See Document history.

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.

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) => {
    let orderItem: Any = 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!