Skip to main content
Version: 1.0 RC1 (Latest)

Create new documents

Once you have created collections, you can start adding documents into them.

Display database setup

This page assumes your database contains Book and Person collections:

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

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

Create one new document​

To create documents of type <type>, use the mutation add_<type> via the CLI command defradb client query. For example, to create a document in the Book collection, use add_Book.

Every add_<type> mutation must return some of the inserted information. Because GraphQL queries only return the exact fields requested, you have to provide a list of return fields (there is no equivalent of the SQL SELECT * syntax).

Create a new document of type "Book"
defradb client query '
  mutation {
    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
    }) {
      _docID
      title
    }
  }
'
Result
{
  "data": {
    "add_Book": [
      {
        "_docID": "bae-ad13cbb3-0970-5e1d-8096-620f7bd27d26",
        "title": "Infinite Jest"
      }
    ]
  }
}

The document ID​

The field _docID is the document's unique identifier, determined by the collection it belongs to and the data it is initialized with. The data in the document might change over time, but its docID will stay the same.

tip

The _docID field is automatically indexed.

Create documents with relationships​

To add documents with relationships to each other, you need two queries: one to create the documents, and another to link them together via their docIDs.

For example, to create a book and link it to an author, first create the documents and return their docIDs:

Create new documents for "Person" and "Book"
mutation {
  add_Person(input: {
    name: "Victor Hugo"
  }) {
    _docID
    name
  }
  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
  }) {
    _docID
    title
  }
}
Result
{
  "data": {
    "add_Book": [
      {
        "_docID": "bae-e1dcefa0-46ca-5ae5-bc0a-859f2e7e1259",
        "title": "Les Misérables"
      }
    ],
    "add_Person": [
      {
        "_docID": "bae-c169e917-df52-5603-9224-39c1757f1b04",
        "name": "Victor Hugo"
      }
    ]
  }
}

To link them, use an update mutation to set the field _authorID on Book with the docID from the desired Person:

Link book and author via Book._authorID
mutation {
  update_Book(
    docID: "bae-e1dcefa0-46ca-5ae5-bc0a-859f2e7e1259",
    input: {  # properties to be altered
      _authorID: "bae-c169e917-df52-5603-9224-39c1757f1b04"
    }
  ) {
    _docID
    _authorID
    title
  }
}
Result
{
  "data": {
    "update_Book": [
      {
        "_authorID": "bae-c169e917-df52-5603-9224-39c1757f1b04",
        "_docID": "bae-e1dcefa0-46ca-5ae5-bc0a-859f2e7e1259",
        "title": "Les Misérables"
      }
    ]
  }
}

Create multiple documents at once​

You can create multiple documents in the same request by concatenating several add_<type> statements. To avoid clashes, you need to alias the results (b1 and b2 in the example). The aliases are used as keys in the result JSON.

Create two documents
defradb client query '
  mutation {
  b1:add_Book(input: {
    title: "1984",
    genre: "Fiction",
    plot: "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
    rating: 4.20
  }) {
    _docID
    title
  }
  b2:add_Book(input: {
    title: "Lord of the Flies",
    genre: "Fiction",
    plot: "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
    rating: 3.70
  }) {
    _docID
    title
  }
}
'
Result
{
  "data": {
    "b1": [
      {
        "_docID": "bae-87c50a88-e1de-5df9-9659-cfe52d10dc7a",
        "title": "1984"
      }
    ],
    "b2": [
      {
        "_docID": "bae-7e637e18-7c15-5ed9-a5bf-aea644e5fcb6",
        "title": "Lord of the Flies"
      }
    ]
  }
}

JSON fields​

JSON fields expect the value to be an unserialized object, not its string representation.

Valid – JSON unserialized object
mutation {
  add_jsonBlob(input: {
    jsonField: {
      i: {
        love: "eating my family and commas"
      }
    }
  }) { jsonField }
}
Invalid – JSON string representation
mutation {
  add_jsonBlob(input: {
    jsonField: "{\"i\": {\"love\": \"eating my family and commas\"}}"
  }) { jsonField }
}
Create new documents
Edit this page