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"
}
})
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 |
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.
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 |
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" }})
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.
DocID¶
Use the doc.id
property to get the unique DocID
for this document.
const docId = doc.id
Latest CommitID¶
Use the doc.commitId
property to get latest CommitID of a document.
const commitId = doc.commitId
Anchor CommitIDs¶
Use the doc.anchorCommitIds
property to get all CommitIDs which are anchor commits for this document.
const anchorCommits = doc.anchorCommitIds