.. 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.

Querying Protocols

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

const { protocols } = await web5.dwn.protocols.query({
message: {
filter: {
protocol: 'https://music.org/protocol',
},
},
});

Querying Records

The following snippet queries a DWN for records that were written by a specific DID, match a given schema, and are in a specific data format:

const { records } = await web5.dwn.records.query({
from: did,
message: {
filter: {
schema: 'https://schema.org/Playlist',
dataFormat: 'application/json',
},
},
});
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"

Filter by parentId

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

const response = await web5.dwn.records.query({
message: {
filter: {
parentId: 'bafyreianzpmhbgcgam5mys722vnsiuwn7y4ek6kjeyjptttquasw4hge2m',
},
},
});

Filter by protocol and protocolPath

Given the following protocol definition is installed:

Playlist Protocol Definition
const playlistProtocolDefinition =  {
protocol: "https://playlist.org/protocol",
published: true,
types: {
playlist: {
schema: "https://schema.org/MusicPlaylist",
dataFormats: ["application/json"],
},
audio: {
schema: "https://schema.org/AudioObject",
dataFormats: ["audio/mp3"],
},
video: {
schema: "https://schema.org/VideoObject",
dataFormats: ["video/mp4"],
},
},
structure: {
playlist: {
$actions: [
{ who: "anyone", can: "write" },
{ who: "author", of: "playlist", can: "read" },
{ who: "recipient", of: "playlist", can: "read" },
],
audio: {
$actions: [
{ who: "anyone", can: "write" },
{ who: "author", of: "audio", can: "read" },
{ who: "recipient", of: "audio", can: "read" },
],
},
video: {
$actions: [
{ who: "anyone", can: "write" },
{ who: "author", of: "video", can: "read" },
{ who: "recipient", of: "video", can: "read" },
]
},
},
}
};

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:

const { records } = await web5.dwn.records.query({
message: {
filter: {
protocol: 'https://playlist.org/protocol',
protocolPath: 'playlist/video'
},
},
});

Sorting Query Results

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

ValueSorts Results ByOrder
createdAscendingdateCreatedascending
createdDescendingdateCreateddescending
publshedAscendingdatePublishedascending
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:

const response = await web5.dwn.records.query({
message: {
filter: {
dataFormat: 'text/plain',
},
dateSort: 'publishedAscending',
},
});

Descending Order

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

const { protocols } = await web5.dwn.protocols.query({
message: {
filter: {
protocol: 'http://social-media.xyz',
},
dateSort: 'createdDescending'
},
});

Connect with us on Discord

Submit feedback: Open a GitHub issue

Edit this page: GitHub Repo

Contribute: Contributing Guide