ComposeDB: Using Ceramic as a Graph Database

ComposeDB provides a complete data solution that supports multi-player use cases—like those demanded by social and DAO applications.

ComposeDB: Using Ceramic as a Graph Database
Read the docs to start building with ComposeDB's developer preview

What is ComposeDB on Ceramic?

ComposeDB on Ceramic is a decentralized, composable graph database. It provides different configurations (building blocks) that allow developers to quickly build applications on Ceramic—including the ability to discover, create, share and reuse composable data models using GraphQL.

ComposeDB provides a complete data solution that supports multi-player use cases—like those demanded by social and DAO applications. Popular use cases include projects around user profiles, reputation (publicly verifiable attestations for skills, credentials, and contribution scores), and user-generated content (portable social graphs, social media apps, networking, messaging, and blogs).

Today, Ceramic applies to a wide variety of use cases across different markets and segments. Its many examples include:

  • Storing user-generated content as Ceramic streams for app interoperability
  • Storing contributor credentials for DAOs
  • Issuing and storing verifiable credentials
  • Creating unified conversation layers that can work across applications
  • Enabling fully encrypted wallet-to-wallet messaging
  • Storing user profile data
  • Storing dynamic NFT content and metadata attached to user identities
  • Dynamically appending metadata to NFTs over time

Following the production-ready release of ComposeDB, we expect to see applications that offer extremely rich end-user experiences—all built by developers who contributed to the community-driven data ecosystem on Ceramic.

Ceramic’s core team will present a production-ready version of ComposeDB in early 2023, one that will:

  • Enable developers to define and query complex graph database schemas that feature many different forms of relations between accounts (e.g. a user) and their content (e.g. a social post)
  • Make indexing and querying possible on Ceramic
  • Make data models and data more easily reusable on Ceramic
  • Support advanced permissioning

Overview of ComposeDB on Ceramic

This section outlines the five features and components that make ComposeDB on Ceramic possible. Click here for a full overview of concepts.

Composites & Data Models

Composites are composable building blocks used by developers. They are groups of data models (e.g. profiles, blog posts, and comments) that together define the graph database schema for an application. Content streams in Ceramic have metadata that automatically associates them to a data model, which defines the shape and schema of that data, as well as to accounts and other content (e.g. User X liked a post by User Y). Composites aggregate these lower-level data models into higher-level groups for application development. Composites are created by developers in the community and all feed into Ceramic’s ecosystem, making it easy for different applications to reuse and share data.

As we shift toward Composites, we’ll be sunsetting the previous data models module and discouraging using TileDocument streams.


There are a few important changes required when running a JS Ceramic node after the ComposeDB release. Every node must now be backed by a SQL database, SQLite or Postgres, that will be used to index the data and construct the database for the data models in your Composite. Each node decides what to index and store in the database based on the models contained in its Composite, which must be passed to the node during development time.

Ceramic acts as a syncing protocol that maintains your local database state against a global network of documents and interoperable data models, maintained via the same verifiable event streams that have always been at the core of Ceramic—allowing you to trust the integrity of your index.


Developers only need to use one library, the ComposeDB Client, which provides a GraphQL interface to Ceramic. This client needs to be passed a Composite in order to saturate its own APIs and know which data models you’re using. Once your ComposeDB Client is loaded with your Composite, you can make GraphQL queries and mutations against your Ceramic node. Using ComposeDB will be much easier and more streamlined than building directly with previous developer packages on Ceramic—such as IDX or DID DataStore.

Data Model Reusability and Marketplace

Composites and their underlying data models are designed to be reusable, making it simple to build complementary and interoperable apps. Apps that reuse each other's Composites create instant interoperability, without any integrations needed. To date, developers have had to manually submit data models to the Registry on Github. Data models are now automatically indexed, enabling easier discovery and reuse. In the first release milestone, getting existing models happens through commands in the ComposeDB CLI, but we’ll follow closely with a UI.

Object Capabilities

One of the biggest challenges in Web3 is offering the ease of use of Web2—one-click sign-in and user sessions—while also preserving the user’s control of their data. To enable this, we have a new library called “did-sessions” built with CACAO (Chain Agnostic Capability Object), offering a permissions model called capability-based access control. CACAO will integrate with ComposeDB to grant granular permissions to specific models. Permissions open up a range of new use cases, sign in flows, and data access patterns on Ceramic. This includes capability-based permission scoping, which allows a developer to specify which Composites or data models they’re asking permission for.

