Delete

Delete( ref )
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, Databases, Collections, Functions, Indexes, Keys, and Roles use an object cache. When you use Delete to delete any of these Fauna schema documents, the deletion is not guaranteed to be visible immediately.

Parameters

Argument Type Definition and Requirements

ref

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

The reference to the now-deleted document.

ts

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:

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)))
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]
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}}
client.query(
  q.Delete(q.Ref(q.Collection('spells'), '181388642581742080'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))
{
  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}}
try {
  println(Await.result(
    client.query(Delete(Ref(Collection("spells"), "181388642581742080"))),
    5.seconds
  ))
} catch {
  case unknown: Throwable => println("Error: " + unknown.getMessage())
}
{ref: ref(id = "181388642581742080", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1594485251730000, 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:

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.
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 {
    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.
client.query(
  q.Get(q.Ref(q.Collection('spells'), '181388642581742080'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s: %s', err.name, err.message))
Error: NotFound: instance 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)
val result = client.query(
  Get(Ref(Collection("spells"), "181388642581742080"))
).recover {
  case error: Any => "Error: " + error.getMessage()
}
println(Await.result(result, 5.seconds))
Error: 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

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!