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