# FSL reference

| Learn: Schema |
| --- | --- | --- |

This guide covers Fauna Schema Language (FSL) syntax and API. For specific FSL schema definitions, see:

*   [FSL access provider schema](access-provider/)
    
*   [FSL collection schema](collection/)
    
*   [FSL function schema](function/)
    
*   [FSL role schema](role/)
    

## [](#comments)Comments

FSL supports single-line and block comments as described in the FQL [comments](../fql/lexical/#comments) section of the language reference.

## [](#property)Property definition

Property definition syntax has one of the following forms:

| Syntax | Description |
| --- | --- | --- | --- |
| <property> <value> | Sets the property value for the item. |
| <property> <reference> | Relationship between the enclosing schema item and the referenced item, indicating existence. |
| <property> <reference> { <configuration> } | Relationship between the enclosing schema item and the referenced item, indicating existence and given a value. |

Properties can be unique for a schema item or can be repeated.

## [](#cross-reference)Cross-reference

An FSL schema can reference another schema by name. For example, a role schema can reference a collection by name:

```fsl
// Schema for the `Customer` collection.
collection Customer { ... }

...

// Schema for the `customer` role.
role customer {
  // The role references the above `Customer` collection.
  privileges Customer {
    read
  }
}
```

# FSL access provider schema

| Learn: Access providers |
| --- | --- | --- |

An FSL access provider schema defines an [access provider](../../../learn/security/access-providers/). An access provider registers an external identity provider (IdP), such as Auth0, in your Fauna database.

```fsl
access provider someIssuer {
  issuer "https://example.com/"
  jwks_uri "https://example.com/.well-known/jwks.json"

  role customer
}
```

Once [set up](../../../learn/security/access-providers/#config), the IdP can issue JSON Web Tokens (JWTs) that act as Fauna [authentication secrets](../../../learn/security/authentication/#secrets). This lets your application’s end users use the IdP for authentication.

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each access provider schema as an FQL document in the [`AccessProvider`](../../fql-api/accessprovider/) system collection.

## [](#fsl-syntax)FSL syntax

```fsl-sig
access provider <accessProvider> {
  issuer "<issuer>"
  jwks_uri "<jwksUri>"
  [role <role> [{
    predicate <predicateFunction>
  }] . . .]
}
```

## [](#name)Name

_access provider_ **Required**

Unique name for the access provider in the database.

Must begin with a letter. Can only include letters, numbers, and underscores.

## [](#properties)Properties

| Property | Required | Description |
| --- | --- | --- | --- | --- |
| issuer | true | Issuer for the IdP’s JWTs. Must match the iss claim in JWTs issued by the IdP.The issuer URL. This tells Fauna which IdP is permitted to send a JWT to authorize a query to be executed. |
| jwks_uri | true | URI that points to public JSON web key sets (JWKS) for JWTs issued by the IdP. Fauna uses the keys to verify each JWT’s signature. |
| role |  | User-defined role assigned to JWTs issued by the IdP. Can’t be a built-in role.An access provider can have multiple role properties.Each role property can include a predicate function. If present, JWTs are only assigned the role if the predicate evaluates to true.The predicate function is passed one argument: an object containing the JWT’s payload. The predicate function does not support shorthand syntax. |

## [](#examples)Examples

```fsl
access provider someIssuer {
  issuer "https://example.com/"
  jwks_uri "https://example.com/.well-known/jwks.json"

  role customer
  role manager {
    predicate (jwt => jwt!.scope.includes("manager"))
  }
}
```

# FSL collection schema

| Learn: Schema |
| --- | --- | --- |

An FSL collection schema defines the structure and behavior of a user-defined [collection](../../../learn/data-model/collections/) and its [documents](../../../learn/data-model/documents/).

```fsl
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:

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each collection schema as an FQL document in the [`Collection`](../../fql-api/collection/) system collection.

## [](#fsl-syntax)FSL syntax

```fsl-sig
[@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)Name

_collName_ _[String](../../fql/types/#string)_ **Required**

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

## [](#properties)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)Annotations

_aliasId_ _[String](../../fql/types/#string)_ or _Identifier_

The optional `@alias` annotation defines a second identifier for the collection. The _aliasId_ can be a [String](../../fql/types/#string), `"Foo"`, or an identifier, `Foo`.

## [](#examples)Examples

```fsl
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)See also

[FSL collection schema: Field definitions](../field-definitions/)  
[FSL collection schema: Migrations block](../migrations-block/)  
[FSL collection schema: Index definitions](../indexes/)  
[FSL collection schema: Unique constraint definitions](../unique/)  
[FSL collection schema: Check constraint definitions](../check/)  
[FSL collection schema: Computed field definitions](../computed/)

# FSL collection schema: Check constraint definitions

| Learn: Check constraints |
| --- | --- | --- |

A check constraint ensures a document field’s values meet a pre-defined rule.

You write the rule as a read-only FQL [predicate](../../fql/functions/#predicates). Fauna only allows document writes if the predicate evaluates to `true`. For example, you can check that field values are in an allowed range.

You define check constraints as part of an FSL [collection schema](../collection/):

```fsl
collection Product {
  ...
  // Check constraint. `Product` document writes are
  // only allowed if the `stock` field value is zero or greater.
  check stockIsValid (product => product.stock >= 0)
  ...
}
```

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each collection schema as an FQL document in the [`Collection`](../../fql-api/collection/) system collection. The `Collection` document’s `constraints` field contains FQL versions of the collection’s check constraint definitions.

## [](#fsl-syntax)FSL syntax

```fsl-sig
check <constraintName> (predicateBody: (<doc>: Document) => Boolean | Null)
```

## [](#properties)Properties

| Parameter | Type | Required | Description |
| --- | --- | --- | --- | --- | --- |
| constraintName | String | true | Check constraint predicate name, which must be unique for the collection.The constraintName identifies the constraint in error messages. |
| predicateBody | Function | true | An anonymous, read-only FQL function that evaluates to true, false, or null. If false or null, Fauna rejects the write. Accepts shorthand syntax.The function is passed one argument: an object containing the document to write.The function runs using the built-in server role’s privileges. |

## [](#discussion)Discussion

Check constraints can read, call UDFs, and use computed fields but can’t write. A constraint that tries to write results in an evaluation error.

Multiple check constraints can be defined for the collection and a check constraint can evaluate multiple document fields, or multiple values or ranges for a field..

When a document is [created](../../fql-api/collection/instance-create/), [updated](../../fql-api/document/update/), or [replaced](../../fql-api/document/replace/), all defined check constraints are evaluated by applying the check constraint, which can have four possible outcomes:

*   The predicate returns true. The write to the document is allowed.
    
*   The predicate returns false or null. The query, including the write to the document, fails.
    
*   The predicate returns a non-boolean non-null value. The query, including the write to the document, fails.
    
*   The predicate fails to evaluate, possibly caused by divide-by-zero, stack overflow, timeout errors, or `abort()` is called. The query, including the write to the document, fails. If a check constraint is failed by calling abort, the argument to abort is returned as if the query were failed by calling abort in the query.
    

Check constraints aren’t applied retroactively to existing data in the database.

Check constraints should be defined defensively to handle the conditions that the field might not exist or might have a different type.

The check constraint is evaluated on the document version when the document is written, not what currently exists. When a check constraint runs on an update operation, it operates on the document with the update applied. When a check constraint runs on a replace operation, it operates on the version that is replacing the original.

Check constraints aren’t evaluated on delete queries.

### [](#check-constraint-errors)Check constraint errors

When a query fails a check constraint, the Core HTTP API’s [Query endpoint](../../http/reference/core-api/#operation/query) rejects the query and returns an error with the `constraint_failure` [error code](../../http/reference/errors/).

The error includes a `constraint_failures` array. The array contains information about the constraints that triggered the error:

```json
{
  "error": {
    "code": "constraint_failure",
    "message": "Failed to create document in collection `Product`.",
    "constraint_failures": [
      {
        "paths": [],
        "message": "Document failed check constraint `stockIsValid`"
      }
    ]
  },
  ...
}
```

Fauna’s client drivers include classes for constraint errors:

*   JavaScript driver: [`ConstraintFailureError`](https://fauna.github.io/fauna-js/latest/classes/ConstraintFailureError.html)
    
*   Python driver: [`FaunaError.constraint_failures`](https://fauna.github.io/fauna-python/latest/api/fauna/errors/errors.html#FaunaError.constraint_failures)
    
*   Go driver: [`ErrConstraintFailure`](https://pkg.go.dev/github.com/fauna/fauna-go/v2#ErrConstraintFailure)
    
*   .NET/C# driver: [`ConstraintFailures`](https://fauna.github.io/fauna-dotnet/latest/class_fauna_1_1_exceptions_1_1_constraint_failure.html)
    
*   JVM driver: [`ConstraintFailureException`](https://fauna.github.io/fauna-jvm/latest/com/fauna/exception/ConstraintFailureException.html)
    

### [](#check-constraint-behavior)Check constraint behavior

Check constraints are evaluated immediately after a write is registered in the query, before the write is committed. All check constraints for the collection are automatically evaluated on the new document state.

If any check constraint fails, the entire query transaction is aborted — no part of the query after the write is evaluated, and no changes from before the write take effect.

Check constraints evaluate against the pending document state. For example, if a check constraint includes an expression such as `Collection.byField(doc.foo).count()`, the query includes the document being written in its results.

## [](#examples)Examples

### [](#basic-example)Basic example

1.  Given a `hasFunds` check constraint for the `Customer` collection, which validates that a customer balance is greater than or equal to zero, and a customer who currently has a positive balance:
    
    ```fsl
    collection Customer {
      ...
      check hasFunds((doc) => doc.balance >= 0)
      ...
    }
    ```
    
    And given the following `Customer` collection document:
    
    ```
    {
      id: "388093102421704737",
      coll: Customer,
      ts: Time("2099-06-25T12:14:29.440Z"),
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com",
      ...,
      balance: 21
    ```
    
2.  Verify check constraint validation by trying to set the balance to less than zero:
    
    ```fql
    Customer.byId("111")!.update({ balance: -50 })
    ```
    
    ```
    constraint_failure: Failed to update document with id 111 in collection `Customer`.
    
    error: Failed to update document with id 111 in collection `Customer`.
    constraint failures:
      Document failed check constraint `hasFunds`
    at *query*:1:29
      |
    1 | Customer.byId("111")!.update({ balance: -50 })
      |                             ^^^^^^^^^^^^^^^^^^
      |
    ```
    
    The `hasFunds` check constraint catches the constraint violation. Notice that the error message includes the name of the check constraint predicate.
    

### [](#shorthand-syntax)Shorthand syntax

You can use [shorthand syntax](../../fql/functions/#shorthand-syntax) in a check constraint’s predicate function. For example:

```fsl
collection Customer {
  ...
  check isAdult(.age >= 18)
  ...
}
```

Or:

```fsl
collection Customer {
  ...
  check isAdult(doc => doc.age >= 18)
  ...
}
```

Is equivalent to:

```fsl
collection Customer {
  ...
  check isAdult((doc) => doc.age >= 18)
  ...
}
```

## [](#see-also)See also

[FSL collection schema](../collection/)

# FSL collection schema: Computed field definitions

| Learn: Computed fields |
| --- | --- | --- |

A computed field dynamically derives the value of a field using an anonymous, read-only function. The function is evaluated when a document is read. The function is passed one argument: the document to read.

The function returns the computed field’s value. Fauna doesn’t persistently store a computed field’s value. The value is computed on each read.

You define computed fields as part of an FSL [collection schema](../collection/). Computed field definitions are part of a collection’s [document type definition](../../../learn/schema/#document-type-definitions).

```fsl
collection Customer {
  ...
  // 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)
  ...
}
```

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each collection schema as an FQL document in the [`Collection`](../../fql-api/collection/) system collection. The `Collection` document’s `computed_fields` field contains FQL versions of the collection’s computed field definitions.

## [](#fsl-syntax)FSL syntax

```fsl-sig
compute <fieldName>[: <type>] <functionBody>
```

## [](#properties)Properties

| Parameter | Type | Required | Description |
| --- | --- | --- | --- | --- | --- |
| fieldName | String | true | Computed field name. The fieldName can be the same as a persisted field name. An optional type can be declared for the function. |
| functionBody | Function | true | The function body is an anonymous function that is evaluated when a document is read. An optional type can also be provided as part of the function signature.The anonymous function takes a source Document as input, operates on the document values, and returns a computed value.Computed fields with defined anonymous functions can transform existing fields, provide convenient access to complex relations, and index over derived data.The anonymous function return value is the value of the computed field. |

## [](#discussion)Discussion

The _computed\_fields_ field defines document functions that evaluate a field when the document is read using the provided anonymous function. The anonymous function can:

*   read
    
*   cause other computed fields to be evaluated
    
*   call user-defined functions (UDFs).
    

A computed field anonymous function has the restriction that it can’t write to a document. Trying to write to a _computed\_fields_ field returns an error.

Computed fields take precedence over persisted fields, and persisted fields can be referenced as children of the `.data` field.

### [](#computed-fields-and-indexes)Computed fields and indexes

Computed fields can be indexed and when indexed, the value that is indexed is the value of the computed field computed at the time the index is built. Because of this, indexed computed fields have more restrictions to prevent changes to the value of the field that are hard to detect. These restrictions are enforced by the type system when changes are made to computed fields or index definitions, preventing such changes. They are also enforced at runtime when they cause evaluation of a computed field to fail during the index build, which results in a `null` term or value.

The following actions cause an index to be rebuilt:

*   Changes to the definition of an indexed computed field.
    
*   Removing the computed field. The new index treats the computed field like a persisted field.
    

When a new index entry is added or an existing entry is updated, the anonymous function computes the value at that time instead of every time the value is needed.

Computed fields can be indexed and used as unique constraints subject to the following restrictions, which cause the computed field evaluation to fail at index time because of an invalid index definition:

*   Indexed computed fields can’t use computed fields in the body.
    
*   Indexed computed fields can’t call UDFs.
    
*   Indexed computed fields can’t read.
    

Failing evaluation causes the document to emit a `null` term or value for the computed field.

The following table summarizes computed field index behavior:

| Problem | Does the entry exist? |
| --- | --- | --- | --- |
| One or more values error, but terms are correct. Termless indexes count are always correct. | Yes |
| At least one term doesn’t error. | YesTerms that error are null. |
| All terms error. | No |

If an indexed computed field depends on another computed field, changing the definition of the first computed field silently changes the definition of the second.

Adding, updating, renaming, or removing non-indexed computed fields is safe. Changing an indexed computed field definition triggers a rebuild of its covering indexes.

### [](#computed-functions-and-types)Computed functions and types

Given the following schema, types are inferred on the index functions for the collection. For example:

```fsl
collection Customer {
  ...
  compute fullName: String = doc => "#{doc.firstName} #{doc.lastName}"

  index byFullName {
    terms [.fullName]
  }
  ...
}
```

In a query, the type in the index function is inferred, and the following query results in a type error:

```fsl
Customer.byFullName(3) // Returns a type error
```

## [](#examples)Examples

### [](#basic-example)Basic example

The following `Product` collection schema contains:

*   A computed `status` field definition
    
*   A `byStatus()` index definition that indexes `status` as a term
    

```fsl
collection Customer {
  ...
  // Defines `status` as a computed document field.
  // If the user's `points` field value is above `100`,
  // `status` is `gold`. Otherwise, `status` is `standard`.
  compute status: String = (
    doc => (
        if( doc.points > 100 ) {
            "gold"
        } else {
            "standard"
        }
    )
  )

  // Defines the `byStatus()` index.
  // Use the index to get `Customer` documents by
  // `status` value.
  index byStatus {
    terms [.status ]
  }
  ...
}
```

The `Customer` collection contains the following document:

```
{
  id: "111",
  coll: Customer,
  ts: Time("2099-06-25T12:50:43.722Z"),
  name: "Alice Appleseed",
  email: "alice.appleseed@example.com",
  status: "gold",
  ...
  points: 120
}
```

Call the `byStatus()` index in a query:

```fql
Customer.byStatus( "gold")
```

The results include the document based on its `status` field value. Fauna computes the `status` field value at query time:

```
{
  data: [
    {
      id: "111",
      coll: Customer,
      ts: Time("2099-06-25T12:50:43.722Z"),
      status: "gold",
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com",
      ...
      points: 120
    },
    ...
  ]
}
```

### [](#use-subqueries-in-a-computed-field)Use subqueries in a computed field

You can use subqueries in a computed field definition:

```fsl
collection Customer {
  ...
  // Defines `orders` as a computed document field. `order`
  // contains an Array of the first five `Order` collection
  // documents returned by a `byCustomer()` index call. The
  // call passes the document as its only argument.
  compute orders:Array<Order> = (
    doc => { Order.byCustomer( doc ).take(5).toArray() }
  )
  ...
}
```

This approach is a useful alternative to directly embedding data from other documents into a field. However, you can’t index the computed field because it performs a read outside of the `doc` argument.

### [](#define-a-computed-field-that-validates-a-range-of-values)Define a computed field that validates a range of values

```fsl
compute isAdult = (
  doc => (doc.age > 18 && doc.age <= 120)
)
```

### [](#assign-a-type-to-a-computed-field)Assign a type to a computed field

Assign a [String](../../fql/types/#string) type to a computed field:

```fsl
collection Customer {
  ...
  compute status: String = doc => {
    if (doc.points > 100) {
      "gold"
    } else {
      "standard"
    }
  }
  ...
}
```

If the optional type is not provided, the type checker assigns the enumeration of the possible computed values, which are `gold` and `standard`.

### [](#use-a-computed-field-as-an-index-term)Use a computed field as an index term

Convert a user name to uppercase and get the first letter of the name to use as a computed field for indexing on the first letter of user names:

```fsl
collection Customer {
  ...
  compute nameInitial = (
    doc => { doc.firstName.toUpperCase().slice(0, 1) }
  )
  ...
}
```

### [](#define-a-check-constraint-on-a-computed-field)Define a check constraint on a computed field

Validate that the result of the computed field is `gold` or `standard`:

```fsl
collection Customer {
  ...
  compute status: String = (
    doc => (
        if( doc.points > 100 ) {
            "gold"
        } else {
            "standard"
        }
    )
  )

  check validStatus (.status == "gold" || .status == "standard")
  ...
}
```

## [](#limitations)Limitations

Runtime errors in computed fields that are indexed aren’t reported. Computed fields that result in runtime errors, including divide by zero, return `null`. If indexed, these computed fields are excluded from the index update.

## [](#see-also)See also

[FSL collection schema](../collection/)

# FSL collection schema: Field definitions

| Learn: Field definitions |
| --- | --- | --- |

Field definitions define fields for a collection’s documents.

You define [field definitions](../../../learn/schema/#field-definitions) as part of an FSL [collection schema](../collection/). Field definitions are part of a collection’s [document type definition](../../../learn/schema/#document-type-definitions).

```fsl
collection Order {
  // Field definitions.
  // Define the structure of the collection's documents.
  description: String? // Equivalent to `status: String | Null`
  customer: Ref<Customer>
  status: "cart" | "processing" | "shipped" | "delivered"
  createdAt: Time = Time.now()
  ...
}
```

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each collection schema as an FQL document in the [`Collection`](../../fql-api/collection/) system collection. The `Collection` document’s `fields` field contains FQL versions of the collection’s field definitions.

## [](#fsl-syntax)FSL syntax

```fsl-sig
<fieldName>: <types>[ = <defaultValue>]
```

## [](#name)Name

_fieldName_ _[String](../../fql/types/#string)_ **Required**

Document field name. A top-level field name must be a valid [identifier](../../fql/variables/#identifier).

Use a top-level wildcard (`*`) constraint to specify accepted [data types](../../fql/types/) for ad hoc fields. See [Wildcard constraints](#wildcard-constraints).

## [](#properties)Properties

| Property | Type | Required | Description |
| --- | --- | --- | --- | --- | --- |
| <types> | String | Yes | Accepted data types for the field. Separate multiple types by |.Types must be persistable. Use Any to accept any persistable value.Use Ref<CollectionName> to accept a document reference.Document references for the following system collections are supported:CredentialKeyTokenReferences to named system collection documents are not supported.Use the Union type to enumerate accepted field values. See Enumerated field values.The ? (nullable) type annotation indicates the field accepts Null values. ? is equivalent to | Null.Fields that accept Null are not guaranteed to exist in every document of the collection. |
| <defaultValue> | String |  | Default field value. Used when the field is missing during document creation or replacement.Can be an FQL expression. The expression can have no effect other than to:Generate an ID, such as calling ID() or newId(). You must then cast the ID to a String using toString().Get the current Date or Time, such as calling Date.today() or Time.now().Fauna evaluates the expression at write time.You can use a document reference as a default value.Document references for the following system collections are supported:CredentialKeyTokenReferences to named system collection documents are not supported. See Default to a document reference.You can’t use another field’s value as a default value.The default value is not applied if an explicit null value is provided or during document updates. |

## [](#wildcard-constraints)Wildcard constraints

When you add field definitions to a collection, the collection’s documents can only contain the defined fields. To accept arbitrary ad hoc fields, add a wildcard (`*`) constraint:

```fsl
collection Order {
  status: String?

  // Wildcard constraint.
  // Allows arbitrary ad hoc fields.
  *: Any
}
```

A wildcard constraint is part of a collection’s [document type definition](../../../learn/schema/#document-type-definitions). You can’t specify a default value for a wildcard constraint.

A collection can only have one top-level wildcard constraint. If present, the top-level wildcard constraint’s definition must be `*: Any`.

### [](#schemaless-by-default)Schemaless by default

If a collection has no field definitions, it implicitly accepts ad hoc fields of any type. This is equivalent to:

```fsl
collection Order {
  // Contains no field definitions
  *: Any
}
```

This means the collection is schemaless. The collection’s documents can contain any field.

### [](#permissive-document-type)Permissive document type

If a collection has both field definitions and a wildcard constraint, it has a permissive document type. The collection’s documents can contain ad hoc fields. However, fields must conform to the structure of their definitions.

```fsl
collection Order {
  // Contains field definitions and a wildcard constraint
  status: String?
  *: Any
}
```

### [](#strict-doc-type)Strict document type

If a collection has field definitions but doesn’t have a wildcard constraint, it does not accept documents with ad hoc fields. This is called a strict document type.

```fsl
collection Order {
  // Contains no wildcard constraint
  status: String?
}
```

### [](#nested-wildcard)Nested wildcard constraints

You can include a wildcard constraint in an [object field definition](#nested) to accept ad hoc fields in the object:

```fsl
collection Product {
  metadata: {
    name: String?
    // The `metadata` object can contain ad hoc fields
    // of any type.
    *: Any
  }
}
```

You can restrict the accepted data types of ad hoc fields in the object:

```fsl
collection Product {
  metadata: {
    name: String?
    // Only accept ad hoc fields with `String` or `Int` values.
    *: String | Int
  }
}
```

#### [](#nested-field-migrations-with-wildcard-constraints)Nested field migrations with wildcard constraints

You can’t [run migrations](../migrations-block/) on a nested field that has a neighboring wildcard constraint:

```fsl
collection Product {
  metadata: {
    // The `metadata` object contains a wildcard constraint.
    // You can't run migrations on `name` or other
    // neighboring fields in `metadata`.
    name: String?
    *: Any
  }
}
```

The `add_wilcard`, `remove_wildcard`, and `move_wildcard` [migration statements](../migrations-block/#migration-statements) only support top-level wildcard constraints, not nested wildcard constraints. These statements let you safely handle conflicts between ad hoc and defined fields.

For an example, see [Nested field migrations with wildcard constraints](../migrations-block/#wildcard-field-migrations).

## [](#ttls-default)Document TTLs default

The `document_ttls` field to controls whether you can write to the [`ttl`](../../../learn/doc-ttl/) field for collection documents.

If a collection schema contains field definitions, the schema’s [`document_ttls`](../../../learn/doc-ttl/#enable-disable-ttl-writes) field defaults to `false`. Otherwise, `document_ttls` defaults to true.

| See Enable or disable ttl writes |
| --- | --- | --- |

## [](#examples)Examples

### [](#arrays)Arrays

Use `Array<…​>` to accept [Array](../../fql/types/#array) values:

```fsl
collection Product {
  categories: Array<String>
}
```

To accept an object Array:

```fsl
collection Customer {
  addresses: Array<{
    street: String
    city: String
    state: String
    zipCode: String
  }>
}
```

You can’t [run migrations](../migrations-block/) on nested fields within an object Array. Otherwise, you define the object in the Array like an object field. See [Objects](#nested).

### [](#default-to-todays-date)Default to today’s date

Use [`Date.today()`](../../fql-api/date/today/) to set today’s date as a default value:

```fsl
collection Product {
  creationDate: Date = Date.today()
}
```

Fauna evaluates the expression at write time.

### [](#default-to-the-current-time)Default to the current time

Use [`Time.now()`](../../fql-api/time/now/) to set the current time as a default value:

```fsl
collection Product {
  creationTime: Time = Time.now()
}
```

Fauna evaluates the expression at write time.

### [](#default-to-a-unique-id)Default to a unique ID

Use [`newId()`](../../fql-api/globals/newid/) to use a unique [ID](../../fql/types/#id) as the default value. You must cast the ID to a [String](../../fql/types/#string) using [`toString()`](../../fql-api/string/tostring/):

```fsl
collection Product {
  productId: String = newId().toString()
}
```

If used, Fauna generates a unique ID value for each document.

### [](#doc-ref-default)Default to a document reference

You can use a [document reference](../../../learn/data-model/relationships/) as a default value:

```fsl
collection Product {
  // `category` defaults to a `Category` document reference
  // Replace `400684606016192545` with a `Category` document ID.
  category: Ref<Category> = Category("400684606016192545")
}
```

Fauna doesn’t guarantee the document exists. You can’t fetch the document using an FQL expression.

Document references for the following [system collections](../../../learn/data-model/collections/#system-coll) are supported:

*   [`Credential`](../../fql-api/credential/)
    
*   [`Key`](../../fql-api/key/)
    
*   [`Token`](../../fql-api/token/)
    

References to [named system collection](../../../learn/data-model/collections/#named-coll) documents are not supported.

### [](#document-relationships)Document relationships

Use `Ref<CollectionName>` to accept a [document reference](../../../learn/data-model/relationships/) as a data type:

```fsl
collection Product {
  // Accepts a reference to a `Category` collection
  // document or `null`.
  category: Ref<Category>?
}
```

Documents may contain references to documents that don’t exist. These are called dangling references.

You can’t delete a collection that’s referenced by a field definition. See [Drop a document reference field](../migrations-block/#drop-doc-ref).

Document references for the following [system collections](../../../learn/data-model/collections/#system-coll) are supported:

*   [`Credential`](../../fql-api/credential/)
    
*   [`Key`](../../fql-api/key/)
    
*   [`Token`](../../fql-api/token/)
    

References to [named system collection](../../../learn/data-model/collections/#named-coll) documents are not supported.

### [](#enumerated-field-values)Enumerated field values

To accept enumerated values:

```fsl
collection Customer {
  status: "silver" | "gold" | "platinum"?
}
```

### [](#nested)Objects

To define a field containing an object:

```fsl
collection Customer {
  // `address` is an object.
  address: {
    // `street` and the other fields are
    // nested fields in the `address` object.
    street: String
    city: String
    state: String
    postalCode: String
    country: String
  }
}
```

You can nest objects within other objects:

```fsl
collection Customer {
  address: {
    street: String
    city: String
    state: String
    postalCode: String
    country: {
      // `countryCode` is nested in the
      // `country` field. The `country`
      // field is nested in the `address` field.
      countryCode:
    }
  }
}
```

#### [](#nested-delimiter)Delimit nested fields

You can use commas to optionally delimit an object’s nested fields:

```fsl
collection Customer {
  address: {
    street: String,
    city: String,
    state: String,
    postalCode: String,
    country: String
  }
}
```

#### [](#nested-field-names)Nested field names

A top-level field name must be a valid [identifier](../../fql/variables/#identifier). A nested field name can be any valid string, including an identifier:

```fsl
collection Product {
  // `metadata` is a top-level field name and must be an identifier.
  metadata: {
    // `internal description` is a nested field name.
    // The name contains a space and is not a valid
    // identifier.
    "internal description": String
  }
}
```

You can access non-identifier field names using [bracket notation](../../fql/dot-notation/#bracket-notation-field-accessor):

```fsl
// Create a `Product` document using the previous schema.
let product = Product.create({
  metadata: {
    "internal description": "Fresh key limes"
  }
})

// Access the document's nested `internal description`
// field using bracket notation.
product.metadata["internal description"]
```

#### [](#nested-defaults)Defaults for nested fields

You can provide default values for fields in an object:

```fsl
collection Customer {
  address: {
    // If `address.street` is not provided,
    // use a default value of "unknown street".
    street: String = "unknown street"
    // If `address.city` is not provided,
    // use a default value of "unknown city".
    city: String = "unknown city"
    state: String
    postalCode: String
    country: String
  }
}
```

#### [](#obj-defaults)Default for an entire object

You can provide a default object for an object field. The default is used only if the entire object is omitted:

```fsl
collection Customer {
  // If no `address` object is provided, use the default object.
  address: {
    street: String
    city: String
    state: String?
    postalCode: String?
    country: String?
  } = {
    // The default object:
    street: "unknown street",
    city: "unknown city"
  }
}
```

You can’t specify both a default object and [nested field defaults](#nested-defaults).

## [](#see-also)See also

[FSL collection schema](../collection/)  
[FSL collection schema: Migrations block](../migrations-block/)

# FSL collection schema: Index definitions

| See Indexes |
| --- | --- | --- |

An index stores, or covers, specific document field values for quick retrieval. Using indexes can significantly improve query performance and reduce costs, especially for large datasets.

You define indexes as part of an FSL [collection schema](../collection/).

```fsl
collection Order {
  ...
  // Index definition.
  // You use indexes to filter and sort documents
  // in a performant way.
  index byCustomer {
    terms [.customer]
    values [desc(.createdAt), desc(mva(.statuses))]
  }
  ...
}
```

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

When you submit a new or updated collection schema, Fauna may need to build (or rebuild) the collection’s indexes. See [Index builds](../../../learn/data-model/indexes/#builds).

Fauna stores each collection schema as an FQL document in the [`Collection`](../../fql-api/collection/) system collection. The `Collection` document’s `indexes` field contains FQL versions of the collection’s index definitions.

## [](#fsl-syntax)FSL syntax

```fsl-sig
index <indexName> {
  [terms [<term> . . .]]
  [values [<value> . . .]]
}
```

## [](#name)Name

_indexName_ _[String](../../fql/types/#string)_ **Required**

Index name. Must be unique within the collection.

## [](#properties)Properties

| Property | Type | Required | Description |
| --- | --- | --- | --- | --- | --- |
| terms | Array of field accessors | Yes, if values is not defined. | Fields used for exact match searches.Supports dot notation and bracket notation. You can only index persistable field values.Use mva() to index an Array field’s values.You can only index persistable field values. |
| values | Array of field accessors | Yes, if terms is not defined. | Fields used for sorting and range searches.Supports dot notation and bracket notation. You can only index persistable field values.Use mva() to index an Array field’s values.Use asc() or desc() to sort results in respective ascending or descending order. Defaults to asc (ascending).You can only index persistable field values. |

### [](#index-document-relationships)Index document relationships

When you [index](../../../learn/data-model/indexes/) a field that contains a document, you index a document reference. The reference consists of the document’s collection and document ID:

```fsl
collection Product {
  ...
  // The `category` field contains a reference to
  // a `Category` collection document.
  category: Ref<Category>
  ...
  // Indexes the `category` field as an index term.
  // The index stores `Category` document references.
  // Example reference: Category("123")
  index byCategory {
    terms [.category]
  }
}
```

An index can’t store a referenced document’s fields. An index also can’t store a computed field that references another document. See [Patterns to avoid](../../../learn/data-model/relationships/#patterns-to-avoid).

## [](#missing-or-null-values)Missing or null values

*   **Terms:** If an index definition contains terms, Fauna doesn’t index a document if all its index terms are missing or otherwise evaluate to null. This applies even if the document contains index values.
    
*   **Values:** If an index definition contains only values, Fauna indexes all documents in the collection, regardless of whether the document’s index values are missing or otherwise null.
    

## [](#examples)Examples

### [](#basic-example)Basic example

You define an index in an FSL [collection schema](../collection/):

```fsl
collection Product {
  ...
  index byName {
    terms [.name]
  }
  ...
}
```

Once the index is [built](../../../learn/data-model/indexes/#builds), you call it as a method on the collection:

```fql
// Call the `byName()` index to fet `Product` collection
// documents with a `name` value of `limes`. Values must
// match exactly.
Product.byName("limes")
```

The call returns a Set of matching collection documents.

### [](#use-index-terms-for-exact-match-searches)Use index terms for exact match searches

You can use index terms to run exact match searches on document field values.

The following index definition includes `name` as an index term:

```fsl
collection Product {
  ...

  index byName {
    terms [.name]
  }

  ...
}
```

When you call the index, you must pass an argument for each term in the index definition.

```fql
// Get products named "limes"
Product.byName("limes")
```

The call returns a Set of `Product` collection documents with a `name` of `limes`.

### [](#pass-multiple-index-terms)Pass multiple index terms

The following index definition includes two index terms:

```fsl
collection Customer {
  ...

  index byName {
    terms [.firstName, .lastName]
  }
}
```

In an index call, use a comma to separate term arguments. Provide arguments in the same field order used in the index definition.

```fql
// Get customers named "Alice Appleseed"
Customer.byName("Alice", "Appleseed")
```

The call returns a Set of matching collection documents.

### [](#use-index-values-for-sorting-and-range-searches)Use index values for sorting and range searches

You can use index values to sort a collection’s documents. You can also use index values for range searches.

### [](#sort-documents)Sort documents

The following index definition includes several index values:

```fsl
collection Product {
  ...

  index sortedByPriceLowToHigh {
    values [.price, .name, .description]
  }
}
```

Call the `sortedByPriceLowToHigh()` index with no arguments to return `Product` documents sorted by:

*   Ascending `price`, then …​
    
*   Ascending `name`, then …​
    
*   Ascending `description`, then …​
    
*   Ascending `id` (default)
    

```fql
// Get products by ascending price, name, and description
Product.sortedByPriceLowToHigh()
```

### [](#sort-in-descending-order)Sort in descending order

By default, index values sort results in ascending order. To use descending order, use `desc()` in the index definition:

```fsl
collection Product {
  ...

  index sortedByPriceHighToLow {
    values [desc(.price), .name, .description]
  }

  ...
}
```

Call the index with no arguments to return `Product` documents sorted by:

*   Descending `price`, then …​
    
*   Ascending `name`, then …​
    
*   Ascending `description`, then …​
    
*   Ascending `id` (default)
    

```fql
// Get products by descending price,
// ascending name, and ascending description
Product.sortedByPriceHighToLow()
```

### [](#run-a-range-search)Run a range search

You can also use index values for range searches.

The following index definition includes several index values:

```fsl
collection Product {
  ...

  index sortedByPriceLowToHigh {
    values [.price, .name, .description]
  }
}
```

The index specifies `price` as its first value. The following query passes an argument to run a range search on `price`:

```fql
// Get products with a price between
// 20_00 (inclusive) and 30_00 (inclusive)
Product.sortedByPriceLowToHigh({ from: 20_00, to: 30_00 })
```

If an index value uses descending order, pass the higher value in `from`:

```fql
// Get products with a price between
// 20_00 (inclusive) and 30_00 (inclusive) in desc order
Product.sortedByPriceHighToLow({ from: 30_00, to: 20_00 })
```

Omit `from` or `to` to run unbounded range searches:

```fql
// Get products with a price greater than or equal to 20_00
Product.sortedByPriceLowToHigh({ from: 20_00 })

// Get products with a price less than or equal to 30_00
Product.sortedByPriceLowToHigh({ to: 30_00 })
```

### [](#pass-multiple-index-values)Pass multiple index values

Use an Array to pass multiple value arguments. Pass the arguments in the same field order used in the index definition.

```fql
Product.sortedByPriceLowToHigh({ from: [ 20_00, "l" ], to: [ 30_00, "z" ] })
```

The index returns any document that matches the first value in the `from` and `to` Arrays. If matching documents have the same values, they are compared against the next Array element value, and so on.

For example, the `Product` collection’s `sortedByPriceLowToHigh()` index covers the `price` and `name` fields as index values. The `Product` collection contains two documents:

| Document | price | name |
| --- | --- | --- | --- | --- |
| Doc1 | 4_99 | pizza |
| Doc2 | 6_98 | cups |

The following query returns both Doc1 and Doc2, in addition to other matching documents:

```fql
Product.sortedByPriceLowToHigh({ from: [4_99, "p"] })
```

The first value (`4_99` and `6_98`) of each document matches the first value (`4_99`) of the `from` Array.

Later, you update the document values to:

| Document | price | name |
| --- | --- | --- | --- | --- |
| Doc1 | 4_99 | pizza |
| Doc2 | 4_99 | cups |

The following query no longer returns Doc2:

```fql
Product.sortedByPriceLowToHigh({ from: [4_99, "p"] })
```

Although the first value (`4_99`) in both documents matches the first value in the `from` Array, the second value (`cups`) in Doc2 doesn’t match the second value (`p`) of the `from` Array.

### [](#run-a-range-search-on-id)Run a range search on `id`

All indexes implicitly include an ascending document `id` as the index’s last value.

If you intend to run range searches on `id`, we recommend you explicitly include an ascending `id` as the last index value in the index definition, even if you have an otherwise identical index.

For example, the following `sortByStock()` and `sortByStockandId()` indexes have the same values:

```fsl
collection Product {
  ...

  index sortByStock {
    values [.stock]
  }

  index sortByStockandId {
    values [.stock, .id]
  }

  ...
}
```

Although it’s not explicitly listed, `sortByStock()` implicitly includes an ascending `id` as its last value.

To reduce your costs, Fauna only builds the `sortByStock()` index. When a query calls the `sortByStockandId()` index, Fauna uses the `sortByStock()` index behind the scenes. `sortByStockandId()` only acts as a [virtual index](../../../learn/data-model/indexes/#virtual-indexes) and isn’t materialized.

### [](#pass-terms-and-values)Pass terms and values

If an index has both terms and values, you can run an exact match search on documents in a provided range.

The following index definition includes `name` as an index term and `stock` as an index value:

```fsl
collection Product {
  ...

  index byName {
    terms [.name]
    values [.stock]
  }

  ...
}
```

When you call the index, you must provide a term and can specify an optional range:

```fql
// Get products named "donkeypinata"
// with a stock between 10 (inclusive) and 50 (inclusive)
Product.byName("donkey pinata", { from: 10, to: 50 })
```

### [](#index-an-array-field)Index an Array field

By default, Fauna assumes index term and value field contain scalar values. Use `mva()` to index an [Array](../../fql/types/#array) field’s values:

```fsl
collection Product {
  ...
  index byCategory {
    // `categories` is an Array field.
    terms [mva(.categories)]
  }

  index sortedByCategory {
    // `categories` is an Array field.
    values [mva(.categories)]
    // You can combine `mva()` with
    // `desc()` and `asc()`. Ex:
    // values [desc(mva(.categories))]
  }
  ...
}
```

`mva()` only works on the last item in the provided field accessor. For more complex nested Arrays, such as an object Array, use a [computed field](../computed/):

```fsl
collection Order {
  ...
  // `Order` collection documents
  // have the following structure:
  // {
  //   customer: Customer("<CUSTOMER_DOC_ID>"),
  //   items: [
  //     {
  //       product: Product("PRODUCT_DOC_ID"),
  //       quantity: 10
  //     },
  //     ...
  //   ],
  //   ...
  // }

  // Defines the `quantities` computed field.
  // The field uses `map()` to extract `price` values
  // from the `cart` Array's object to a flat Array.
  compute quantities = (.items.map(item => item.quantity))

    // Uses `mva()` to index the computed `quantities` field.
  index byQuantities {
    terms [mva(.quantities)]
  }
  ...
}
```

### [](#covered-queries)Covered queries

If you [project](../../fql/projection/) or [map](../../fql-api/set/map/#project) an index’s covered term or value fields, Fauna gets the field values from the index.

The following index definition includes several index values:

```fsl
collection Product {
  ...

  index sortedByPriceLowToHigh {
    values [.price, .name, .description]
  }
}
```

The following is a covered query:

```fql
// This is a covered query.
// `name`, `description`, and `price` are values
// in the `sortedByPriceLowToHigh()` index definition.
Product.sortedByPriceLowToHigh() {
  name,
  description,
  price
}
```

If the projection contains an uncovered field, Fauna must retrieve the field values from the documents. This is an uncovered query:

```fql
// This is an uncovered query.
// `stock` is not one of the terms or values
// in the `sortedByPriceLowToHigh()` index definition.
Product.sortedByPriceLowToHigh() {
  name,
  stock
}
```

Performance hint: `non_covered_document_read`

Uncovered queries emit a [performance hint](../../http/reference/query-summary/#perf), if enabled. For example:

```
performance_hint: non_covered_document_read - .stock is not covered by the Product.sortedByPriceLowToHigh index. See https://docs.fauna.com/performance_hint/non_covered_document_read.
at *query*:1:42
  |
1 | Product.sortedByPriceLowToHigh() { name, stock }
  |                                          ^^^^^
  |
```

Covered queries are typically faster and less expensive than uncovered queries, which require document reads. If you frequently run uncovered queries, consider adding the uncovered fields to the index definition’s [`values`](../../../learn/data-model/indexes/#sort-documents). For example:

```fsl
collection Product {
  ...
  // Adds the `stock` field as an index value.
  index sortedByPriceLowToHigh {
    values [.price, .name, .description, .stock]
  }
}
```

#### [](#no-projection-or-mapping)No projection or mapping

Index queries without a [projection](../../fql/projection/) or [mapping](../../fql-api/set/map/#project) are uncovered. Fauna must read each document returned in the Set. For example:

```fql
// This is an uncovered query.
// Queries without a projection or mapping
// require a document read.
Product.byName("limes")
```

Performance hint : `non_covered_document_read`

If [performance hints](../../http/reference/query-summary/#perf) are enabled, index queries without a projection or mapping emit a performance hint. For example:

```
performance_hint: non_covered_document_read - Full documents returned from Product.byName. See https://docs.fauna.com/performance_hint/non_covered_document_read.
at *query*:1:15
  |
1 | Product.byName("limes")
  |               ^^^^^^^^^
  |
```

If you frequently run such queries, consider adding the uncovered fields to the index definition’s [`values`](../../../learn/data-model/indexes/#sort-documents). For example:

```fsl
collection Product {
  ...

  index byName {
    terms [.name]
    values [.price, .stock, .description]
  }

  ...
}
```

Then use projection or mapping to only return the fields you need. Given the previous index definition, the following query is covered:

```fql
// This is a covered query.
// `price`, `stock`, and `description` are values
// in the `byName()` index definition.
Product.byName("limes") {
  price,
  stock,
  description
}
```

#### [](#filter-covered-values)Filter covered values

You can use [`set.where()`](../../fql-api/set/where/) to filter the results of an [index call](../../../learn/data-model/indexes/#call). If the [`set.where()`](../../fql-api/set/where/) predicate only accesses fields defined in the index definition’s `terms` and `values`, the query is [covered](../../../learn/data-model/indexes/#covered-queries).

For example, given the following index definition:

```fsl
collection Product {
  ...

  index byName {
    terms [.name]
    values [.price, .description]
  }

  ...
}
```

The following query is covered:

```fql
// Covered query.
// Calls the `byName()` index.
// Uses `where()` to filter the results of
// the index call. The predicates only
// access covered terms and values.
Product.byName("limes")
  .where(.description.includes("Conventional"))
  .where(.price < 500) {
    name,
    description,
    price
  }
```

The following query is uncovered:

```fql
Product.byName("limes")
  .where(.description.includes("Conventional"))
  // The `where()` predicate accesses the uncovered
  // `stock` field.
  .where(.stock < 100)
  .where(.price < 500) {
    name,
    description,
    price
  }
```

To cover the query, add the uncovered field to the index definition’s `values`:

```fsl
collection Product {
  ...

  index byName {
    terms [.name]
    // Adds `stock` to the index's values
    values [.price, .description, .stock]
  }

  ...
}
```

#### [](#dynamic-filtering-using-advanced-query-composition)Dynamic filtering using advanced query composition

Complex applications may need to handle arbitrary combinations of search criteria. In these cases, you can use [query composition](../../../learn/query/composition/) to dynamically apply [indexes](../../../learn/data-model/indexes/) and [filters](../../../learn/query/patterns/sets/#filters) to queries.

The following template uses query composition to:

*   Automatically select the most selective index
    
*   Apply remaining criteria as filters in priority order
    
*   Support both index-based and filter-based search patterns
    

The template uses TypeScript and the [JavaScript driver](../../../build/drivers/js-client/). A similar approach can be used with any [Fauna client driver](../../../build/drivers/).

```typescript
/**
 * A Javascript object with a sorted list of indexes or filters.
 *
 * Javascript maintains key order for objects.
 * Sort items in the map from most to least selective.
 */
type QueryMap = Record<string, (...args: any[]) => Query>

/** Object to represent a search argument.
 *
 * Contains the name of the index to use and the arguments
 * to pass to it.
 *
 * Example:
 * { name: "by_name", args: ["limes"] }
 * { name: "range_price", args: [{ from: 100, to: 500 }] }
 */
type SearchTerm = {
  name: string
  args: any[]
}

/**
 * Composes a query by prioritizing the most selective index and then
 * applying filters.
 *
 * @param default_query - The initial query to which indexes and filters are applied.
 * @param index_map - A map of index names to functions that generate query components.
 * @param filter_map - A map of filter names to functions that generate query components.
 * @param search_terms - An array of search terms that specify the type and arguments
 *                       for composing the query.
 * @returns The composed query after applying all relevant indices and filters.
 */
const build_search = (
  default_query: Query,
  index_map: QueryMap,
  filter_map: QueryMap,
  search_terms: SearchTerm[]
): Query => {
  const _search_terms = [...search_terms]

  // Initialize a default query. Used if no other indexes are applicable.
  let query: Query = default_query

  // Iterate through the index map, from most to least selective.
  build_index_query: for (const index_name of Object.keys(
    index_map
  )) {
    // Iterate through each search term to check if it matches the highest priority index.
    for (const search_term of _search_terms) {
      // If a match is found, update the query. Then remove the search term from the
      // list and break out of the loop.
      if (index_name === search_term.name) {
        query = index_map[search_term.name](...search_term.args)
        _search_terms.splice(_search_terms.indexOf(search_term), 1)
        break build_index_query
      }
    }
  }

  // Iterate through the filter map, from most to least selective.
  for (const filter_name of Object.keys(filter_map)) {
    // Iterate through each search term to check if it matches the highest priority filter.
    for (const search_term of _search_terms) {
      // If a match is found, update the query. Then remove the search term from the list.
      if (filter_name === search_term.name) {
        const filter = filter_map[search_term.name](...search_term.args)
        query = fql`${query}${filter}`
        _search_terms.splice(_search_terms.indexOf(search_term), 1)
      }
    }
  }

  // If there are remaining search terms, you can't build the full query.
  if (_search_terms.length > 0) {
    throw new Error("Unable to build query")
  }

  return query
}
```

The following example implements the template using the [Fauna Dashboard](https://dashboard.fauna.com/)'s demo data:

```typescript
// Implementation of `index_map` from the template.
// Sort items in the map from most to least selective.
const product_index_priority_map: QueryMap = {
  by_order: (id: string) =>
    fql`Order.byId(${id})!.items.map(.product!)`,
  by_name: (name: string) => fql`Product.byName(${name})`,
  by_category: (category: string) =>
    fql`Product.byCategory(Category.byName(${category}).first()!)`,
  range_price: (range: { from?: number; to?: number }) =>
    fql`Product.sortedByPriceLowToHigh(${range})`,
}

// Implementation of `filter_map` from the template.
// Sort items in the map from most to least selective.
const product_filter_map: QueryMap = {
  by_name: (name: string) => fql`.where(.name == ${name})`,
  by_category: (category: string) =>
    fql`.where(.category == Category.byName(${category}).first()!)`,
  range_price: ({ from, to }: { from?: number; to?: number }) => {
    // Dynamically filter products by price range.
    if (from && to) {
      return fql`.where(.price >= ${from} && .price <= ${to})`
    } else if (from) {
      return fql`.where(.price >= ${from})`
    } else if (to) {
      return fql`.where(.price <= ${to})`
    }
    return fql``
  },
}

// Hybrid implementation of `index_map` and `filter_map` from the template.
// Combines filters and indexes to compose FQL query fragments.
// Sort items in the map from most to least selective.
const product_filter_with_indexes_map: QueryMap = {
  by_name: (name: string) =>
    fql`.where(doc => Product.byName(${name}).includes(doc))`,
  by_category: (category: string) =>
    fql`.where(doc => Product.byCategory(Category.byName(${category}).first()!).includes(doc))`,
  range_price: (range: { from?: number; to?: number }) =>
    fql`.where(doc => Product.sortedByPriceLowToHigh(${range}).includes(doc))`,
}

const order_id = (await client.query(fql`Order.all().first()!`))
  .data.id

const query = build_search(
  fql`Product.all()`,
  product_index_priority_map,
  product_filter_with_indexes_map,
  [
    // { type: "by", name: "name", args: ["limes"] },
    // { type: "by", name: "category", args: ["produce"] },
    { type: "range", name: "price", args: [{ to: 1000 }] },
    { type: "by", name: "order", args: [order_id] },
  ]
)

const res = await client.query(query)
```

To reduce your costs, Fauna doesn’t build duplicate indexes that have the same terms and values. Instead, Fauna only builds a single index and internally points any duplicates to the single index.

For example, in the following collection, the `byDescription()` and `byDesc()` indexes are duplicates:

```fsl
collection Product {
  ...

  index byDescription {
    terms [.description]
  }

  index byDesc {
    terms [.description]
  }
}
```

When a query calls the `byDesc()` index, Fauna uses the existing `byDescription()` index internally. `byDesc()` is considered a virtual index and is never materialized.

## [](#see-also)See also

[FSL collection schema](../collection/)

# FSL collection schema: Migrations block

| Learn: Migrations block |
| --- | --- | --- |

A migrations block instructs Fauna how to handle updates to a collection’s [field definitions](../field-definitions/) or top-level [wildcard constraint](../field-definitions/#wildcard-constraints).

This process, called a schema migration, lets you change the structure of a collection’s documents. For a tutorial, see [Progressively enforce a document type](../../../build/tutorials/schema/).

You define a migrations block as part of an FSL [collection schema](../collection/). A collection schema can only contain one migration block. The block must include one or more migration statements:

```fsl
collection Product {
  ...
  migrations {
    // Applied 2099-05-06
    add .typeConflicts
    add .stock
    move_conflicts .typeConflicts
    backfill .stock = 0
    drop .internalDesc
    move .desc -> .description
    split .creationTime -> .creationTime, .creationTimeEpoch

    // Applied 2099-05-20
    // Make `price` a required field.
    split .price -> .price, .tempPrice
    drop .tempPrice
    backfill .price = 1

    // Applied 2099-06-01
    // Re-add wildcard
    add_wildcard
  }
}
```

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each collection schema as an FQL document in the [`Collection`](../../fql-api/collection/) system collection. The `Collection` document’s `migrations` field contains FQL versions of the collection’s migrations block.

## [](#fsl-syntax)FSL syntax

```fsl-sig
migrations {
  [add <field> . . .]
  [add_wildcard . . .]
  [backfill <field> = <value> . . .]
  [drop <field> . . .]
  [move <origField> -> <newField> . . .]
  [move_conflicts <field> . . .]
  [move_wildcard <field> . . .]
  [split <origField> -> <splitField>, <splitField>[, <splitField> . . .] . . .]
}
```

## [](#migration-statements)Migration statements

| Keyword | Required | Description |
| --- | --- | --- | --- | --- |
| add |  | Adds a field definition. For examples, see Add a nullable field and Add and backfill a non-nullable field.Requires a <field> accessor. Supports dot notation and bracket notation.If the schema accepted ad hoc fields before migration, a move_conflicts statement must follow the add statement. If the field is present in existing documents, Fauna assigns non-conforming values to the move_conflicts statement’s catch-all field. |
| add_wildcard |  | Adds a top-level wildcard constraint. For an example, see Add a top-level wildcard constraint.An add_wildcard statement is not required when you first add field definitions to a collection schema. |
| backfill |  | Backfills a new field with a value. For examples, see Add and backfill a non-nullable field.Requires a <field> accessor and a field <value>. The accessor supports dot notation and bracket notation.A backfill statement is required for any migration that could result in an empty non-nullable field.The backfill operation only affects existing documents where the field is missing. It does not affect documents added after the migration.The field value can be an FQL expression. The expression can have no effect other than to:Generate an ID, such as calling ID() or newId(). You must then cast the ID to a String using toString().Get the current Date or Time, such as calling Date.today() or Time.now().Fauna evaluates the expression at schema update time.Document references for the following system collections are supported:CredentialKeyTokenReferences to named system collection documents are not supported. See Backfill using a document reference. |
| drop |  | Removes an existing field and its values. For an example, see Drop a field.Requires a <field> accessor. Supports dot notation and bracket notation. |
| move |  | Moves or renames an existing field. For examples, see Rename a field and Move a nested field.Requires <origField> and <newField> accessors. The accessors support dot notation and bracket notation. |
| move_conflicts |  | Assigns non-conforming values for fields in previous add migration statements to a catch-all field. For examples, see:How a catch-all field worksAdd multiple fields with the same catch-all fieldAdd multiple fields with different catch-all fieldsThe move_conflicts statement only affects existing documents. It does not affect documents added after the migration.Requires a <field> accessor for the catch-all field. The accessor supports dot notation and bracket notation. You can’t use move_conflicts to handle conflicts within an object’s nested fields.The catch-all field’s type must be { *: Any }?. The catch-all field can be nested in an object. The statement nests non-conforming values in the catch-all field using the original field name as a property key.If the catch-all field already contains a nested field with the same key, Fauna prepends the new key with an underscore (_). |
| move_wildcard |  | Assigns top-level fields without a field definition to a catch-all field. Required to remove a top-level wildcard constraint. For an example, see Remove a top-level wildcard constraint.Requires a <field> accessor for the catch-all field. The accessor supports dot notation and bracket notation. You can’t use move_wildcard to handle conflicts within an object’s nested fields.The catch-all field’s type must be { *: Any }?. The catch-all field can be a nested in an object. The statement nests values in the catch-all field using the original field name as a property key.If the catch-all field already contains a nested field with the same key, Fauna prepends the new key with an underscore (_). |
| split |  | Splits an existing field into multiple fields based on data type. For examples, see Split a field.Requires an <origField> accessor and two or more <splitField> accessors. The <origField> can be one of the <splitField> accessors.The <origField> field’s values are assigned to the first <splitField> field with a matching type. Fields are checked from left to right. For an example, see Match values to split fields. |

## [](#run-a-schema-migration)Run a schema migration

A typical schema migration involves the following steps:

1.  Update the [field definitions](../field-definitions/) and [wildcard constraint](../field-definitions/#wildcard-constraints) in the [collection schema](../collection/).
    
2.  Add one or more related migration statements to the collection schema’s migrations block. Include comments to group and annotate statements related to the same migration.
    
    Fauna runs each new migration statement sequentially from top to bottom. Fauna ignores unchanged migration statements from previous migrations.
    
3.  Commit the updated collection schema to Fauna with a [staged schema change](../../../learn/schema/manage-schema/#staged).
    
    To run a staged schema change using the CLI:
    
    1.  Use [`fauna schema push`](../../../build/cli/v4/commands/schema/push/) to stage the schema changes. [`fauna schema push`](../../../build/cli/v4/commands/schema/push/) stages schema changes by default:
        
        ```cli
        # Replace 'us' with your preferred Region Group:
        # 'us' (United States), 'eu' (Europe), or `global`.
        # Replace 'my_db' with your database's name.
        fauna schema push \
          --database us/my_db \
          --dir /path/to/schema/dir
        ```
        
        A database can have one staged schema change at a time. You can update staged schema using [`fauna schema push`](../../../build/cli/v4/commands/schema/push/).
        
        When a database has staged schema, any access or updates done using FQL’s schema commands on related [system collections](../../../learn/data-model/collections/#system-coll) interact with the staged schema, not the database’s active schema.
        
        For example, when schema changes are staged, [`Collection.all()`](../../fql-api/collection/static-all/) returns `Collection` documents for the staged collection schema, not the database’s `Collection` documents.
        
        If a database has staged schema, you can’t edit the database’s active schema using FQL, the [Dashboard](https://dashboard.fauna.com/), or an [unstaged schema change](../../../learn/schema/manage-schema/#unstaged). You must first [abandon the staged schema change](#abandon).
        
    2.  Use [`fauna schema status`](../../../build/cli/v4/commands/schema/status/) to check the status of the staged schema:
        
        ```cli
        fauna schema status \
          --database us/my_db
        ```
        
        Possible statuses:
        
        | Staged status | Description |
        | --- | --- | --- | --- |
        | pending | Changes are being processed. New indexes are still being built. |
        | ready | All indexes have been built. Changes are ready to commit. |
        | failed | There was an error during the staging process. |
    3.  When the status is `ready`, use [`fauna schema commit`](../../../build/cli/v4/commands/schema/commit/) to apply the staged schema to the database:
        
        ```cli
        fauna schema commit \
          --database us/my_db
        ```
        
        You can only commit staged schema with a status of `ready`.
        
        If you no longer wish to apply the staged schema or if the status is `failed`, use [`fauna schema abandon`](../../../build/cli/v4/commands/schema/abandon/) to unstage the schema:
        
        ```cli
        fauna schema abandon \
          --database us/my_db
        ```
        
    

Once committed, changes from the migration are immediately visible in any subsequent queries.

## [](#migration-errors)Migration errors

When you submit a collection schema, Fauna checks the schema’s field definitions and migration statements for potential conflicts.

If a change could conflict with the collection’s data, Fauna rejects the schema with an error message. The check doesn’t require a read or scan of the collection’s documents.

## [](#previous-migration-statements)Previous migration statements

For documentation purposes, you can retain migration statements from previous schema migrations in a collection schema. This lets you apply the same changes to other databases. For example, you could copy migration statements used for a staging database to run a similar migration on a production database.

Use caution when copying migration statements that depend on default field values across databases. These migrations can produce different results on different databases based on:

*   The state of documents at migration time
    
*   Previously applied migrations
    

For an example, see [Copy a migration that depends on default values](#copy-block-ex).

## [](#migrations-for-empty-collections)Migrations for empty collections

If a collection has never contained a document, you can change its [field definitions](../field-definitions/) and top-level [wildcard constraint](../field-definitions/#wildcard-constraints) without a migrations block. If the collection schema includes a migrations block, Fauna ignores it.

## [](#limitations)Limitations

A migration statement’s field accessors can’t reference nested fields in an object Array.

## [](#examples)Examples

### [](#add-nullable-fields-example)Add a nullable field

Starting with the following collection schema:

```fsl
collection Product {
  // Contains no field definitions.
  // Accepts ad hoc fields of any type.
  // Has an implicit wildcard constraint of
  // `*: Any`.
}
```

The following migration adds a nullable field to the collection. Nullable fields aren’t required in new collection documents.

```fsl
collection Product {
  // Adds the `description` field.
  // Accepts `String` or `null` values.
  description: String?
  // Adds the `typeConflicts` field as a catch-all field for
  // existing `description` values that aren't `String` or `null`.
  // Because `typeConflicts` is used in a `move_conflicts`statement,
  // it must have a type of `{ *: Any }?`.
  // If the schema didn't accept ad hoc field before
  // the migration, a catch-all field isn't needed.
  typeConflicts: { *: Any }?

  // The schema now includes field definitions.
  // Adds an explicit wildcard constraint to continue
  // accepting documents with ad hoc fields.
  *: Any

  migrations {
    // Adds the `typeConflicts` field.
    add .typeConflicts
    // Adds the `description` field.
    add .description
    // Nests non-conforming `description` and `typeConflicts`
    // field values in the `typeConflicts` catch-all field.
    // If the schema didn't accept ad hoc fields before the
    // migration, a `move_conflicts` statement isn't needed.
    move_conflicts .typeConflicts
  }
}
```

### [](#how-a-catch-all-field-works)How a catch-all field works

The [previous migration](#add-nullable-fields-example) uses a `move_conflicts` statement to reassign non-conforming `description` field values to the `typeConflicts` catch-all field.

The following examples show how the migration would affect existing documents that contain a `description` field.

The catch-all field for a `move_wildcard` statement works similarly.

#### [](#migrate-a-document-with-no-changes)Migrate a document with no changes

The migration does not affect existing documents that contain a field value of an accepted type.

```
{
  ...
  // `description` contains an accepted data type.
  // The field stays the same throughout the migration.
  description: "Conventional Hass, 4ct bag",
  ...
}
```

Similarly, a `move_wildcard` statement does not affect existing fields that conform to a field definition.

#### [](#migrate-a-non-conforming-field-value)Migrate a non-conforming field value

If an existing document contains a `description` field with a non-conforming value, the migration nests the value in the `typeConflicts` catch-all field.

```
// Before migration:
{
  ...
  // `description` contains an unaccepted type.
  description: 5,
  ...
}

// After migration:
{
  ...
  // The `description` field is nested in
  // the `typeConflicts` catch-all field.
  typeConflicts: {
    description: 5
  }
  ...
}
```

##### [](#the-catch-all-field-already-exists-as-an-object)The catch-all field already exists as an object

If the document already contains the catch-all field as an object, the migration uses the existing field.

```
// Before migration:
{
  ...
  // `description` contains an unaccepted type.
  description: 5,
  // The `typeConflicts` catch-all field already exists as an object.
  typeConflicts: {
    backordered: "yes"
  }
  ...
}

// After migration:
{
  ...
  // The `description` field is nested in
  // the existing `typeConflicts` catch-all field.
  typeConflicts: {
    description: 5,
    backordered: "yes"
  }
  ...
}
```

##### [](#the-catch-all-field-already-exists-with-non-conforming-values)The catch-all field already exists with non-conforming values

If you add the catch-all field in the same migration, Fauna nests any existing, non-conforming values for the field in itself.

```
// Before migration:
{
  ...
  // `description` contains an unaccepted type.
  description: 5,
  // The `typeConflicts` catch-all field already exists but isn't an object.
  // The field contains an unaccepted type.
  typeConflicts: true
  ...
}

// After migration:
{
  ...
  // The existing `typeConflicts` field value doesn't conform
  // to the new `typeConflicts` field definition. The migration
  // nests the existing, non-conforming `typeConflicts` field
  // value in itself.
  typeConflicts: {
    description: 5,
    typeConflicts: true
  }
  ...
}
```

##### [](#the-catch-all-field-already-contains-the-field-key)The catch-all field already contains the field key

If the catch-all field already contains a nested field with the same key, Fauna prepends the new key with an underscore (`_`).

```
// Before migration:
{
  ...
  // `description` contains an unaccepted type.
  description: 5,
  // The `typeConflicts` catch-all field already contains a nested
  // `description` field.
  typeConflicts: {
    description: "Conventional Hass, 4ct bag"
  }
  ...
}

// After migration:
{
  ...
  typeConflicts: {
    description: "Conventional Hass, 4ct bag",
    // The new key is prepended with an underscore.
    _description: 5
  }
  ...
}
```

### [](#add-backfill-example)Add and backfill a non-nullable field

Starting with the following collection schema:

```fsl
collection Product {
  // Contains no field definitions.
  // Accepts ad hoc fields of any type.
  // Has an implicit wildcard constraint of
  // `*: Any`.
}
```

The following migration adds a non-nullable field to the collection. Non-nullable fields must include a `backfill` statement for existing documents.

```fsl
collection Product {
  // Adds the `stock` field.
  stock: Int
  // Adds the `typeConflicts` field as a catch-all field for
  // existing `stock` values that aren't `Int`.
  // Because `typeConflicts` is used in a `move_conflicts`statement,
  // it must have a type of `{ *: Any }?`.
  // If the schema didn't accept ad hoc field before
  // the migration, a catch-all field isn't needed.
  typeConflicts: { *: Any }?

  *: Any

  migrations {
    // Adds the `typeConflicts` field.
    add .typeConflicts
    // Adds the `stock` field.
    add .stock
    // Nests non-conforming `stock` and `typeConflicts`
    // field values in the `typeConflicts` catch-all field.
    // If the schema didn't accept ad hoc fields before the
    // migration, a `move_conflicts` statement isn't needed.
    move_conflicts .typeConflicts
    // Set `stock` to `0` for existing documents
    // with a `null` (missing) or non-conforming `stock` value.
    backfill .stock = 0
  }
}
```

For examples of how the migration’s `move_conflicts` statement reassigns non-conforming field values, see [How a catch-all field works](#how-a-catch-all-field-works).

#### [](#backfill-using-todays-date)Backfill using today’s date

Use [`Date.today()`](../../fql-api/date/today/) to use today’s date as a backfill value:

```fsl
collection Product {
  // Adds the `creationDate` field.
  creationDate: Date
  typeConflicts: { *: Any }?

  *: Any

  migrations {
    add .typeConflicts
    add .creationDate
    move_conflicts .typeConflicts
    // Set `creationDate` to today for existing documents.
    backfill .creationDate = Date.today()
  }
}
```

Fauna evaluates the expression at schema update time.

#### [](#backfill-using-the-current-time)Backfill using the current time

Use [`Time.now()`](../../fql-api/time/now/) to use the current time as a backfill value:

```fsl
collection Product {
  // Adds the `creationTime` field.
  creationTime: Time
  typeConflicts: { *: Any }?

  *: Any

  migrations {
    add .typeConflicts
    add .creationTime
    move_conflicts .typeConflicts
    // Set `creationTime` to now for existing documents.
    backfill .creationTime = Time.now()
  }
}
```

Fauna evaluates the expression at schema update time.

#### [](#backfill-using-an-id)Backfill using an ID

Use [`newId()`](../../fql-api/globals/newid/) to use a unique [ID](../../fql/types/#id) as a backfill value. You must cast the ID to a [String](../../fql/types/#string) using [`toString()`](../../fql-api/string/tostring/):

```fsl
collection Product {
  // Adds the `productId` field.
  productId: String = newId().toString()
  typeConflicts: { *: Any }?

  *: Any

  migrations {
    add .typeConflicts
    add .productId
    move_conflicts .typeConflicts
    // Set `productId` to an ID for existing documents.
    backfill .productId = newId().toString()
  }
}
```

Fauna uses the same [ID](../../fql/types/#id) value to backfill existing documents. The backfilled ID is not unique among documents.

#### [](#doc-ref-backfill)Backfill using a document reference

You can use a [document reference](../../../learn/data-model/relationships/) as a backfill value:

```fsl
collection Product {
  // Adds the `category` field.
  category: Ref<Category>
  typeConflicts: { *: Any }?

  *: Any

  migrations {
    add .typeConflicts
    add .category
    move_conflicts .typeConflicts
    // Set `category` to a `Category` collection document.
    // Replace `400684606016192545` with a `Category` document ID.
    backfill .category = Category("400684606016192545")
  }
}
```

Fauna doesn’t guarantee the document exists. You can’t fetch the document using an FQL expression.

Document references for the following [system collections](../../../learn/data-model/collections/#system-coll) are supported:

*   [`Credential`](../../fql-api/credential/)
    
*   [`Key`](../../fql-api/key/)
    
*   [`Token`](../../fql-api/token/)
    

References to [named system collection](../../../learn/data-model/collections/#named-coll) documents are not supported.

### [](#move-wildcard-conflicts-ex-1)Add multiple fields with the same catch-all field

Multiple fields can use the same `move_conflicts` statement during a migration.

For example, starting with the following collection schema:

```fsl
collection Product {
  // Contains no field definitions.
  // Accepts ad hoc fields of any type.
  // Has an implicit wildcard constraint of
  // `*: Any`.
}
```

The following migration adds multiple fields. If the fields are present in existing documents, they nest the values in the field specified by the next `move_conflicts` statement:

```fsl
collection Product {
  description: String?
  price: Int

  typeConflicts: { *: Any }?
  *: Any

  migrations {
    add .typeConflicts
    add .description
    add .price
    // Nests non-conforming `description`, `price`, and `typeConflicts`
    // field values in the `typeConflicts` catch-all field.
    move_conflicts .typeConflicts
    backfill .price = 1
  }
}
```

### [](#move-wildcard-conflicts-ex-2)Add multiple fields with different catch-all fields

A migration can include multiple `move_conflicts` statements. This lets you use different catch-all fields for different fields.

For example, starting with the following collection schema:

```fsl
collection Product {
  // Contains no field definitions.
  // Accepts ad hoc fields of any type.
  // Has an implicit wildcard constraint of
  // `*: Any`.
}
```

The following migration includes multiple `move_conflicts` statements:

```fsl
collection Product {
  description: String?
  price: Int
  stock: Int?

  typeConflicts: { *: Any }?
  stockTypeConflicts: { *: Any }?
  *: Any

  migrations {
    add .typeConflicts
    add .description
    add .price
    // Nests non-conforming `description`, `price`, and `typeConflicts`
    // field values in the `typeConflicts` catch-all field.
    move_conflicts .typeConflicts
    backfill .price = 1

    add .stockTypeConflicts
    add .stock
    // Nests non-conforming `stock` and `stockTypeConflicts`
    // field values in the `stockTypeConflicts` catch-all field.
    move_conflicts .stockTypeConflicts
  }
}
```

### [](#drop-field)Drop a field

Starting with the following collection schema:

```fsl
collection Product {
  price: Int = 0
  internalDesc: String?
}
```

The following migration removes the `internalDesc` field and its values from the collection’s documents:

```fsl
collection Product {
  price: Int = 0
  // Removed the `internalDesc` field.

  migrations {
    drop .internalDesc
  }
}
```

#### [](#drop-doc-ref)Drop a document reference field

You can’t delete a collection that’s referenced by a field definition or other schema. To delete a collection and drop any related [document reference](../../../learn/data-model/relationships/) fields for the collection:

1.  Run migrations to drop any field definitions that reference the collection. For example, starting with the following collection schema:
    
    ```fsl
    collection Product {
      name: String
      // Accepts a reference to a `Category` collection document or `null`.
      category: Ref<Category>?
    }
    ```
    
    The following migration removes the document reference field:
    
    ```fsl
    collection Product {
      name: String
      // Removed the `category` field.
    
      migrations {
        drop .category
      }
    }
    ```
    
2.  Remove references to the collection in any other schema. For example, remove references to the collection from any [role schema](../../../learn/security/roles/).
    
3.  Remove the collection schema for the collection you want to delete.
    
4.  Commit your changes to Fauna using a [staged schema change](../../../learn/schema/manage-schema/#staged).
    

### [](#rename-field)Rename a field

Starting with the following collection schema:

```fsl
collection Product {
  desc: String?
}
```

The following migration renames the `desc` field to `description`:

```fsl
collection Product {
  // Renamed `desc` to `description`.
  description: String?

  migrations {
    move .desc -> .description
  }
}
```

### [](#split-field)Split a field

Starting with the following collection schema:

```fsl
collection Product {
  creationTime: Time | Number?
}
```

The following migration reassigns `creationTime` field values in the following order:

1.  [Time](../../fql/types/#time) values to `creationTime`
    
2.  [Number](../../fql/types/#number) values to `creationTimeEpoch`
    

```fsl
collection Product {
  // `creationTime` accepts `Time` values.
  creationTime: Time?
  // `creationTimeEpoch` accepts `Number` values.
  creationTimeEpoch: Number?

  migrations {
    split .creationTime -> .creationTime, .creationTimeEpoch
  }
}
```

#### [](#match-values-to-split-fields)Match values to split fields

`split` assigns field values to the first field with a matching type. Keep this in mind when using superset types, such as [Number](../../fql/types/#number) or [Any](../../fql/types/#any).

For example, starting with the following collection schema:

```fsl
collection Product {
  creationTime: Time | Number?
}
```

The following migration would reassign `creationTime` field values in the following order:

1.  [Time](../../fql/types/#time) values to `creationTime`
    
2.  [Number](../../fql/types/#number) values, including [Int](../../fql/types/#int) values, to `creationTimeNum`
    
3.  [Int](../../fql/types/#int) values to `creationTimeInt`
    

```fsl
collection Product {
  // `creationTime` accepts `Time` values.
  creationTime: Time?
  // `creationTimeNum` accepts any `Number` value, including `Int` values.
  creationTimeNum: Number?
  // `creationTimeInt` accepts `Int` values.
  creationTimeInt: Int?

  migrations {
    split .creationTime -> .creationTime, .creationTimeNum, .creationTimeInt
  }
}
```

Because `creationTimeNum` precedes `creationTimeInt`, `split` would never assign a value to the `creationTimeInt` field.

Instead, you can reorder the `split` statement as follows:

```fsl
collection Product {
  // `creationTime` accepts `Time` values.
  creationTime: Time?
  // `creationTimeInt` accepts `Int` values.
  creationTimeInt: Int?
  // `creationTimeNum` accepts any other `Number` value.
  creationTimeNum: Number?

  migrations {
    split .creationTime -> .creationTime, .creationTimeInt, .creationTimeNum
  }
}
```

Now, `split` assigns any `creationTime` values with an [Int](../../fql/types/#int) type to `creationTimeInt`. Any remaining [Number](../../fql/types/#number) values are assigned to `creationTimeNum`.

### [](#narrow-a-fields-accepted-types)Narrow a field’s accepted types

You can use migration statements to narrow a field’s accepted data types, including [Null](../../fql/types/#null). For example, you can convert a nullable field to a non-nullable field.

Starting with the following collection schema:

```fsl
collection Product {
  // Accepts `String` and `null` values.
  description: String?
  price: Int?
}
```

The following migration:

*   Uses `split` to reassign `null` values for the `description` field to a temporary `tmp` field.
    
*   Drops the `tmp` field and its values.
    
*   Backfills any `description` values that were previously `null` with the `"default"` string.
    

```fsl
collection Product {
  // Accepts `String` values only.
  description: String
  price: Int?

  migrations {
    split .description -> .description, .tmp
    drop .tmp
    backfill .description = "default"
  }
}
```

Because it follows a `split` statement, `backfill` only affects documents where the `description` field value was `null` and split to `tmp`.

### [](#add-wildcard-constraint)Add a top-level wildcard constraint

Starting with the following collection schema:

```fsl
collection Product {
  name: String?
  description: String?
  price: Int?
  stock: Int?
}
```

The following migration adds a top-level wildcard constraint. Once added, the collection accepts documents with ad hoc fields.

```fsl
collection Product {
  name: String?
  description: String?
  price: Int?
  stock: Int?

  *: Any

  migrations {
    add_wildcard
  }
}
```

### [](#remove-wildcard-constraint)Remove a top-level wildcard constraint

Starting with the following collection schema:

```fsl
collection Product {
  name: String?
  description: String?
  price: Int?
  stock: Int?

  *: Any
}
```

The following migration removes the collection’s top-level wildcard constraint. Once removed, the collection no longer accepts documents with ad hoc fields.

```fsl
collection Product {
  name: String?
  description: String?
  price: Int?
  stock: Int?

  // Removes the `*: Any` wildcard constraint.

  // Adds the `typeConflicts` field as a catch-all field for
  // existing ad hoc fields that don't
  // have a field definition.
  typeConflicts: { *: Any }?

  migrations {
    add .typeConflicts
    move_conflicts .typeConflicts
    // Nests existing ad hoc field values without a field definition
    // in the `typeConflicts` catch-all field.
    move_wildcard .typeConflicts
  }
}
```

The `move_wildcard` statement’s catch-all field works similarly to a `move_conflict` statement’s catch-all field. See [How a catch-all field works](#how-a-catch-all-field-works).

### [](#nested)Migrate nested fields

A nested field is a field within an object. For example:

```fsl
collection Product {
  // `metadata` is an object field.
  metadata: {
    // `name` is a nested field
    // in the `metadata` object.
    "name": String?
  }
}
```

For more information, see [Objects](../field-definitions/#nested) in the field definition docs.

#### [](#access-nested)Access nested fields in migration statements

A top-level field name must be a valid [identifier](../../fql/variables/#identifier). A [nested field name](../field-definitions/#nested) can be any valid string, including an identifier.

You can access identifier field names in a migration statement using [dot notation](../../fql/dot-notation/#dot-notation-field-accessor):

```fsl
collection Product {
  metadata: {
    name: String?
    internalDesc: String?
  }

  migrations {
    // Uses dot notation to add the
    // nested `internalDesc` field.
    add .metadata.internalDesc
  }
}
```

You can access non-identifier field names in a migration statement using [bracket notation](../../fql/dot-notation/#bracket-notation-field-accessor):

```fsl
collection Product {
  metadata: {
    name: String?
    "internal description": String?
  }

  migrations {
    // Uses bracket notation to add the
    // nested `internal description` field.
    add .metadata["internal description"]
  }
}
```

#### [](#move-field)Move a nested field

Starting with the following collection schema:

```fsl
collection Product {
  metadata: {
    name: String
    internalDesc: String
  }
}
```

The following migration moves the nested `name` field from the `metadata` object to the top level:

```fsl
collection Product {
  name: String
  metadata: {
    internalDesc: String
  }

  migrations {
    move .metadata.name -> .name
  }
}
```

#### [](#backfill-object)Add and backfill an object

If you add a field definition for an object, you must include `add` statements for any fields in the object. You must also include `backfill` statements for any non-nullable fields in the object.

Starting with the following collection schema:

```fsl
collection Customer {
  name: String
  email: String
}
```

The following migration adds a field definition for a non-nullable `address` object:

```fsl
collection Customer {
  name: String
  email: String
  address: {
    street: String
    city: String
  }

  migrations {
    // The following statements are implicit:
    // add .address
    // backfill .address = {}

    // Adds the nested `address.street` field
    add .address.street
    // Adds the nested `address.city` field
    add .address.city

    // Set `address.street` to `unknown street`
    // for existing documents.
    backfill .address.street = "unknown street"
    // Set `address.city` to `unknown city`
    // for existing documents.
    backfill .address.city = "unknown city"
  }
}
```

#### [](#backfill-nested)Add and backfill a non-nullable nested field

If you add a non-nullable field to an existing object, you must include a `backfill` statement. Starting with the following collection schema:

```fsl
collection Customer {
  address: {
    street: String
    city: String
    state: String
    postalCode: String
  }
}
```

The following migration adds a non-nullable `country` field to the `address` object:

```fsl
collection Customer {
  address: {
    street: String
    city: String
    state: String
    postalCode: String
    country: String
  }

  migrations {
    // Adds the nested `country` field to the `address` object.
    add .address.country
    // Set `address.country` to `US` for existing documents.
    backfill .address.country = "US"
  }
}
```

#### [](#add-a-nested-wildcard-constraint)Add a nested wildcard constraint

An `add_wildcard` statement isn’t required to add a wildcard constraint to an object. Starting with the following collection schema:

```fsl
collection Product {
  metadata: {
    name: String
  }
}
```

The following migration adds a wildcard constraint to the `metadata` object:

```fsl
collection Product {
  metadata: {
    name: String
    *: Any
  }
}
```

Documents added after the migration can contain ad hoc fields in the `metadata` object.

#### [](#wildcard-field-migrations)Nested field migrations with wildcard constraints

You can’t run migrations on a nested field that has a neighboring wildcard constraint.

Starting with the following collection schema:

```fsl
collection Product {
  name: String
  metadata: {
    *: Any
  }
}
```

Create a `Product` document with a nested `productUpc` field in the `metadata` object:

```fql
Product.create({
  name: "key limes",
  metadata: {
    productUpc: "00123456789012"
  }
})
```

The following migration is disallowed and returns an error:

```fsl
collection Product {
  name: String
  metadata: {
    productUpc: Int?
    *: Any
  }

  migrations {
    // Error! `metadata`contains a
    // wildcard constraint.
    // You can't run migrations on
    // `metadata.productUpc` field.
    add .metadata.productUpc
  }
}
```

The `add_wilcard`, `remove_wildcard`, and `move_wildcard` [migration statements](#migration-statements) only support top-level wildcard constraints, not nested wildcard constraints. These statements let you safely handle conflicts between ad hoc and defined fields.

#### [](#remove-a-nested-wildcard-constraint)Remove a nested wildcard constraint

A `move_wildcard` statement isn’t required to remove a wildcard constraint from an object. Starting with the following collection schema:

```fsl
collection Product {
  metadata: {
    name: String
    *: Any
  }
}
```

The following migration removes the wildcard constraint from the `metadata` object:

```fsl
collection Product {
  metadata: {
    name: String
    // Removes the nested `*: Any?` wildcard constraint.
  }

  migrations {
    // Reassigns non-conforming `metadata` objects
    // to the `tmp` field.
    split .metadata -> .metadata, .tmp
    // Backfills documents whose `metadata` objects
    // were reassigned.
    backfill .metadata = { name: "" }
    // Removes the `tmp` field.
    drop .tmp
  }
}
```

### [](#copy-block-ex)Copy a migration that depends on default values

The following example shows how migration statements that depend on default values can produce different results when copied to a database in a different state. It uses two example databases: `Dev` and `Staging`.

1.  In the `Dev` database, create a `Product` collection with the following collection schema:
    
    ```fsl
    collection Product {
      stock: Int = 0
    }
    ```
    
2.  Create a `Product` document with no fields:
    
    ```fql
    Product.create({})
    ```
    
3.  Migrate the collection schema to add a `price` field with a default value of `0`:
    
    ```fsl
    collection Product {
      stock: Int = 0
      // Accepts `Int` and `String` values.
      // Defaults to `0`.
      price: Int | String = 0
    
      migrations {
        // Migration #1 (Current)
        add .price
      }
    }
    ```
    
    The document you previously created now has a `price` of `0`:
    
    ```
    {
      id: "111",
      coll: Product,
      ts: Time("2099-07-19T18:48:58.985Z"),
      stock: 0,
      price: 0
    }
    ```
    
4.  Migrate the schema to split `price` field values based on data type:
    
    ```fsl
    collection Product {
      stock: Int = 0
      // Adds the `priceInt` field.
      // `priceInt` defaults to `1`.
      // `price` previously defaulted to `0`.
      priceInt: Int = 1
      // Adds the `priceStr` field.
      priceStr: String = ""
    
      migrations {
        // Migration #1 (Previous)
        // Already run. Fauna ignores
        // previously run migration statements.
        add .price
    
        // Migration #2 (Current)
        // Splits `price` field values.
        // `Int` values are assigned to `priceInt`.
        // `String` values are assigned to `priceStr`.
        split .price -> .priceInt, .priceStr
      }
    }
    ```
    
    The document you previously created now has a `priceInt` of `0`:
    
    ```
    {
      id: "111",
      coll: Product,
      ts: Time("2099-07-19T18:48:58.985Z"),
      stock: 0,
      priceInt: 0,
      priceStr: ""
    }
    ```
    
    The document’s `price` was previously `0`. The `split` statement reassigned the `price` value to `priceInt`. The `priceInt` field’s default value is not applied.
    
5.  In a `Staging` database, create a `Product` collection with the same initial schema:
    
    ```fsl
    collection Product {
      stock: Int = 0
    }
    ```
    
6.  Create a `Product` document in the `Staging` database:
    
    ```fql
    Product.create({})
    ```
    
7.  In the `Staging` database, run a migration on the `Product` collection schema that combines the two previous migrations:
    
    ```fsl
    collection Product {
      stock: Int = 0
      // `priceInt` defaults to `1`.
      priceInt: Int = 1
      priceStr: String = ""
    
      migrations {
        add .price
    
        split .price -> .priceInt, .priceStr
      }
    }
    ```
    
    In the `Staging` database, the document has a `priceInt` value of `1`:
    
    ```
    {
      id: "111",
      coll: Product,
      ts: Time("2099-07-19T18:48:58.985Z"),
      stock: 0,
      // `priceInt` field
      priceInt: 1,
      priceStr: ""
    }
    ```
    
    Because the document didn’t previously contain a `price` field, the `split` statement didn’t affect the document. Instead, the document uses the default `priceInt` value.
    

## [](#see-also)See also

[FSL collection schema](../collection/)  
[FSL collection schema: Field definitions](../field-definitions/)

# FSL collection schema: Unique constraint definitions

| Learn: Unique constraints |
| --- | --- | --- |

A unique constraint ensures a field value or combination of field values is unique for each document in a collection. Fauna rejects document writes that don’t meet the constraint.

You define unique constraints as part of an FSL [collection schema](../collection/):

```fsl
collection Customer {
  ...
  // 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)]
  ...
}
```

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each collection schema as an FQL document in the [`Collection`](../../fql-api/collection/) system collection. The `Collection` document’s `constraints` field contains FQL versions of the collection’s unique constraint definitions.

## [](#fsl-syntax)FSL syntax

```fsl-sig
unique [<constraintTerm> . . .]
```

## [](#members)Members

| Member | Type | Required | Description |
| --- | --- | --- | --- | --- | --- |
| constraintTerm | String | true | Document field to constrained to a unique value.Use mva() to constrain every element of an Array field. |

## [](#discussion)Discussion

Unique constraints are applied when a new document is [created](../../fql-api/collection/static-create/) or when an existing document is [updated](../../fql-api/document/update/). Constraints aren’t applied retroactively to existing documents.

You can declare any number of constraints that define which [Document](../../fql/types/#document) fields must have unique values in the [Collection](../../fql/types/#collection). For example:

```fsl
collection Customer {
  ...
  unique [.email]

  unique [.firstName, .lastName]
  ...
}
```

A unique constraint can define multiple fields that must be unique in combination. If the `firstName` and `lastName` fields in the example are defined as a unique constraint, the first and last name combination must be unique for the collection.

If you create a unique constraint over more than one field, the absence of one or more fields with the presence of other fields in the unique constraint is a combination that the constraint is enforced over. In the first and last name example, if you create a user and populate only the `lastName` field, you can’t create another user with only the same last name, but you can create another user with the same last name if you also define a `firstName` field.

When one or more fields are part of a unique constraint, multiple documents can’t have the same combination of values for the constrained fields.

## [](#examples)Examples

```fsl
collection Product {
  unique [.name]
}
```

## [](#see-also)See also

[FSL collection schema](../collection/)

# FSL function schema

| Learn: User-defined functions (UDFs) |
| --- | --- | --- |

An FSL function schema defines a [user-defined function (UDF)](../../../learn/schema/user-defined-functions/). A user-defined function (UDF) is a set of one or more FQL statements stored as a reusable resource in a Fauna database. Like a stored procedure in SQL, a UDF can accept parameters, perform operations, and return results.

```fsl
@role("server-readonly")
// Defines the `getCustomerName` UDF.
function getCustomerName(customerId: ID): String {
  // Find the customer document by ID.
  let customer = Customer.byId(customerId)

  // Return the customer's name field.
  customer!.name
}
```

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each function schema as an FQL document in the [`Function`](../../fql-api/function/) system collection.

## [](#fsl-syntax)FSL syntax

```fsl-sig
[@role("<roleName>")]
[@alias(<aliasId>]
function <functionName> (<parameter>: <parameterType>): <returnType> {
  <functionBody>
}
```

## [](#name)Name

_functionName_ _[String](../../fql/types/#string)_ **Required**

Unique name of the UDF. The _name_ is case insensitive and can’t be a [reserved](../../fql/reserved/) word.

## [](#properties)Properties

| Parameter | Type | Required | Description |
| --- | --- | --- | --- | --- | --- |
| parameter | String | true | functionBody parameterSupports the ... syntax for variadic arguments. See Variadic arguments. |
| parameterType | String | true | parameter type |
| returnType | String | true | functionBody return type |
| functionBody | String | true | FQL block. |

## [](#annotations)Annotations

_roleName_ _[String](../../fql/types/#string)_

The optional `@role` annotation associates a [Role](../../fql/types/#role) named _roleName_ with the function. The [Role](../../fql/types/#role) can be a user-defined role or one of the following built-in roles:

*   `admin`
    
*   `server`
    
*   `server-readonly`
    

This is the role to use when the UDF is called. This is typically used for privilege escalation when current privileges would otherwise be too restrictive. A function must declare a built-in role to be able to view logs.

The role can be set only by users with a privileged role, such as `admin`, `server`, or a user-defined role that grants write privilege for [Function](../../fql/types/#function)s.

Use `@role` carefully. Setting the role privilege gives the function permission to create, change, and remove documents when invoked by calling the function. A UDF can change a role to change function privileges.

_aliasId_ _[String](../../fql/types/#string)_ or _Identifier_

The optional `@alias` annotation defines a second identifier for the function. The _aliasId_ can be a [String](../../fql/types/#string), `"Foo"`, or an identifier, `Foo`.

## [](#examples)Examples

### [](#basic-example)Basic example

You create and manage a UDF as an FSL function schema:

```fsl
function getOrCreateCart(id) {
  // Find the customer by ID, using the ! operator to
  // assert that the customer exists.
  // If the customer does not exist, fauna will throw a
  // document_not_found error.
  let customer = Customer.byId(id)!

  if (customer!.cart == null) {
    // Create a cart if the customer does not have one.
    Order.create({
      status: 'cart',
      customer: Customer.byId(id),
      createdAt: Time.now(),
      payment: {}
    })
  } else {
    // Return the cart if it already exists.
    customer!.cart
  }
}
```

You save and manage function schema using the [Fauna Dashboard](https://dashboard.fauna.com/) or the [Fauna CLI](../../../build/cli/v4/)'s [`fauna schema push`](../../../build/cli/v4/commands/schema/push/) command.

Once saved in a database, you can call the UDF in FQL queries against the database:

```fql
// Call the `getOrCreateCart()` UDF with a
// customer id of `111`.
getOrCreateCart(111)
```

### [](#type-checking)Type checking

You can explicitly type a UDF’s arguments and return value:

```fsl
// The `x` argument must be a `Number`.
// The function returns a `Number` value.
function myFunction(x: Number): Number {
  x + 2
}
```

### [](#multiple-statements)Multiple statements

A UDF can contain multiple statements and expressions:

```fsl
function calculateOrderTotal(order) {
  // Calculate the subtotal by summing up the prices of all items.
  let subtotal = order.items.fold(0, (sum, orderItem) => {
    if (orderItem.product != null) {
      sum + orderItem.product.price * orderItem.quantity
    } else {
      sum
    }
  })

  // Calculate the tax based on the subtotal.
  let tax = subtotal * 0.1

  // Return the final total including the tax.
  subtotal + tax
}
```

### [](#variadic)Variadic arguments

Use the `...` syntax to create a variadic UDF that accepts an indefinite number of arguments, including zero.

```fsl
// The `args` argument accepts multiple Numbers.
function getLength(...args: Number): Number {
  args.length
}
```

When called in an FQL query:

```fql
getLength(1, 2, 3)
```

```
3
```

A UDF can only accept one variadic argument. It must be the last argument.

Variadic arguments are collected into an [Array](../../fql/types/#array). You can define a type signature to limit the types of values accepted and held in the Array.

For example, the following UDF accepts a single [String](../../fql/types/#string) argument followed by a variadic argument of zero or more [Number](../../fql/types/#number)s:

```fsl
function formatCurrency(symbol: String, ...amounts: Number): String {
  symbol + amounts.reduce((prev, cur) => prev + cur).toString()
}
```

When called in an FQL query:

```fql
formatCurrency("$", 2, 3)
```

```
"$5"
```

### [](#composability)Composability

UDFs are composable, allowing you to combine multiple UDFs.

For example, you can define a UDF:

```fsl
// Defines the `applyDiscount()` UDF.
function applyDiscount(total, discountPercent) {
  total * (1 - discountPercent / 100)
}
```

And call the UDF in another UDF definition:

```fsl
// Defines the `calculateFinalPrice()` UDF.
function calculateFinalPrice(order, discountPercent) {
  // Calls the `calculateOrderTotal()` UDF.
  let total = calculateOrderTotal(order)
  // Calls the `applyDiscount()` UDF.
  applyDiscount(total, discountPercent)
}
```

### [](#error-handling)Error handling

Use reference:fql-api/globals/abort.adoc to raise an Abort error from a UDF:

```fsl
function validateOrderStatusTransition(oldStatus, newStatus) {
  if (oldStatus == "cart" && newStatus != "processing") {
    // The order can only transition from cart to processing.
    abort("Invalid status transition.")
  } else if (oldStatus == "processing" && newStatus != "shipped") {
    // The order can only transition from processing to shipped.
    abort("Invalid status transition.")
  } else if (oldStatus == "shipped" && newStatus != "delivered") {
    // The order can only transition from shipped to delivered.
    abort("Invalid status transition.")
  }
}
```

### [](#runtime-privileges)Runtime privileges

By default, UDFs run with the privileges of the calling query’s authentication secret.

When you define a UDF, you can include an optional `@role` annotation. If provided, the UDF runs using the role’s privileges, regardless of the secret used to call it:

```fsl
// Runs with the built-in `server` role's privileges.
@role("server")
function inventory(name) {
  Product.byName(name) {
    name,
    description,
    stock
  }
}
```

#### [](#udf-doc-refs)Resolve document references returned by UDFs

If a UDF returns [document references](../../../learn/data-model/relationships/) in the query results, the [secret](../../../learn/security/authentication/) used to run the query must have `read` privileges for the referenced document’s collection. This requirement applies even if the UDF’s `@role` has `read` privileges for the collection.

For example, the following UDF returns a Set of documents. Each document contains a document reference:

```fsl
// Runs with the built-in `server-readonly` role's privileges.
// The role has `read` privileges for the `Category` collection.
@role("server-readonly")
function getCategory(name) {
  // Returns the `category` field, which contains
  // a reference to a `Category` collection document.
  Product.byName(name) {
    name,
    category
  }
}
```

If you call the UDF using a secret that lacks `read` privileges for the referenced document’s collection, the reference is not resolved in the results:

```fql
getCategory("limes")
```

```
{
  data: [
    {
      name: "limes",
      category: Category("789") /* permission denied */
    }
  ]
}
```

Although the UDF’s `@role` has the required privileges, document references in Sets and documents are lazily loaded. The references are resolved, or materialized, only when results are returned — after the UDF runs.

To solve this issue without granting additional privileges, update the UDF to:

*   [Project](../../fql/projection/) or [map](../../fql-api/set/map/#project) any desired fields from the referenced document.
    
*   Convert the results to an eager-loading type, such as an [Array](../../fql/types/#array) or [Object](../../fql/types/#object).
    

##### [](#return-a-set-as-an-array)Return a Set as an array

If the UDF originally returned a Set of documents, update it to return the Set as an array:

```fsl
@role("server-readonly")
function getCategory(name) {
  // Project any desired fields from the referenced
  // `Category` document.
 let products = Product.byName(name) {
    name,
    category {
      id,
      ts,
      name,
      description
    }
  }

  // Convert the Set to an array.
  products.toArray()
}
```

When called using a secret that lacks privileges on the referenced documents' collection:

```fql
getCategory("limes")
```

```
[
  {
    name: "limes",
    category: {
      id: "789",
      ts: Time("2099-12-12T14:22:31.560Z"),
      name: "produce",
      description: "Fresh Produce"
    }
  }
]
```

##### [](#return-a-document-as-an-object)Return a document as an object

If the UDF originally returned a single document, update it to return the document as an object instead:

```fsl
@role("server-readonly")
function getCategory(name) {
  // Project any desired fields from the referenced
  // `Category` document.
 let product = Product.byName(name).first() {
    name,
    category {
      id,
      ts,
      name,
      description
    }
  }

  // Convert the Document to an object.
  Object.assign({}, product)
}
```

When called using a secret that lacks privileges on the referenced document’s collection:

```fql
getCategory("limes")
```

```
{
  name: "limes",
  category: {
    id: "789",
    ts: Time("2099-12-13T16:25:53Z"),
    name: "produce",
    description: "Fresh Produce"
  }
}
```

### [](#pass-a-collection-as-an-argument)Pass a collection as an argument

The following example passes a collection name as an argument. Use [`Collection()`](../../fql-api/collection/coll-type/) to dynamically specify collection names in a query:

```fsl
// Accepts a collection name as an argument.
function getPriceLowtoHigh(collection) {
  // Uses `Collection()` to dynamically specify
  // the collection name.
  Collection(collection).sortedByPriceLowToHigh() {
    price,
    name,
    description
  }
}
```

The following query calls the function:

```fql
// Calls the `getPriceLowtoHigh()` UDF with
// a `Product` collection argument.
getPriceLowtoHigh("Product")
```

# FSL role schema

| Learn: Roles |
| --- | --- | --- |

An FSL role schema defines a [user-defined role](../../../learn/security/roles/#user-defined-role).

Fauna uses [secrets](../../../learn/security/authentication/#secrets) for authentication and authorization. Roles determine a secret’s privileges, which control data access.

```fsl
role manager {

  membership Manager

  membership User {
    predicate (user => user.accessLevel == 'manager')
  }

  privileges Product {
    create
    read
    write
    delete
  }

  privileges User {
    read {
      predicate (doc => Query.identity() == doc)
    }
  }

  privileges getOrCreateCart {
    call
  }

  privileges checkout {
    call {
      predicate ((args) => {
        let order = Order.byId(args[0])!
        order?.customer == Query.identity()
      })
    }
  }
}
```

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

*   The [Fauna CLI](../../../learn/schema/manage-schema/#staged)
    
*   The [Fauna Dashboard](https://dashboard.fauna.com/)
    
*   The Fauna Core HTTP API’s [Schema endpoints](../../http/reference/core-api/#tag/Schema)
    
*   [FQL schema methods](../../../learn/schema/manage-schema/#fql)
    

Fauna stores each role schema as an FQL document in the [`Role`](../../fql-api/role/) system collection.

## [](#fsl-syntax)FSL syntax

```fsl-sig
role <role> {
  [membership <collection> [{
    predicate <predicate>
  }] . . .]

  [privileges <resource> {
    <action> [{
      predicate <predicate>
    }] . . .
  } . . .]
}
```

## [](#name)Name

_role_ **Required**

Unique name for the role in the database.

Must begin with a letter. Can only include letters, numbers, and underscores. `admin`, `server`, and `server-readonly` are reserved and can’t be used.

## [](#properties)Properties

| Property | Required | Description |
| --- | --- | --- | --- | --- |
| membership |  | Assigns the role to tokens based on the token’s identity document. See Membership definition. |
| privileges |  | Allows one or more actions on a resource. See Privileges definition. |

## [](#membership-definition)Membership definition

```fsl
role manager {
  membership Manager

  membership User {
    predicate (user => user.accessLevel == 'manager')
  }
  ...
}
```

| Property | Required | Description |
| --- | --- | --- | --- | --- |
| collection | true | Name of a user-defined collection.Fauna assigns the role to tokens with an identity document in the collection. |
| predicate |  | Predicate used to conditionally assign the role. If the predicate is not true, the role is not assigned.The predicate is passed one argument: an object containing the token’s identity document.The predicate runs with the built-in server role’s privileges. Supports shorthand syntax. |

## [](#privileges-definition)Privileges definition

```fsl
role manager {
  ...
  privileges Product {
    create
    read
    write
    delete
  }

  privileges User {
    read {
      predicate (doc => Query.identity() == doc)
    }
  }
  ...
}
```

| Property | Required | Description |
| --- | --- | --- | --- | --- |
| resource | true | Name of a collection or user-defined function (UDF). Supports user-defined collections and the following system collections:AccessProviderCollectionCredentialDatabaseFunctionKeyRoleTokenread privileges grants the ability to call the collection’s indexes. |
| action | true | Type of operation allowed on the resource. Privileges support different actions based on the resource type. See Privilege actions. |
| predicate |  | Predicate used to conditionally grant the privilege. If the predicate is not true, the privilege is not granted.Privilege predicates are passed different arguments based on their action. See Privilege predicate arguments.The predicate runs with the built-in server role’s privileges. Supports shorthand syntax. |

### [](#privilege-actions)Privilege actions

Privileges support different actions based on their resource type.

| Resource type | Action | Allows you to …​ |
| --- | --- | --- | --- | --- |
| Collection | create | Create documents in the collection. To create documents with a custom id, you must also have the create_with_id privilege. |
| Collection | delete | Delete documents in the collection. |
| Collection | read | Read documents in the collection. Can also call the collection’s indexes. To read historical document snapshots, you must also have the history_read privilege. |
| Collection | write | Update or replace documents in the collection. |
| Collection | create_with_id | Create documents with a custom id in the collection. You must also have the create privilege. |
| Collection | history_read | Read snapshots for documents in the collection. See Run a temporal query. |
| User-defined function (UDF) | call | Call the function. |

### [](#privilege-predicate-arguments)Privilege predicate arguments

Privilege predicates are passed different arguments based on their action.

| Action | Predicate function signature |
| --- | --- | --- | --- |
| create | (doc: Object) => Boolean | Null doc: Object containing the document to create. Includes metadata fields. |
| delete | (doc: Object) => Boolean | Null doc: Object containing the document to delete. Includes metadata fields. |
| read | (doc: Object) => Boolean | Null doc: Object containing the document to read. Includes metadata fields. |
| write | (oldDoc: Object, newDoc: Object) => Boolean | Null oldDoc: Object containing the original document. Includes metadata fields.newDoc: Object containing the document to write. Includes metadata fields. |
| create_with_id | (doc: Object) => Boolean | Null doc: Object containing the document to create. Includes metadata fields. |
| history_read | (doc: Object) => Boolean | Null doc: Object containing the document to read. Includes metadata fields. |
| call | (args: Array) => Boolean | Null args: Array containing the function call’s arguments. |

## [](#examples)Examples

```fsl
role manager {

  // Assign the `manager` role to tokens with
  // an identity document in the `Manager` collection.
  membership Manager

  // If the predicate is `true`,
  // assign the `manager` role to tokens with
  // an identity document in the `User` collection.
  membership User {
    // Check that the identity document's
    // `accessLevel` field value is `manager`
    predicate (user => user.accessLevel == 'manager')
  }

  // Grant full access to `OrderItem` collection documents.
  privileges OrderItem {
    create
    read
    write
    delete
  }

  // Grant `read` access to `Customer` collection documents.
  privileges Customer {
    read
  }

  // If the predicate is `true`,
  // grant `read` access to `Manager` collection documents.
  privileges Manager {
    read {
      predicate (doc =>
        // Check that the `ManagerProfile` document
        // is the token's identity document.
        // `Query.identity()` is `null` (falsy) for JWTs or keys.
        Query.identity() == doc &&
        // Check that it's a weekday.
        Date.today().dayOfWeek < 6
      )
    }
  }

  // Grant the ability to call the user-defined
  // `getOrCreateCart()` function.
  privileges getOrCreateCart {
    call
  }

  // If the predicate is `true`,
  // grant the ability to call the user-defined
  // `submitOrder()` function.
  privileges checkout {
    call {
      // Check that the `orderId` (`args[0]`) belonds to the user.
      // `Query.identity()` is `null` for JWTs or keys.
      predicate ((args) => {
        let order = Order.byId(args[0])!
        order?.customer == Query.identity()
      })
    }
  }
}
```