The first major use case we’re enabling with CACAO is Sessions. We’ve paired CACAO and did-sessions library with a new DID method, called did:pkh, and the Sign-In With Ethereum specification (with more chains to come). This will allow users to seamlessly sign-in with their wallet and delegate actions (e.g. “liking”) and storage permissions to the developer for time-bound periods.

Ceramic Today vs. ComposeDB on Ceramic

Ceramic Today

ComposeDB on Ceramic

DB Type

Key-Value Store

Graph Database


Account to single JSON object (Data Models)

Property graph supporting one-to-many relationships (Composites)


TileDocument streams

Model streams, MID streams



Indexing by each Ceramic node


Many JS Library Method Calls

GraphQL Queries


HTTP Client, ModelManager, DID DataStore, Self.ID SDK

HTTP Client, GraphQL Client


3ID as default

did:PKH as default


All-or-nothing permissions

Granular permissions per model


GitHub Data Models Registry

Marketplace for models


Patchwork of client libraries

Streamlined flow and tooling


Specific Ceramic sign-in popups

Familiar, Web3 wallet-native

Milestones for ComposeDB on Ceramic

The following milestones represent different releases of ComposeDB on Ceramic. The dates are targets, not commitments. Please join our mailing list or Discord Server to find out when new releases go live.

Developer Preview

The Developer Preview will be available for developers who want to familiarize themselves with the new ComposeDB stack. Over the coming months the Ceramic core team will release new versions with improved functionality and documentation.

Available Early September

The earliest Developer Preview will offer the CLI and GraphQL Client, Composites, Sign-In With Ethereum, DID-Sessions, and the ability to explore models in the CLI. The core team will provide a Getting Started Guide, high level docs and js-ComposeDB API documentation.

Limitations: Currently, ComposeDB only supports defining relations between an account and the documents created by this account. Relations between documents and accounts are under development. In addition, there will be no scalability guarantees, no access to historical third-party data, it will not be available on mainnet and there will be no retroactive data availability.

Available Early October at Devcon in Bogota, Colombia

This release milestone provides simple relations between documents and accounts, enabling developers to test graph models so they can build richer and more engaging applications on Ceramic.

This version of the preview will offer simple (as compared to the following release) model relations, an improved docs portal with updated API documentation (js-compose, js-did, js-ceramic), Sign-In With Solana functionality and an updated way to index models that doesn’t require developers to restart their nodes.

Limitations include no access to historical third-party data, no optimization for deeply-nested queries with many relations and, at this time, ComposeDB will allow duplicate relations (e.g. liking the same post twice); therefore, developers will need to build preventative logic.

Available Late December

This release enables support for interfaces, allowing developers to evolve their application through extending existing data models, and unifying queries across different data models. This will also make it easier for developers to build shared interfaces with other applications (e.g. an interface for comments) as well as extend models for their app (e.g. adding more fields to a model).

For example, there could be a generic verifiable credential interface, this interface could be implemented by an education credential and a job employment credential. An application could make a union of these two credentials and seamlessly query across both of them. Verifiable credential MID streams won’t belong to the generic VC interface, but they will belong to more specific data models that implement the verifiable credential interface (e.g. education credential, job employment credential, DAO contribution credential, etc.).

Developers can expect support for sets, and indexable anchors that enable historical data sync retroactively. Historical data sync will enable a node to connect to the network and sync previous data (before the point in time that the particular node started indexing the data model). Historical data sync also means that if Node B goes down it will still be able to index the data via Node A, allowing historical data to sync between applications that share the same data model.

Available January 2023

This release enables developers to build on an open data ecosystem and define the data standards for their app (and others to come) to interoperate.

At this stage, queries will be executed more efficiently than before (server-side query execution), improvements will come to the dev portal, and easy-to-use node metrics will be available—in addition to self-serve mainnet access.

Limitations at this stage include multi-node deployments and a lack of hosted node options.


Available Early 2023

Developers can build quickly on ComposeDB to offer rich end-to-end user experiences on their apps—providing data models and interoperable data within the Ceramic ecosystem.

At this point, Ceramic will handle a standard deployment of millions of writes and reads per day, in addition to a UI for searching Composites (data models) and improved Getting Started documentation. A UI for searching data models and Composites will make building with ComposeDB on Ceramic faster than before. Templates for scaled deployments and a hosted infrastructure option will also become available.

Read the docs to build with ComposeDB and let us know what you think via this 2-minute survey