Writes¶

Writes are interactions that write to Ceramic, such as creating new documents or modifying existing documents. This guide demonstrates how to make writes during runtime using the HTTP and core clients. To make writes using the CLI, see Quick Start.

Prerequisites¶

You need an installed client and an authenticated user to perform writes to the network during runtime.

Create a document¶

Use the createDocument() method to create a new document.

const doc = await ceramic.createDocument(doctype, docParams, docOpts)

Example

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

const doc = await ceramic.createDocument('tile', {
  content: { foo: "bar" },
  metadata: {
    schema: "ceramic://kyz123...456",
    controllers: ["did:3:kyz123...456"],
    family: "doc family"
  }
})

API reference

Parameters¶

When creating a document, the first parameter is the doctype and it is always required. Other parameters including content will vary depending on the doctype specification. If you do not specify a doctype or if your parameters do not meet the doctype's requirements, your transaction will fail.

Doctype

Doctypes are rules that govern the behavior of documents on the Ceramic network. A doctype is required.

Parameter	Required?	Value	Description
`doctype`	required	string	Specifies rules for `content`, `metadata`, and conflict resolution

Supported doctypes

Ceramic currently supports two doctypes: tile for storing arbitrary JSON content and caip-10 link for storing a proof that binds a DID to a blockchain account. Read each doctype's documentation for more information on its parameters below.

DocParams

DocParams are specifics related to your document including content, metadata, and deterministic. All of these properties are optional.

Content

Parameter	Required?	Value	Description	Notes
`content`	optional	object	The content of your document	Must conform to the `doctype` and `schema` if present

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, then the genesis commit will not be signed.

Metadata

Parameter	Required?	Value	Description	Notes
`schema`	optional	string	URL of a Ceramic document that contains a JSON schema	If set, schema will be enforced on content
`controllers`	optional	array of strings	Defines the DID that is allowed to modify the document	If empty, defaults to currently authenticated DID
`family`	optional	string	Allows you to group similar documents into families	Useful for indexing groups of like documents on the network

API reference

Deterministic

Parameter	Required?	Value	Description	Notes
`deterministic`	optional	boolean	If false, allows documents with the same `doctype`, `content`, and `metadata` to generate unique DocIDs	If empty, defaults to false

Using the deterministic parameter

For most use cases you will likely want to leave the deterministic parameter set to false. However for special circumstances, you may want this to be set to true. For example this should be set to true if you would like to enable deterministic queries for your document. If this is your use case, then it is also important that you omit all content during document creation. You can proceed to add content to your document by updating it.

API reference

DocOpts (optional)

DocOpts are options that can be passed to each operation on a document (create, change, load) 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 the update was made	true
`publish`	optional	boolean	Publish the update to the network	true
`sync`	optional	boolean	Sync document updates from the network	true

API reference

Update a document¶

Use the doc.change() method to update the content or metadata of your document. Any update to a document must conform to the update rules specified by the document's doctype. Note that you can also pass DocOpts parameters to this method if you wish to not use the default behavior of publishing and/or anchoring your change, but this behavior should be reserved for advanced use cases.

await doc.change({ content: { foo: "updated" }})

API reference

Document information¶

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

API reference

DocID¶

Use the doc.id property to get the unique DocID for this document.

const docId = doc.id

API reference

Latest CommitID¶

Use the doc.commitId property to get latest CommitID of a document.

const commitId = doc.commitId

API reference

Anchor CommitIDs¶

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

const anchorCommits = doc.anchorCommitIds

API reference