FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

Delete

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
Delete( ref )
delete( ref )
Delete( ref )
Delete( ref )
Delete( ref )
Delete( ref )

Description

The Delete function removes a document. This includes user-created documents, plus system documents for Collections, Indexes, Databases, etc.

When you delete a Database, all of its documents, Collections, child Databases, Functions, Indexes, Keys, Roles, and Tokens are also deleted.

When you delete a Collection, all documents within the Collection are also deleted.

When you delete a Collection that is the single source for an index, the index is also deleted.

There is no cascading delete for user-defined documents. If you have a document "A" that includes a reference to another document "B", deleting "A" does not affect "B", and deleting "B" does not affect "A". You would have to write your own query logic to automatically follow references to perform a cascading delete.

For performance, the documents describing AccessProviders, Databases, Collections, Functions, Indexes, Keys, Roles, and Tokens use an object cache. When you use Delete to modify any of these Fauna schema documents, the modification is not guaranteed to be visible immediately.

This does not apply to non-schema documents, such as those in a user-created collection. Non-schema documents are always modified or removed in a strongly consistent manner.

Parameters

Parameter Type Definition and Requirements

ref

Reference

The Reference to an object that should be removed.

Returns

An object representing the just-deleted document, containing all of the document’s fields and values.

All deleted documents return the following fields:

Field Name Field Type Definition and Requirements

ref

Reference

The reference to the now-deleted document.

ts

Long

The timestamp of the most recent update of the document, prior to its deletion.

All document fields are returned, but documents can have varying sets of fields. For example, not all documents have a data field; those documents that do not contain a data field do not return a data field upon deletion.

Examples

The following query removes the document pointed at by the reference:

client.query(
  q.Delete(q.Ref(q.Collection('spells'), '181388642581742080'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Collection("spells"), "181388642581742080"),
  ts: 1592054525870000,
  data: { name: "Mountain's Thunder", element: 'air', cost: 15 }
}
result = client.query(
    q.delete(q.ref(q.collection("spells"), "181388642581742080"))
)
print(result)
{'ref': Ref(id=181388642581742080, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592857155330000, 'data': {'name': "Mountain's Thunder", 'element': 'air', 'cost': 15}}
result, err := client.Query(
	f.Delete(f.Ref(f.Collection("spells"), "181388642581742080")))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:map[cost:15 element:air name:Mountain's Thunder] ref:{181388642581742080 0xc00012c2a0 0xc00012c2a0 <nil>} ts:1603747152880000]
try
{
    Value result = await client.Query(
        Delete(Ref(Collection("spells"), "181388642581742080"))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "181388642581742080", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1603756243560000),data: ObjectV(name: StringV(Mountain's Thunder),element: StringV(air),cost: LongV(15)))
System.out.println(
    client.query(
        Delete(Ref(Collection("spells"), Value("181388642581742080")))
    ).get());
{ref: ref(id = "181388642581742080", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1594315444820000, data: {name: "Mountain's Thunder", element: "air", cost: 15}}
Delete(Ref(Collection('spells'), '181388642581742080'))
{
  ref: Ref(Collection("spells"), "181388642581742080"),
  ts: 1624310394670000,
  data: { name: "Mountain's Thunder", element: 'air', cost: 15 }
}
Query metrics:

  •    bytesIn:   68

  •   bytesOut:  223

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   99

  • writeBytes:  659

  •  queryTime: 33ms

  •    retries:    0

After deletion, the document can no longer be retrieved:

client.query(
  q.Get(q.Ref(q.Collection('spells'), '181388642581742080'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
Error: [NotFound] instance not found: Document not found.
try:
  result = client.query(
    q.get(q.ref(q.collection("spells"), "181388642581742080"))
  )
  print(result)
except e.NotFound as err:
  print(err)
ErrorData(code='instance not found', description='Document not found.', position=[], failures=None)
result, err := client.Query(
	f.Get(f.Ref(f.Collection("spells"), "181388642581742080")))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
Response error 404. Errors: [](instance not found): Document not found., details: []
try
{
    Value result = await client.Query(
        Get(Ref(Collection("spells"), "181388642581742080"))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ERROR: instance not found: Document not found.
try {
    System.out.println(
        client.query(
            Get(Ref(Collection("spells"), Value("181388642581742080")))
        ).get());
} catch (Exception e) {
    System.out.println("ERROR " + e.getMessage());
}
ERROR com.faunadb.client.errors.NotFoundException: instance not found: Document not found.
Get(Ref(Collection('spells'), '181388642581742080'))
{
  errors: [
    {
      position: [
        'do',
        1
      ],
      code: 'instance not found',
      description: 'Document not found.'
    }
  ]
}
Query metrics:

  •    bytesIn:  65

  •   bytesOut:  92

  • computeOps:   1

  •    readOps:   0

  •   writeOps:   0

  •  readBytes:   0

  • writeBytes:   0

  •  queryTime: 4ms

  •    retries:   0

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!