Skip to content

TileDocument API

This guide describes how to create, update, and query TileDocuments using the JS HTTP Client and the Core Client. You can also interact with TileDocuments from the CLI; see the Quick Start guide for more information.

Requirements

You need an installed client and an authenticated user to perform writes to TileDocuments. If you only wish to query TileDocuments then you do not need authentication.

Installation

npm install @ceramicnetwork/stream-tile

Write APIs

Create a TileDocument

Use the TileDocument.create() method to create a new TileDocument.

import { TileDocument } from '@ceramicnetwork/stream-tile';

const doc = await TileDocument.create(ceramic, content, metadata, opts);

const streamId = doc.id.toString();

In this example we create a TileDocument where we set content, schema, controllers, and family.

const doc = await TileDocument.create(
  ceramic,
  { foo: 'bar' },
  {
    controllers: [ceramic.did.id],
    family: 'doc family',
    schema: schemaDoc.commitId,
  }
);

API reference

Parameters

ceramic

When creating a TileDocument, the first parameter is the CeramicAPI used to communicate with the ceramic node and it is always required. It will either be an instance of Ceramic when using the Core client or an instance of CeramicClient when using the HTTP client.

content

The content of your TileDocument, in the form of a JSON document. If schema is set in the metadata, then the content must conform to the specified schema.

When content is included during document creation, the document's genesis commit will be signed by the authenticated user's DID. When content is omitted (set as null or undefined), then the genesis commit will not be signed.

metadata (optional)
Parameter Required? Value Description Notes
controllers optional array of strings Defines the DID that is allowed to modify the document. Currently only one controller is supported per document If empty, defaults to currently authenticated DID
schema optional string CommitID of a Ceramic TileDocument that contains a JSON schema If set, schema will be enforced on content
family optional string Allows you to group similar documents into families Useful for indexing groups of like documents on the network
tags optional array of strings Allows you to tag similar documents Useful for indexing groups of like documents on the network
deterministic (deprecated) optional boolean Deprecated - Please use TileDocument.deterministic() instead. If false, allows TileDocuments with the same content and metadata to generate unique StreamIDs If empty, defaults to false

API reference

opts (optional)

The final argument to TileDocument.create is an instance of CreateOpts, which are options that control network behaviors performed as part of the operation. They are not included in the document itself.

Parameter Required? Value Description Default value
anchor optional boolean Request an anchor after creating the document true
publish optional boolean Publish the new document to the network true
sync optional enum Controls behavior related to syncing the current document state from the network PREFER_CACHE
syncTimeoutSeconds optional number How long to wait to hear about the current state of the document from the network 3 for deterministic documents, 0 otherwise
pin optional boolean Whether to immediately pin the stream upon creation on the connected node false

API reference

Create a Deterministic TileDocument

Use the TileDocument.deterministic() method to create a new deterministic TileDocument or to query an existing deterministic TileDocument (see the Query A Deterministic TileDocument section).

import { TileDocument } from '@ceramicnetwork/stream-tile';

const doc = await TileDocument.deterministic(ceramic, metadata, opts);

const streamId = doc.id.toString();

In this example we create a deterministic TileDocument where we set tags, and family in the metadata. Then we update the document to add contents. We then can retrieve that same tile document using the original metadata, even without knowing the document's StreamID.

// If the document doesn't already exist, TileDocument.deterministic creates it
const doc = await TileDocument.deterministic(
  ceramic,
  { family: 'doc family', tags: ['tag1'] }
);

await doc.update({ foo: "Adding some content!" });

// If the document does already exist, TileDocument.deterministic loads its current state
const retrievedDoc = await TileDocument.deterministic(
  ceramic,
  { family: 'doc family', tags: ['tag1'] },
  { anchor: false, publish: false }
);

console.log(doc.id.toString() === retrievedDoc.id.toString()); // true
console.log(doc.content.foo === retrievedDoc.content.foo); // true

API reference

Using the deterministic function

For most use cases you will likely want to use TileDocument.create(). However for special circumstances, you may want to use TileDocument.deterministic() . For example you should use TileDocument.deterministic() if you would like to enable deterministic queries for your TileDocument. If this is your use case, then it is also important that you provide initial metadata as deterministic document queries are based entirely on the document's initial metadata. You can proceed to add content to your document by updating it.

Parameters

ceramic

See the ceramic parameter in TileDocument.create.

metadata

Metadata is required when creating TileDocuments using TileDocument.deterministic. Specifically the family and/or tag parameters are required.

For more information see the metadata parameter in TileDocument.create.

opts (optional)

See the opts parameter in TileDocument.create.

Update a TileDocument

Use the doc.update() method to update the content or metadata of an existing TileDocument.

const doc = await TileDocument.load(ceramic, streamId, opts);
await doc.update(newContent, newMetadata, opts);

In this example we update a TileDocument's content while also giving it a tag.

const streamId = 'kjzl6cwe1jw14...'; // Replace this with the StreamID of the TileDocument to be updated
const doc = await TileDocument.load(ceramic, streamId);
await doc.update({ foo: 'baz' }, { tags: ['baz'] });

API reference

Persisting updates

Please note that if you want updates to a Stream to persist you need to ensure that the stream is pinned by at least one node on the network. See the pinning page for more information.

Parameters

content

The new content of your document. This fully replaces any existing content in the document.

metadata (optional)

Only fields that are provided in the metadata arg will be updated. Fields not specified in the metadata arg will be left with their current value.

API reference

Updating the deterministic parameter

Please note that the deterministic parameter can only be set while creating a document. It cannot be updated once the document exists.

opts (optional)

The final argument to TileDocument.update is an instance of UpdateOpts, which are options that control network behaviors performed as part of the operation. They are not included in the document itself.

Parameter Required? Value Description Default value
anchor optional boolean Request an anchor after updating the document true
publish optional boolean Publish the update to the network true

API reference

Read APIs

Load a TileDocument

Use the TileDocument.load() method to load a single document using its StreamID

const streamId = 'kjzl6cwe1jw14...'; // Replace this with the StreamID of the TileDocument to be loaded
const doc = await TileDocument.load(ceramic, streamId, opts);

API reference

Parameters

ceramic

When loading a TileDocument, the first parameter is the CeramicAPI used to communicate with the Ceramic node and it is always required. It will either be an instance of Ceramic when using the Core client or an instance of CeramicClient when using the HTTP client.

streamId

The StreamID or CommitID of the TileDocument to be loaded. When providing the document's StreamID, Ceramic will attempt to load the most recent version of the document from the network. If a CommitID is provided instead, Ceramic will load the document with the version of the contents and metadata from the specific commit specified. The returned TileDocument object will also be marked readonly and cannot be used to perform updates.

opts (optional)

The final argument to TileDocument.load is an instance of LoadOpts, which are options that control network behaviors performed as part of the operation.

Parameter Required? Value Description Default value
sync optional enum Controls behavior related to syncing the current document state from the network SyncOptions.PREFER_CACHE
syncTimeoutSeconds optional number How long to wait to hear about the current state of the document from the network 3

API reference

Query a deterministic TileDocument

In the deterministic section, we discussed how to create a deterministic document. Since this function allows us to generate the exact same StreamID if we use it to create two documents with the same initial metadata, it is possible to "query" the document using the same TileDocument.deterministic method that we used to initially create it, without needing to know the StreamID before performing the query. Note we are setting the CreateOpts parameters (anchor and publish) to false so that we are only loading the document and not publishing any changes to the network.

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

API reference