Skip to main content
Version: 1.0 (Latest)

Create new documents

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

Display database setup

To reproduce the example results from this page, your database needs the following setup.

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

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

Syntax​

You create documents via the add_TYPE mutation. The mutation returns the new documents.

Syntax – Add mutation
mutation {
  add_TYPE(input: docObj) { [returnField] }
}
  • TYPE – A collection name.
  • docObj – JSON-like object containing the document details.
  • [returnField] – List of fields to return for the created documents.

Single document​

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

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-db5131b2-2e79-5ae8-ab8b-df35c2b939e1",
        "title": "Infinite Jest"
      }
    ]
  }
}
The document ID

The field _docID contains the document's unique identifier. The document data might change over time, but its docID will stay the same. The _docID field is automatically indexed.

Multiple documents​

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
  }) {
    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
  }) {
    title
  }
}
'
Result
{
  "data": {
    "b1": [
      {
        "title": "1984"
      }
    ],
    "b2": [
      {
        "title": "Lord of the Flies"
      }
    ]
  }
}

Relationships​

To create a relationship between two documents, you need to store the docID of one document into the relationship field of the other. Each relationship field results in a _<fieldName>ID field: for example, the type Book has a field author: Person, so a field _authorID is automatically available. Use this field to store the pointer to the docID of a Person document.

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-097c416c-bb66-5947-b241-c462464ea41d",
        "title": "Les Misérables"
      }
    ],
    "add_Person": [
      {
        "_docID": "bae-4bfe5f4c-d668-5dc3-9de2-eb598af3da7d",
        "name": "Victor Hugo"
      }
    ]
  }
}

Then create a relationship between them via 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-097c416c-bb66-5947-b241-c462464ea41d",
    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-097c416c-bb66-5947-b241-c462464ea41d",
        "title": "Les Misérables"
      }
    ]
  }
}

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