Read Queries

get / cget

Fetches data from the database collection. The get query returns only the data, while cget also provides metadata of the documents.

The following is the metadata format returned by cget :

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

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

Fetch a single document

Use get or cget to fetch a single document from a collection. cget additionally returns document metadata.

await db.get(collection_name, doc_id)

Fetch all documents in a collection

Use get or cget to fetch all documents from a collection. cget additionally returns document metadata.

await db.get(collection_name)

Fetch documents from a sub collection

Arbitrary levels of document nesting are supported, allowing access to subcollection documents.

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

Limit

Limits the number of documents returned from a collection. By specifying a number after the collection name, you can control how many documents are fetched.

await db.get(collection_name, 5)

Sort

Sorts the documents in a collection based on a specified field and order. Supports both ascending and descending order.

Descending order

In this example, documents in the collection are sorted by age in descending order.

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

Ascending order

In this example, the age field is sorted in ascending order by default because the second element in the array is not defined.

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

Multiple fields

In this example, documents in the collection are sorted by age in descending order, then sorted by name in ascending order.

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

Where

Retrieves documents from a collection based on specific query conditions. Supports a range of operators for flexible querying.

The following example returns all documents where the age field is greater than 20.

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

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

Skip

Enables skipping over a specified number of documents, useful for implementing pagination or bypassing previously processed data.

startAt, startAfter, endAt, and endAfter are supported.

• startAt : Start fetching documents from a specific value.
• startAfter : Fetch documents beginning immediately after a specific value.
• endAt : Fetch documents up to and including a specific value.
• endAfter : Fetch documents up to, including, and the one after a specific value.

Skip with limit range

The following example will sort the documents from the collection using the age field in ascending order. It will then start fetching documents from the collection where the age is greater than 20 but less than or equal to 60.

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

Skip with a specific start point

The following example will sort the documents from the collection using the age field in ascending order, then by the name field in descending order. The documents to be fetched will start after the first document where the age is 20 and name is "Bob".

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

Pagination

Manages the retrieval of documents in pages, making it easier to handle large datasets.

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