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 document

Use the loadDocument() method to load a single document using its DocID.

const docid = 'kjzl6cwe1jw14...'
const doc = await ceramic.loadDocument(docid)

API reference

Query a deterministic document

One the writes page, we discussed how to create a document with the deterministic parameter set to true. Since this parameter allows us to generate the exact same DocID if we create two documents with the same doctype and DocParams, it is possible to "query" the document using the same createDocument() method that we used to initially create it without needing to know the DocID before performing the query. Note we are setting the DocOpts parameters (anchor and publish) to false so that we are only loading the document and not publishing any changes to the network.

const doc = ceramic.createDocument('tile', {
  deterministic: true,
  metadata: {
    controllers: ['did:key:z6MkfZ6S4NVVTEuts8o5xFzRMR8eC6Y1bngoBQNnXiCvhH8H'],
    family: 'example family'
  },
  { anchor: false, publish: false }
})

API reference

Query multiple documents

Use the multiQuery() method to load multiple documents at once. The returned object docMap is a map from DocIDs to document instances.

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

API reference

Query document paths

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

Imagine a document kjzl6cwe1jw...14 whose content contains the DocIDs of two other documents. These DocIDs exist at various levels within a nested JSON structure.

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

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

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

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

API reference