Skip to content

Queries

This guide demonstrates how to query documents on the Ceramic network during runtime using the HTTP and core clients. You can also use the CLI to query documents as shown in the Quick Start guide.

Prerequisites

You need to have an installed client to perform queries during runtime.

Query a stream

Use the loadStream() method to load a single stream using its StreamID.

const streamId = 'kjzl6cwe1jw14...'
const stream = await ceramic.loadStream(streamId)

Loading the proper stream type

When using the Typescript APIs, loadStream by default returns an object of type Stream, which will not have any methods available to perform updates, or any other streamtype-specific methods or accessors. To be able to perform updates, as well as to access streamtype-specific data or functionality, you need to specialize the loadStream method on the StreamType of the Stream being loaded. For example, to load a TileDocument, you would say await ceramic.loadStream<TileDocument>(streamId)

API reference

Load a stream at a specific commit

If you want to see the contents of a stream as of a specific point in time, it's possible to pass a CommitID instead of a StreamID to the loadStream() method. This will cause the Stream to be loaded at the specified commit, rather than the current commit as loaded from the network. When loading with a CommitID the returned Stream object will be marked as readonly and cannot be used to perform updates. If you wish to perform updates, load a new instance of the Stream using its StreamID.

Query multiple streams

Use the multiQuery() method to load multiple streams at once. The returned object is a map from StreamIDs to stream instances.

const queries = [{
  streamId: 'kjzl6cwe1jw...14'
}, {
  streamId: 'kjzl6cwe1jw...15'
}]
const streamMap = await ceramic.multiQuery(queries)

API reference

Query document paths

Use the multiQuery() method to load one or more streams using known paths from a root stream to its linked streams.

Imagine a stream kjzl6cwe1jw...14 whose content contains the StreamIDs of two other streams. These StreamIDs exist at various levels within a nested JSON structure.

{
  a: 'kjzl6cwe1jw...15',
  b: {
    c: 'kjzl6cwe1jw...16'
  }
}

In the stream above, the path from root stream kjzl6cwe1jw...14 to linked stream kjzl6cwe1jw...15 is /a and the path to linked stream kjzl6cwe1jw...16 is /b/c. Using the StreamID of the root stream and the paths outlined here, we use multiQuery() to query all three streams at once without needing to explicitly know the StreamIDs of the two linked streams.

The multiQuery() below will return a map with all three streams.

const queries = [{
  streamId: 'kjzl6cwe1jw...14'
  paths: ['/a', '/b/c']
}]
const streamMap = await ceramic.multiQuery(queries)

API reference

Stream information

To get specific information about the stream that you created or loaded you can use the accessors on the Stream class. Below are some examples.

API reference

StreamID

Use the stream.id property to get the unique StreamID for this stream.

const streamId = stream.id

API reference

Latest CommitID

Use the stream.commitId property to get latest CommitID of a stream.

const commitId = stream.commitId

API reference

Anchor CommitIDs

Use the stream.anchorCommitIds property to get all CommitIDs which are anchor commits for this stream.

const anchorCommits = stream.anchorCommitIds

API reference