Documents
Reference: | Document |
---|
You add data to Fauna as JSON-like objects called documents. A document is a single, changeable record in a Fauna database. Each document belongs to a collection.
All user data is stored in documents, and every entity in the Fauna data model, including Database, Collection, and Function, is defined in a document.
Storing data in documents instead of rows and columns gives you greater flexibility. It allows you to shape your data in the way that best fits your applications instead of writing your applications to fit the data. Every record in a Fauna database is grouped and stored as a Document object, consisting of key:value pairs. A key can be a document.
Data stored in a document looks similar to a JSON document and can include strings, integers, arrays, and other data types. Documents include:
-
a timestamp
-
the name of their collection
-
a string-encoded integer used as a document ID.
Documents changes create a new version of the document, which supports temporal querying.
See the Global limits for more information on document size and transaction limits.
Document type
A document’s data type is taken from its collection’s name. For example,
Product
for a document in the Product
collection. This type is an instance
of the Document type, which is a subtype of the Object type.
You define the structure of a collection’s document type using the collection schema’s:
See Document type definitions |
---|
Document metadata
All documents have these common metadata fields:
-
Documents have a string-encoded 64-bit integer identifier. A document ID is a compound value of a collection identifier and a unique document ID. The ID is a unique identifier for the document in the scope of the database where it is stored.
-
When a document is updated, a new version is stored. User documents have a timestamp that identifies the most recent document update. Documents are versioned, and the versions are distinguished using a timestamp. When a query doesn’t specify a timestamp, the latest version of the document is used. The timestamp is returned in the document
ts
field. -
The
ts
field shouldn’t be directly manipulated. To track timestamps independent of Fauna operations, include fields that are under your control in your documents to record timestamps. -
Documents have an optional
ttl
(time-to-live) field that indicates when the document should be removed. See Document time-to-live (TTL).
CRUD operations on documents
Every document object has the following methods:
Method | Description |
---|---|
Deletes the document, returning the |
|
Tests if a given document exists. |
|
Fully replaces the document data with the provided data. Fields are removed if they aren’t present in the provided data. |
|
Updates the document with the provided data and returns the updated
document. This does a patch update. Omitted fields are left as-is. To
remove fields from a document, set the field value to |
NullDoc
A NullDoc is a marker used to indicate that a document doesn’t exist or is inaccessible.
A NullDoc’s data type is taken from its collection’s name. For example, a
NullDoc for a Product
collection document is NullProduct
. NullDocs always
contains a null
value.
Several FQL methods, such as
collection.byId()
, return
a NullDoc for missing or inaccessible documents:
// Attempts to access a `Product` collection document
// with an `id` of `401697070347452493`. In this
// example, the document doesn't exist.
Product.byId("401697070347452493")
// Returns a `NullProduct` value.
Product("401697070347452493") /* not found */
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!