Query APIs
Read Queries

Read Queries


db is assumed to be the state variable storing the WeaveDB SDK object. For reference, see Initialize WeaveDB

Also, it is expected that collection_name refers to the string value that contains the name of your collection, and doc_id refers to the string value that contains the unique identifier of a document from the collection.

get / cget

get only returns data, whereas cget returns metadata of the docs too.

{ id, setter, data, block: { height, timestamp } }

The metadata returned with cget functions as a cursor for pagination.

Get a doc

await db.get(collection_name, doc_id)

Get a collection

await db.get(collection_name)

Get a sub collection

Arbitrary length of document nesting is possible.

await db.get(collection_name, doc_id, "sub_collection_name_1", "sub_doc_id_1", "sub_collection_name_2")


Limit the number of docs returned

await db.get(collection_name, 5)


Sort by age in descending order

await db.get(collection_name, [ "age", "desc" ])

Sort by age in ascending order

By default, the property age is sorted in ascending order because the second element in the array is not defined

await db.get(collection_name, [ "age" ])

Sort by age in descending order, then sort by name in ascending order

await db.get(collection_name, [ "age", "desc" ], [ "name", "asc" ])


Get docs where the age is 20

await db.get(collection_name, ["age"], [ "age", ">", 20 ])

== > >= < <= != in not-in array-contains, and array-contains-any are supported.


Dot notation can be used to specify nested object fields. (e.g. [ "favorites.food", "==", "apple" ])

Note that dot notation only works with where for now.



= is deprecated and replaced by == at v0.23.0. You can still use it for backward compatibility.


await db.get(collection_name, [ "age" ], [ "startAfter", 20 ], [ "endAt", 60 ])
await db.get(collection_name, [ "age" ], [ "name", "desc" ], [ "startAfter", 20, "Bob" ])

startAt, startAfter, endAt, and endAfter are supported.


const docs_page1 = await db.cget(collection_name, [ "age" ])
const docs_page2 = await db.cget(collection_name, [ "age" ], ["startAfter", docs_page1[docs_page1.length - 1]])


To get the next nonce for an address. Nonces are internally used for signature verification to write data.

await db.getNonce("address")


To get the last added doc id, use getIds.

const tx = await db.add({ age: 20, name: "Bob" }, collection_name)
const doc_id = (await db.getIds(tx))[0]

on / con

You can subscribe to state changes with on and con. They are the counterparts of get and cget respectively.

These only work with weavedb-sdk-node for now.

const unsubscribe = await on.(collection_name, doc_id, (data) => {

getCache / cgetCache

They are the same as get / cget, but get values from the cached state, which is faster but may not be the most up-to-date values.

These only work with weavedb-sdk-node for now.

await db.getCache(collection_name, doc_id)
await db.cgetCache(collection_name, doc_id)


List collection names

await db.listCollections() // list root collections
await db.listCollections(collection_name, doc_id) // list sub collections