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

Limit the number of docs returned

await db.get(collection_name, 5)

Sort

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" ])

Where

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.

⚠️

deprecated

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

Skip

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.

Pagination

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]])

getNonce

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

await db.getNonce("address")

getIds

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) => {
  console.log(data)
  unsubscribe()
})

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)

listCollections

List collection names

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

Write Queries Database Info