Delete documents

Deletion in DefraDB works differently than in most other databases. Because the history of documents is append-only, the deletion of a document is registered just as another record in the history. Queries don't return deleted documents though, unless the query explicitly requests deleted documents. In other words: the details of a deleted document are still available, but queries ignore its existence when retrieving results. The only way to permanently delete a document is to truncate the collection it belongs to.

Syntax

Similarly to the update_TYPE mutation to update documents, you delete documents via the delete_TYPE mutation. The mutation returns the deleted documents.

Syntax – Delete mutation

mutation {
  delete_TYPE(docID: [ID], filter: filterObj) [TYPE]
}

• docID – DocID of the document(s) to delete. Either a string or a list of strings.
• filter – Criteria for selecting documents to delete (see Filter documents).

If both filter and docID are given, both criteria must be fulfilled for a document to be selected.

note

You cannot restore a deleted document, nor re-create a document with the exact same content as a previously deleted one, because the docID would conflict. In case you need to re-create a deleted document, create a new document with only some of the fields of the deleted document, and then update it to include all the wished information.

Examples

Display database setup

This page assumes your database contains Book and Person collections and some documents in them:

Database schema

type Person {
  name: String!
  authoredBooks: [Book]
}

type Book {
  title: String!
  genre: String
  plot: String
  rating: Float
  author: Person
}

Person documents setup

mutation {
  a1:add_Person(input: {
    name: "George Orwell"
  }) { _docID }
  a2:add_Person(input: {
    name: "William Golding"
  }) { _docID }
  a3:add_Person(input: {
    name: "David Foster Wallace"
  }) { _docID }
  a4:add_Person(input: {
    name: "Victor Hugo"
  }) { _docID }
}

Book documents setup

mutation {
  b11:add_Book(input: {
    title: "1984",
    genre: "Dystopia",
    plot: "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
    rating: 4.20,
    _authorID: "bae-3517d1eb-351b-5231-8387-870893ffb395"
  }) {
    _docID
    title
  }
  b12:add_Book(input: {
    title: "Down and Out in Paris and London",
    genre: "Biography",
    plot: "The adventures of a penniless British writer among the down-and-outs of two great cities.",
    rating: 4.09,
    _authorID: "bae-3517d1eb-351b-5231-8387-870893ffb395"
  }) {
    _docID
    title
  }
  b21:add_Book(input: {
    title: "Lord of the Flies",
    genre: "Dystopia",
    plot: "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
    rating: 3.70,
    _authorID: "bae-78e9c7be-10b9-5673-bad2-da3341367d4b"
  }) {
    _docID
    title
  }
  b31:add_Book(input: {
    title: "Infinite Jest",
    genre: "Fiction",
    plot: "A gargantuan, mind-altering tragi-comedy about the Pursuit of Happiness in America.",
    rating: 4.25
    _authorID: "bae-b59928dc-fd05-5fb7-aea2-9b24af5ebcea"
  }) {
    _docID
    title
  }
  b32:add_Book(input: {
    title: "Consider the Lobster and Other Essays",
    genre: "Nonfiction",
    plot: "Do lobsters feel pain? Did Franz Kafka have a funny bone? What is John Updike's deal, anyway? And what happens when adult video starlets meet their fans in person? Essays that are also enthralling narrative adventures.",
    rating: 4.18,
    _authorID: "bae-b59928dc-fd05-5fb7-aea2-9b24af5ebcea"
  }) {
    _docID
    title
  }
  b41:add_Book(input: {
    title: "Les Misérables",
    genre: "Fiction",
    plot: "Victor Hugo's tale of injustice, heroism and love follows the fortunes of Jean Valjean, an escaped convict determined to put his criminal past behind him.",
    rating: 4.21,
    _authorID: "bae-c169e917-df52-5603-9224-39c1757f1b04"
  }) {
    _docID
    title
  }
}

Eliminate the dystopians

mutation {
  delete_Person(
    filter: { authoredBooks: { genre: { _eq: "Dystopia" } } } 
  ) {
    _docID
    name
  }
}

Result

{
  "data": {
    "delete_Person": [
      {
        "_docID": "bae-3517d1eb-351b-5231-8387-870893ffb395",
        "name": "George Orwell"
      },
      {
        "_docID": "bae-78e9c7be-10b9-5673-bad2-da3341367d4b",
        "name": "William Golding"
      }
    ]
  }
}

It looks like power has eliminated the dystopians, as a regular query does not return them as existing people.

The dystopians are gone

{
  Person(filter: { authoredBooks: { genre: { _eq: "Dystopia"} } } ) {
    name
  }
}

Result

{
  "data": {
    "Person": []
  }
}

True dystopians are however never erased. Deleted documents show up if the query requests to include them with showDeleted: true. The _deleted return field marks whether a document is deleted.

The dystopians are gone

{
  Person(
    filter: { authoredBooks: { genre: { _eq: "Dystopia"} } },
    showDeleted: true
  ) {
    _deleted
    name
  }
}

Result

{
  "data": {
    "Person": [
      {
        "_deleted": true,
        "name": "George Orwell"
      },
      {
        "_deleted": true,
        "name": "William Golding"
      }
    ]
  }
}