Field definitions

Learn: Schema

Field definitions and schema migrations are in beta.

A schema migration is required to change a collection’s field definitions or wildcard constraint. By performing a schema migration, you automatically opt-in to the beta.

During beta, schema migrations triggers a rebuild of all of a collection’s indexes. This can make large indexes unusable for extended periods.

To register for the beta and sign up for production support, go to https://go.fauna.com/schemabetaproductionsupport.

Field definitions define fields for a collection's documents.

Field definitions are part of a collection’s document type definition.

collection Order {
  status: String? // Equivalent to `status: String | Null`
  cart: Array<{
    product: Ref<Product>?,
    quantity: Int?,
    price: Double?,
  }>?
  creationDate: Time = Time.now()
  deliveryAddress: {
    street: String?,
    city: String?,
    state: String?,
    zipCode: String?,
  }?
  creditCard: {
    network: "Visa" | "MasterCard" | "American Express"?,
    number: String?,
  }?
}

Syntax

<fieldName>: <types>[ = <defaultValue>]

Name

fieldName String Required

Document field name.

Use a wildcard (*) constraint to specify accepted data types for ad hoc fields. See Wildcard constraints.

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 collection’s documents as a data type. 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 if the field is missing or the field value is null.

Can be an FQL expression. The expression can have no effect other than to:

Fauna evaluates the expression at write time.

You can use a document as a default value. See Default to a document.

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:

collection Order {
  // Only accept ad hoc fields with `String` or `Int` values
  *: String | Int
}

Ad hoc fields must conform to the wildcard constraint’s accepted data types.

A collection can only have one wildcard constraint. You can’t specify a default value for a wildcard.

A wildcard constraint is part of a collection’s document type definition.

Schemaless by default

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

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

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

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.

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

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.

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

Examples

Arrays

Use Array<…​> to accept Array values:

collection Product {
  categories: Array<String>?
}

To accept an object array:

collection Customer {
  addresses: Array<{
    street: String?,
    city: String?,
    state: String?,
    zipCode: String?,
  }>?
}

Default to today’s date

Use Date.today() to set today’s date as a default value:

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

Fauna evaluates the expression at write time.

Default to the current time

Use Time.now() to set the current time as a default value:

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

Fauna evaluates the expression at write time.

Default to a unique ID

Use newId() to use a unique ID as the default value. You must cast the ID to a String using toString():

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

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

Default to a document

You can use a document as a backfill value:

collection Product {
  // Default `store` to a `Store` collection document.
  // Replace `400684606016192545` with a `Store` document ID.
  store: Ref<Store> = Store("400684606016192545")
}

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

Document relationships

Use Ref<CollectionName> to accept a collection’s documents as a data type:

collection Product {
  // Accepts `Store` collection documents and `null`
  store: Ref<Store>?
}

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

Enumerated field values

To accept enumerated values:

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

Nested objects

To define a field containing a nested object:

collection Order {
  deliveryAddress: {
    street: String?,
    city: String?,
    state: String?,
    zipCode: String?,
  }?
}

See also

collection
Migrations block

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!