Skip to content

Ceramic storage

Learn how to use Ceramic streams as external storage for records.

This guide only describes how to use Ceramic streams as external storage for records. If you want to directly store or read content in records then you do not need this guide. See writing records or reading records.



Since IDX already depends on Ceramic to store protocol data, you will have it installed in your project. You do not need to install any additional software to use Ceramic for external storage.

Writing data

To write data to IDX records and their external Ceramic streams, you must first authenticate the user's DID.

For demonstration purposes, we will use this example of a simple note-taking application. This application will store individual notes in Ceramic streams and a list of these notes will be stored in an IDX record. This IDX record will be identified with the notesList alias and use the described data model.

Create a new Ceramic stream

Use the TileDocument.create() static method from @ceramicnetwork/stream-tile to create a new note as a Ceramic stream:

const stream = await TileDocument.create(ceramic, {
  date: new Date().toISOString(),
  text: 'Hello world',

Add the Ceramic stream to an IDX record

Use the idx.set() method from the IDX API to add the StreamID of the note to their notesList record.

await idx.set('notesList', {
  notes: [{ id:, title: 'My first note' }],

Update the Ceramic stream

Use the update() method of the TileDocument instance to update the note.

await stream.update({ date:, text: 'Hello Ceramic' })

Reading data

Query the IDX record

Use the idx.get() method from the IDX API to query the notesList record. In this case it will return a list of StreamIDs that represent the notes.

With an authenticated user:

await idx.get('notesList')

With an unauthenticated user:

await idx.get('notesList', '<DID>')

Query the Ceramic stream

Use the TileDocument.load() static method from the @ceramicnetwork/stream-tile to load a stream containing the note. You will need to pass a StreamID from the notesList record above:

await TileDocument.load(ceramic, '<StreamID>')

More on Ceramic

For a full description of Ceramic and how to use it, see the Ceramic documentation.