Retrieve Documents
Retrieve data from Dash Platform
Overview
In this tutorial we will retrieve some of the current data from a data contract. Data is stored in the form of documents as described in the Dash Platform Protocol Document explanation.
Prerequisites
- node.js (v12+)
- Basic familiarity with JavaScript asychronous functions using async/await
- The Dash JavaScript SDK is initialized (covered in Connecting to EvoNet)
Code
Initializing the Client with a contract identity
The example below shows how access to contract documents via
<contract name>.<contract document>
syntax (e.g.tutorialContract.note
) can be enabled by passing a contract identity to the constructor. Please refer to the Dash JavaScript SDK documentation for details.
const Dash = require('dash');
const clientOpts = {
apps: {
tutorialContract: {
contractId: 'Q894cs83D8REQNo7mAetj1wPJK2W3svrwqaN61aP25W',
},
},
};
const client = new Dash.Client(clientOpts);
const getDocuments = async () => {
return client.platform.documents.get(
'tutorialContract.note',
{
limit: 1, // Only retrieve 1 document
},
);
};
getDocuments()
.then((d) => console.log(d))
.catch((e) => console.error('Something went wrong:\n', e))
.finally(() => client.disconnect());
Queries
The example code uses a very basic query to return only one result. More extensive querying capabilities are covered in the query syntax reference.
Example Document
The following examples show the structure of a note
document (from the data contract registered in the tutorial) returned from the SDK when retrieved with various methods.
The values returned by .toJSON()
include the base document properties (prefixed with $
) present in all documents along with the data contract defined properties.
Note: When using
.toJSON()
, binary data is displayed as a base64 string (since JSON is a text-based format).
The values returned by .getData()
(and also shown in the console.dir() data
property) represent only the properties defined in the note
document described by the tutorial data contract.
{
'$protocolVersion': 0,
'$id': '4K9T3mJPeDVJrSzWWgf82ngcjqpkaYBTx6Qgg9Mr6VA5',
'$type': 'note',
'$dataContractId': 'Q894cs83D8REQNo7mAetj1wPJK2W3svrwqaN61aP25W',
'$ownerId': 'BhC9M3fQHyUCyuxH4WHdhn1VGgJ4JTLmer8qmTTHkYTe',
'$revision': 1,
message: 'Tutorial Test @ Thu, 29 Oct 2020 20:39:40 GMT'
}
{
message: 'Tutorial Test @ Thu, 29 Oct 2020 20:39:40 GMT'
}
Tutorial Test @ Thu, 29 Oct 2020 20:39:40 GMT
Document {
dataContract: DataContract {
protocolVersion: 0,
id: Identifier(32) [Uint8Array] [
5, 236, 110, 66, 246, 123, 205, 227,
74, 231, 87, 141, 168, 144, 212, 48,
224, 134, 31, 51, 194, 251, 7, 199,
174, 122, 163, 170, 200, 63, 9, 105
],
ownerId: Identifier(32) [Uint8Array] [
158, 224, 179, 186, 104, 63, 179, 146,
194, 213, 42, 101, 129, 188, 237, 15,
21, 125, 1, 246, 65, 175, 92, 13,
146, 83, 56, 204, 175, 49, 103, 221
],
schema: 'https://schema.dash.org/dpp-0-4-0/meta/data-contract',
documents: { note: [Object] },
definitions: undefined,
binaryProperties: { note: {} }
},
entropy: undefined,
protocolVersion: 0,
id: Identifier(32) [Uint8Array] [
49, 57, 17, 154, 188, 135, 185, 215,
168, 240, 118, 208, 187, 133, 159, 11,
124, 204, 153, 237, 33, 101, 28, 76,
121, 20, 157, 193, 53, 7, 57, 214
],
type: 'note',
dataContractId: Identifier(32) [Uint8Array] [
5, 236, 110, 66, 246, 123, 205, 227,
74, 231, 87, 141, 168, 144, 212, 48,
224, 134, 31, 51, 194, 251, 7, 199,
174, 122, 163, 170, 200, 63, 9, 105
],
ownerId: Identifier(32) [Uint8Array] [
158, 224, 179, 186, 104, 63, 179, 146,
194, 213, 42, 101, 129, 188, 237, 15,
21, 125, 1, 246, 65, 175, 92, 13,
146, 83, 56, 204, 175, 49, 103, 221
],
revision: 1,
data: { message: 'Tutorial Test @ Thu, 29 Oct 2020 20:39:40 GMT' }
}
What's happening
After we initialize the Client, we request some documents. The client.platform.documents.get
method takes two arguments: a record locator and a query object. The records locator consists of an app name (e.g. tutorialContract
) and the top-level document type requested, (e.g. note
).
DPNS Contract
Note: Access to the DPNS contract is built into the Dash SDK. DPNS documents may be accessed via the
dpns
app name (e.g.dpns.domain
).
If you need more than the first 100 documents, you'll have to make additional requests with startAt
incremented by 100 each time. In the future, the Dash SDK may return documents with paging information to make this easier and reveal how many documents are returned in total.
Updated almost 4 years ago