Skip to main content

Interact with data

The final step of getting started with ComposeDB is interacting with your data using GraphQL. In this guide you will learn how to perform GraphQL queries and mutations using your composite.

tip

Want to interact with data using JavaScript instead? See Client setup

Setup​

GraphQL Server​

To interact with data on the network, start a local GraphQL server by running the command below. Note that you have to provide the seed to your did-private-key here — it is also required for performing mutations, covered below.

composedb graphql:server --ceramic-url=http://localhost:7007 --graphiql runtime-composite.json --did-private-key=your_private_key --port=5005

✏️ Note: You can customize the port by configuring the —-port flag.

The output will display a URL, for example:

GraphQL server is listening on http://localhost:5005/graphql

GraphQL Web UI​

In your browser, visit the URL that your local GraphQL server is listening on. You will see a simple UI that you can use to easily interact with your data: GraphQL Web UI

Queries​

One of the most common data interactions you might want to do with ComposeDB is read records from the graph. Using GraphQL, you can query ComposeDB records indexed by your Ceramic node.

In the Create your composite guide, we fetched two models from the Catalog: Post and SimpleProfile. Here we will focus on Post model. For example, let’s say you want to check the first 2 entries that were indexed on the Post graph. This can be achieved running a query like below and specifying that you want to retrieve first 2 records:

Query:

query{
  postIndex(first: 2) {
    edges {
      node {
        text
      }
    }
  }
}

You should see a response similar to the one below. Here, nodes correspond to stored documents while edges represent the relations between nodes.

Response:

{
  "data": {
    "postIndex": {
      "edges": [
        {
          "node": {
            "text": "This is my first post."
          }
        },
        {
          "node": {
            "text": "My second post about ComposeDB!"
          }
        }
      ]
    }
  }
}

You have options to retrieve specific records or last n indexed records as well. For example, to check the last 3 records, run the query below:

Query:

query{
  postIndex(last: 3) {
    edges {
      node {
        text
      }
    }
  }
}

Mutations​

There are two types of mutations you can perform on ComposeDB data: creating and updating records.

Creating records​

Let’s say, you would like to create a post and add it to the graph. To do that, you will have to run a mutation as shown below and pass the actual text as a variable:

Query:

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

Variables:

{
  "i": {
    "content": {
      "text": "A Post created using composites and GraphQL" 
    }
  }
}

The result of the query above will be a new document with a unique ID and the content you provided:

Response:

{
  "data": {
    "createPost": {
      "document": {
        "id": "kjzl6kcym7w8y9xlffqruh3v7ou1vn11t8203i6te2i3pliizt65ad3vdh5nl4l",
        "text": "A Post created using composites and GraphQL"
      }
    }
  }
}
note

Stream IDs are unique. The “id” you will see in the response when performing the mutation above will be different.

Updating records​

Now let’s say you want to edit the post you created in the previous step. To update it, you have to run the UpdatePost mutation and pass the post’s unique ID along with the updated content as variables.

info

You can find your post’s ID in the response after you ran the CreateNewPost mutation.

Query:

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

Variables:

{
  "i": {
    "id": "kjzl6kcym7w8y9xlffqruh3v7ou1vn11t8203i6te2i3pliizt65ad3vdh5nl4l",
    "content": {
      "text": "My best post!"
    }
  }
}

This mutation will update the record with ID kjzl6kcym7w8y9xlffqruh3v7ou1vn11t8203i6te2i3pliizt65ad3vdh5nl4l.

Response:

{
  "data": {
    "updatePost": {
      "document": {
        "id": "kjzl6kcym7w8y9xlffqruh3v7ou1vn11t8203i6te2i3pliizt65ad3vdh5nl4l",
        "text": "My best post!"
      }
    }
  }
}

Authentication​

Although you can query records created by other accounts, you can only perform mutations on records controlled by your account. This guide did not require your authentication because you previously did that in the Set up your environment guide.

🔑 did-private-key plays a very important role for these kind of mutations - it ensures that only you, the account owner, can make changes to the streams that you created.

Next Steps​

Congratulations — you’re on your way to becoming a ComposeDB developer! 🔥

Visit Next Steps for more integration guides and opportunities to contribute to the ComposeDB on Ceramic ecosystem.

For more detailed descriptions and examples, see our advanced guides: