Mutations

Create or update data on ComposeDB.

Prerequisites

• An authenticated user
• A deployed composite
• A compiled composite

tip

The ComposeDB Client automatically generates a GraphQL Schema from your compiled composite.

Enable mutations

Mutations require an authenticated user. After you have an authenticated user, enable mutations by setting their authenticated account on the ComposeDB client:

With Sessions

// Assign the authorized did from your session to your client

compose.setDID(session.did)

Without Sessions

// Call setDID method on ComposeClient instance
// Using authenticated did instance

compose.setDID(did)

Create data

Let’s say your app uses a Post model:

type Post @createModel(accountRelation: LIST, description: "A simple text post") {
  author: DID! @documentAccount
  title: String! @string(minLength: 10, maxLength: 100)
  text: String! @string(maxLength: 500)
}

Users will generate data as they interact with your app. Your app needs to perform mutations to write that data to the network. Here’s a mutation query that creates a new post:

# Create post

mutation CreateNewPost($i: CreatePostInput!) {
  createPost(input: $i) {
	document{
		id
		title
	        text
    	}
  }
}

# Content for the post

{
  "i": {
    "content": {
      "title": "Getting started with ComposeDB"
      "text": "A Post created using composites and GraphQL" 
    }
  }
}

Where:

• mutation: GraphQL keyword for creating a write operation.
• CreateNewPost: custom name given to this mutation. This name should represent what the mutation is doing and can be anything you’d like it to be.
• ($i: CreatePostInput!) creates a variable named i with the requirement that its value is of the type CreatePostInput. This type is automatically created for you as a part of the run-time composite. Notice the !, which informs us that this input is required.
• createPost corresponds to an automatically generated GraphQL binding that is part of the run-time representation of your composite. Then names of these bindings follow a naming convention create<your-model-name>.
• (input: $i) is using the value provided for $i as the input for the mutation. This will be defined as a variable to this operation.
• The final piece to this, document{id,title,text} is defining the fields of the document we would like this mutation to create. It’s important to note that you need to include id here in the mutation, but you will not need to include it in the query variables as it is automatically generated.
• Variables: As you can see, i contains content that matches the fields in the above schema title and text. Both have the proper values supplied of a type string. This sets up the variables needed for the query.

Update data

Let’s say a user wanted to modify the title of a previous post. Your app would need to perform a mutation to update that field in the post.

# Update post

mutation UpdatePost($i: UpdatePostInput!) {
    updatePost(input: $i) {
        document {
            id
            title
            text
        }
    }
}

# Content to be updated

{
    "i": {
          "id": <streamID of the stream you wish to update,
	        "content": {    
            "title": "Getting started with ComposeDB and Ceramic"
        }
    }
}

Where:

• You will notice that the naming of the mutation is UpdatePost which indicates that this mutation will update existing records.
• updatePost binding has a prefix update which defines the behaviour of your mutation - updating the existing data instead of creating new records.
• Finally, just like before, we define the variables that should be passed to update record. Here, very important difference is that you will be required to specify all variables, including the stream id so that ComposeDB would know which record should be updated.

Update Options

Update mutations can be provided with an options object containing the following fields:

• replace: Boolean: by default the update logic performs a shallow (1 level) merge of the document contents, so existing contents of the document are not removed unless explicitly changed. When setting replace to true, the document contents will be fully replaced by the contents provided in the update mutation.
• version: CommitID: version of the document the update should be applied on. If set, the update logic will load the latest version of the document and throw an error if it doesn't match the expected version.

Delete data

Currently, data deletion is not supported. All ComposeDB data transactions are timestamped via Ceramic into the public Ethereum blockchain. This means that data can always be retrieved from the blockchain.

Next Steps

At this stage, you should have a strong understanding of how to create applications using ComposeDB and interact with the data that is stored on the network. Congrats!

If you need more inspiration for what can be built on ComposeDB, check out the example applications built by Ceramic community members.