.. and press ENTER to ask a question on web5, how to write code and more.

Skip to main content

Query DWN Records

You can use the query function to obtain records and protocols from a DWN. This guide shows how to do both, as well as how to sort the query results.

tip

Querying a DWN is analogous to querying a database, and the flow of a query is similar to an SQL select statement.

A query can be read as select records with a filter of X from the DWN of this DID.

Querying Protocols​

The following snippet queries the local DWN for protocols that match a given schema:

Querying Records​

The following snippet queries a given DWN for records that match a given schema and are in a specific data format.

Note the from property used here. Much like SQL, where the FROM command is used to specify which table to select data from, in Web5, from specifies which DWN to query.

note

records.query() does not guarantee that the data is returned unless it is under a specific threshold (50 kb). To guarantee record data, call records.read().

Filterable Record Properties​

Here are the properties you can use to filter your record query, along with explanations and examples for each.

PropertyValueExample
recipientRecipient DID of message"did:example:alice"
protocolThe URI of the protocol bucket in which to query"example.com"
protocolPathRecords under a protocol path across all context IDs"example"
contextIdrecordId of a root record of a protocol"bafyreianzpmhbgcgam5mys722vnsiuwn..."
schemaThe URI of the schema bucket in which to query"https://schema.org/Message"
recordIdProperty contains the message recordId"aa36ec55-c59b-4f20-8143-10f74aac696d"
parentIdrecordId of the parent record in a protocol"iadsfdreianzpmasdffcgam5mys722vnd..."
dataFormatThe IANA string for the data format to filter"application/json"
dateCreatedDate the record was created"2023-04-30T22:49:37.713976Z"
tagsUser-defined key-value pairs for categorizing records{"genre": "Action", "year": "2024"}

Filter by parentId​

This snippet queries the DWN for records that have a parent record with a specific record ID:

Filter by protocol and protocolPath​

Given the following protocol definition is installed:

Playlist Protocol Definition

And assuming playlist and video records have been created using this protocol, the following snippet demonstrates how to query for video records that match the protocol:

Sorting Query Results​

Query results can be sorted via the dateSort field. Valid values for dateSort are:

ValueSorts Results ByOrder
createdAscendingdateCreatedascending
createdDescendingdateCreateddescending
publishedAscendingdatePublishedascending
publishedDescendingdatePublisheddescending

Ascending Order​

This code snippet queries for records with a plain text data format, and returns them in ascending order by the date they were published:

Descending Order​

This code snippet queries for protocols with a certain URL, and returns them in descending order by the date they were created.

Connect with us on Discord

Submit feedback: Open a GitHub issue

Edit this page: GitHub Repo

Contribute: Contributing Guide