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?,
}?
}
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> |
Yes |
Accepted data types for the field.
Separate multiple types by Types must be persistable.
Use The Fields that accept Null are not guaranteed to exist in every document of the collection. |
|
<defaultValue> |
Default field value. Used if the field is missing or the field value is
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
}
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.
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!