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 private key 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. This UI allows you to run queries by simply writing data queries inside of the editor you see below and pressing the "Play" button to see the results of the query: 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{
  postsIndex(first: 2) {
    edges {
      node {
        body
      }
    }
  }
}

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": {
    "postsIndex": {
      "edges": [
        {
          "node": {
            "text": "A Post created using composites and GraphQL"
          }
        },
        {
          "node": {
            "text": "This is my second post!"
          }
        }
      ]
    }
  }
}

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{
  postsIndex(last: 3) {
    edges {
      node {
        body
      }
    }
  }
}

Mutations​

There are three types of mutations you can perform on ComposeDB data: creating, and updating records, or change wether the records is indexed or not.

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: CreatePostsInput!){
  createPosts(input: $i){
    document{
      id
      title
      body
      tag
      ranking
      created_at
    }
  }
}

Variables:

{
  "i": {
    "content": {
      "title": "New post",
      "body": "My new post on Ceramic",
      "tag": "User post",
      "ranking": 5,
      "created_at": "2024-12-03T10:15:30Z"
    }
  }
}

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

Response:

{
  "data": {
    "createPosts": {
      "document": {
        "id": "kjzl6kcym7w8y5ygh1fyvstbjztd69suybc4ez8bet2hun7jezrc2m0uwg5bm3q",
        "title": "New post",
        "body": "My new post on Ceramic",
        "tag": "User post",
        "ranking": 5,
        "created_at": "2024-12-03T10:15:30Z"
      }
    }
  }
}
note

Stream IDs are unique. The “id” you will see in the response when performing the mutation above will be different. Keep that in mind as you follow this guide and update the id to the one that you see in your response.

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: UpdatePostsInput!) {
    updatePosts(input: $i) {
        document {
            id
            title
            body
            tag
            ranking
            created_at
        }
    }
}

Variables:

{
  "i": {
    "id": "kjzl6kcym7w8y5ygh1fyvstbjztd69suybc4ez8bet2hun7jezrc2m0uwg5bm3q",
    "content": {
      "title": "New post",
      "body": "My new post on Ceramic using ComposeDB",
      "tag": "User post",
      "ranking": 5,
      "created_at": "2024-12-03T10:15:30Z"
    }
  }
}

This mutation will update the record with ID kjzl6kcym7w8y5ygh1fyvstbjztd69suybc4ez8bet2hun7jezrc2m0uwg5bm3q.

Response:

{
  "data": {
    "updatePosts": {
      "document": {
        "id": "kjzl6kcym7w8y5ygh1fyvstbjztd69suybc4ez8bet2hun7jezrc2m0uwg5bm3q",
        "title": "New post",
        "body": "My new post on Ceramic using ComposeDB",
        "tag": "User post",
        "ranking": 5,
        "created_at": "2024-12-03T10:15:30Z"
      }
    }
  }
}

Remove/Restore record from index​

If instead of updating the created post record we want to stop indexing said record we would need to use the enableIndexingPost mutation with the shouldIndex option set to false, or if we want to index an un-indexed record we can call the enableIndexingPost mutation with the shouldIndex option set to true, and the post ID as variable.

Query:

mutation EnableIndexingPost($i: EnableIndexingPostsInput!) {
      enableIndexingPosts(input: $i) {
          document {
            id
          }
        }
      }

Variables:

{
  "i": {
    "id": "kjzl6kcym7w8y5ygh1fyvstbjztd69suybc4ez8bet2hun7jezrc2m0uwg5bm3q",
    "shouldIndex": false
  }
}

This mutation will un-index the record with ID kjzl6kcym7w8y5ygh1fyvstbjztd69suybc4ez8bet2hun7jezrc2m0uwg5bm3q.

Response:

{
  "data": {
    "enableIndexingPosts": {
      "document": null
    }
  }
}

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: