Delete database entities

This tutorial deletes in order:

  1. A document field.

  2. A document in the collection.

  3. The collection.

Create database entities for this tutorial

To preserve the CoffeeBean collection for the following tutorials, better show the scope of delete operations, and provide a self-contained example, this tutorial first creates and populates another arbitrary collection.

Create a temporary collection

Similar to how you created a collection in the Populate the cookbook database tutorial, create a collection.

  1. In the Dashboard Explorer page, under your Region Group, choose the Cookbook database.

  2. In the left-bottom panel, choose Collections and click the plus (+) symbol to the right of the Cookbook database.

  3. Create a collection of information about stores. In the Create Collection dialog, enter Store for the collection Name.

  4. Leave all other fields in their default state and click the CREATE button.

    You should see the Store collection added to your database, and if you select the Store collection, you should see an empty collection in the Shell:

collection Store {
  history_days 0
}

Add documents to the temporary collection

  1. In the Shell for the Cookbook database, add three documents with the following queries:

    Store.create({
  name: "DC Fruits",
  address: {
    street: "13 Pierstorff Drive",
    city: "Washington",
    state: "DC",
    zipCode: "20220"
  }
})

    Store.create({
  name: "Party Supplies",
  address: {
    street: "7529 Capitalsaurus Court",
    city: "Washington",
    state: "DC",
    zipCode: "20002"
  }
})

    Store.create({
  name: "Foggy Bottom Market",
  address: {
    street: "4 Florida Ave",
    city: "Washington",
    state: "DC",
    zipCode: "20037"
  }
})

  2. Confirm that the Store collection is now populated with three documents by selecting the Store collection in the Dashboard and viewing the Documents list or by running the following query:

    Store.all()
    {
  data: [
    {
      id: "378661942830563393",
      coll: Store,
      ts: Time("2023-10-15T14:10:19.500Z"),
      name: "DC Fruits",
      address: {
        street: "13 Pierstorff Drive",
        city: "Washington",
        state: "DC",
        zipCode: "20220"
      }
    },
    {
      id: "378662034803261505",
      coll: Store,
      ts: Time("2023-10-15T14:11:47.230Z"),
      name: "Party Supplies",
      address: {
        street: "7529 Capitalsaurus Court",
        city: "Washington",
        state: "DC",
        zipCode: "20002"
      }
    },
    {
      id: "378662129421516865",
      coll: Store,
      ts: Time("2023-10-15T14:13:17.455Z"),
      name: "Foggy Bottom Market",
      address: {
        street: "4 Florida Ave",
        city: "Washington",
        state: "DC",
        zipCode: "20037"
      }
    }
  ]
}

The rest of this tutorial shows how to delete database elements and finishes with deleting the Store collection.

Delete a field

Delete a field in a document by setting its value to null.

Using the document id of one of the documents in your Store collection to get the document, use the following query to delete the address field:

Store.byId("378661942830563393")!.update(
  { address: null }
)
{
  id: "378661942830563393",
  coll: Store,
  ts: Time("2023-10-15T14:33:05.890Z"),
  name: "DC Fruits"
}

The response shows that the address field is deleted, and you can run Store.all() to view the updated store data.

Remember that deleted fields aren’t saved by Fauna.

Delete a document

To delete the full document and remove it from the collection, call the delete() method on the document instance. Again, use a document id from your Store collection:

Store.byId("378662129421516865")!.delete()
Store.byId("378662129421516865") /* not found */

The not found response confirms that the document is deleted. Run Store.all() to see that there are now two documents in the collection.

If you delete a document referenced by another document, the referencing document field is replaced with a Deleted placeholder that shows that the document is deleted but the reference still exists. Try this example:

  1. Create two collections:

    Collection.create({ name: "Foo" })
Collection.create({ name: "Bar" })

  2. Create a document in both collections such that one document references the document in the other collection:

    Foo.create({ other: Bar.create({}) })
    {
  id: "380934695755448388",
  coll: Foo,
  ts: Time("2023-11-09T16:14:45.570Z"),
  other: Bar.byId("380934695754399812")
}

  3. Delete the referenced document:

    Bar.definition.delete()

  4. View the document definition of the referencing document:

    Foo.byId("380934695755448388")
    {
  id: "380934695755448388",
  coll: Foo,
  ts: Time("2023-11-09T16:14:45.570Z"),
  other: Deleted.byId("380934695754399812")
}

    The document referenced as other is deleted but the reference still exists.

Delete a collection

You delete a collection by deleting the collection definition, which describes the schema for the collection. To view the Store collection definition, run Store.definition.

To delete the collection, run the following query:

Store.definition.delete()
Collection.byName("Store") /* not found */

The not found response confirms that the collection is deleted.

Deleting a collection deletes its indexes, user-defined functions, and all documents in the collection.

Run Collection.all() to list the current collections in the system, confirming that the Store collection no longer exists.

Delete other database entities

See the Use indexes for more efficient queries tutorial for how to delete an index and see the Write custom logic with UDFs tutorial for how to delete a user-defined function.

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!