Skip to main content
Version: 0.2.x

Concepts overview

ComposeDB provides a graph structure for interacting with data on the Ceramic network.

The nodes in the graph can be accounts or documents, while the edges in the graph represent relations between nodes.

Currently, ComposeDB only supports edges between an account and documents, but relations between accounts and documents are planned on being supported.


All nodes in the graph use a globally unique identifier, allowing direct access to any known node.

ComposeDB supports two types of nodes: accounts that are able to manipulate data in the graph, and documents containing mutable data of a given shape.


Ceramic uses Decentralized Identifiers (DIDs) for accounts, which get translated to CeramicAccount objects by the ComposeDB client.

DIDs can represent any entity that is able to write data on Ceramic and therefore in ComposeDB, which can be end-users of an application, groups, applications or any kind of authenticated service.

In order to write data in ComposeDB, a DID must be attached to the ComposeDB client instance, as documented in the mutations page.


Documents in ComposeDB are Ceramic streams storing structured data defined by a model.

Ceramic nodes can be configured to index specific models, storing all the documents using a model in a local database in order to provide fast access and query capabilities.

Using GraphQL, the ComposeDB client allows to query documents indexed by a Ceramic node, as well as creating new documents and updating existing ones when mutations are enabled.


Models are Ceramic streams storing metadata about documents, notably their data structure, validation rules and relations, as well as discovery information.

ComposeDB tools abstract the creation of models using GraphQL's Schema Definition Language, as described in the dedicated documentation page.


All documents in ComposeDB must use a model, which contains information about the data structure the document must conform to. The validation is performed directly by all Ceramic nodes, allowing application to have guaranties about the documents they interact with even if they don't implement validation themselves.

Currently Ceramic uses draft 2020-12 of the JSON Schema specification to define the data structure and validation rules of documents.


Currently, ComposeDB only supports defining relations between an account and the documents created by this account.

Relations between documents and between accounts are under development and will be made available in future developer previews of ComposeDB.


Composites are the primary data structures used by ComposeDB, essentially defining a mutable set of models with additional metadata.

The ComposeDB developer tools and client library use complementary representations of composites to support various development flows such as managing data models, deploying them to Ceramic nodes and generating the runtime GraphQL schema applications can interact with.