Basic CRUD operations

If you’re new to Fauna Query Language, basic CRUD operations are a good place to get started with learning the language. This page provides examples of creating, reading, updating, and deleting documents in a Fauna collection.

About documents

In Fauna, a document is the basic unit of information. All information is stored in documents, which are in turn stored in collections. Even the building blocks of Fauna, such as databases, indexes, and user-defined functions, are all defined in documents.

To learn more about documents, see Documents in the Understanding Fauna section.

Creating documents

For the purposes of this guide, we’ll use a collection called fruit in a database called myDb. If you need help getting started with creating databases and collections in the Fauna Dashboard, please see the Dashboard quick start.

To create a new document, use the Create function. Create takes two parameters: a collection in which to create the document, and an object which contains user-specifed data and additional optional parameters.

In the following example, a new document is created in the fruit collection:

The C# version of this example is not currently available.
The Go version of this example is not currently available.
The Java version of this example is not currently available.
client.query(
  q.Create(
    q.Ref(q.Collection('fruit'), '1'),
    {
      data: {
        type: 'apple',
        colors: ['red', 'green'],
        quantity: 15,
      },
    },
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Collection("fruit"), "1"),
  ts: 1641328117890000,
  data: { type: "apple", colors: ["red", "green"], quantity: 15 }
}
The Python version of this example is not currently available.
The Shell version of this example is not currently available.
Query metrics:

  •    bytesIn:  146

  •   bytesOut:  205

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   14

  • writeBytes:  224

  •  queryTime: 19ms

  •    retries:    0

Note that the return value for Create contains the complete document, including a Ref which uniquely identifies the new document and a creation timestamp.

Reading documents

Any Fauna document can be retrieved with its Ref. To read a single document, use the Get function. Get takes two parameters: a Ref, and (optionally) a timestamp. The timestamp parameter is useful if you want to retrieve an older version of a document (see Temporality for more information).

The following example reads the new document created in the above example.

The C# version of this example is not currently available.
The Go version of this example is not currently available.
The Java version of this example is not currently available.
client.query(
  q.Get(q.Ref(q.Collection('fruit'), '1')),
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Collection("fruit"), "1"),
  ts: 1641328117890000,
  data: { type: "apple", colors: ["red", "green"], quantity: 15 }
}
The Python version of this example is not currently available.
The Shell version of this example is not currently available.
Query metrics:

  •    bytesIn:  47

  •   bytesOut: 205

  • computeOps:   1

  •    readOps:   1

  •   writeOps:   0

  •  readBytes:  88

  • writeBytes:   0

  •  queryTime: 5ms

  •    retries:   0

You can retrieve multiple documents by their Refs with by grouping Get functions in an array, as the following example demonstrates:

The C# version of this example is not currently available.
The Go version of this example is not currently available.
The Java version of this example is not currently available.
client.query([
  q.Get(q.Ref(q.Collection('fruit'), '1')),
  q.Get(q.Ref(q.Collection('fruit'), '2')),
  q.Get(q.Ref(q.Collection('fruit'), '3')),
])
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
[
  {
    ref: Ref(Collection("fruit"), "1"),
    ts: 1641328117890000,
    data: { type: "apple", colors: ["red", "green"], quantity: 15 }
  },
  {
    ref: Ref(Collection("fruit"), "2"),
    ts: 1641334768347000,
    data: { type: "grapes", colors: ["red", "green"], quantity: 600 }
  },
  {
    ref: Ref(Collection("fruit"), "3"),
    ts: 1641334747325000,
    data: { type: "banana", colors: ["yellow", "green"], quantity: 50 }
  }
]
The Python version of this example is not currently available.
The Shell version of this example is not currently available.
Query metrics:

  •    bytesIn: 145

  •   bytesOut: 599

  • computeOps:   1

  •    readOps:   3

  •   writeOps:   0

  •  readBytes: 272

  • writeBytes:   0

  •  queryTime: 7ms

  •    retries:   0

Updating documents

To update a document, use the Update function. Update takes two parameters: a Ref which identifies the document to be updated, and a parameter object which contains new data for the document and other optional parameters.

Update performs a partial update on a document. If you specify an existing field, that field is updated with new data. If you specify new fields, those fields are added to the document. Any fields which exist in the document but are not specified in the Update operation are left unmodified. To replace an existing document’s entire data object, use the Replace function. Fauna does not have a dedicated function for an upsert operation, which updates a document if it exists and creates it if it doesn’t, but it’s possible to perform an upsert with a composed query. See the cookbook recipe for details. 
The C# version of this example is not currently available.
The Go version of this example is not currently available.
The Java version of this example is not currently available.
client.query(
  q.Update(
    q.Ref(q.Collection('fruit'), '1'),
    {
      data: {
        quantity: 75,
      },
    },
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
    ref: Ref(Collection("fruit"), "1"),
    ts: 1641328117890000,
    data: { type: "apple", colors: ["red", "green"], quantity: 75 }
  }
The Python version of this example is not currently available.
The Shell version of this example is not currently available.
Query metrics:

  •    bytesIn:  106

  •   bytesOut:  205

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   88

  • writeBytes:  117

  •  queryTime: 20ms

  •    retries:    0

As with other CRUD functions, you can perform multiple updates in a single operation by grouping Update functions in an array.

Deleting documents

To delete a document, use the Delete function. Delete takes a single parameter: the Ref of the document to be deleted.

The C# version of this example is not currently available.
The Go version of this example is not currently available.
The Java version of this example is not currently available.
client.query(
  q.Delete(q.Ref(q.Collection('fruit'), '1'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Collection("fruit"), "1"),
  ts: 1641328117890000,
  data: { type: "apple", colors: ["red", "green"], quantity: 75 }
}
The Python version of this example is not currently available.
The Shell version of this example is not currently available.
Query metrics:

  •    bytesIn:   50

  •   bytesOut:  205

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:  191

  • writeBytes:  237

  •  queryTime: 27ms

  •    retries:    0

The return value of a Delete operations contains the deleted document, including its most recent timestamp.

Other schema objects

It is also possible to use the Create, Get, Update and Delete functions on other Fauna schema objects, such as collections, databases, and indexes. For more information and examples, see the Fauna Cookbook’s basic operations section.

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!