getDocument

Retrieves one document by its id.

💡 A missing document is not an error. You get a normal response with document set to null, so check for null rather than waiting for a failure.

Request

method is "getDocument".

Field	Type	Required	Description
`collection`	String	Yes	The collection to read from.
`document_id`	String	Yes	The document to fetch.
`app_id`	String	Optional	The app the document belongs to. Defaults to the bot's own app.
`reference`	String	Optional	Your id for this request. Echoed back in the response.

To fetch several documents at once, or to search by content rather than id, use listDocuments instead.

Response

getDocumentResponse

Field	Type	Returned	Description
`method`	String	Yes	`"getDocumentResponse"`
`collection`	String	Yes	Echoed from the request.
`document_id`	String	Yes	Echoed from the request.
`document`	Object	Yes	The stored document, or `null` if the id does not exist.
`app_id`	String	Yes	Echoed from the request.
`reference`	String	Optional	Echoed from the request.

SDKs

SDK	Call	Callback
Java	`store.getDocument(api, collection, documentId, reference);`	`onDocumentResponse(DocumentResponse response)`
JavaScript	`store.getDocument(api, collection, documentId, reference);`	`onDocumentResponse(response)`
Python	`store.get_document(api, collection, document_id, reference)`	`on_document_response(self, response)`

Example

Request

json
{
  "method": "getDocument",
  "collection": "orders",
  "document_id": "42",
  "app_id": "90090684293000559",
  "reference": "123456789"
}

java
DocumentStore.getInstance().getDocument(api, "orders", "42", "123456789");

// in the callback
@Override
public void onDocumentResponse(DocumentResponse response) {
    JSONObject document = response.getDocument();
    if (document == null) {
        System.out.println("no such document");
        return;
    }
    System.out.println(document.get("status"));
}

javascript
const store = require('nandbox-bot-api/src/util/DocumentStore')

store.getDocument(api, 'orders', '42', '123456789')

// in the callback
nCallBack.onDocumentResponse = response => {
  if (!response.document) return console.log('no such document')
  console.log(response.document.status)
}

python
from nandboxbots.util.DocumentStore import DocumentStore

DocumentStore.get_instance().get_document(api, "orders", "42", "123456789")

# in the callback
def on_document_response(self, response):
    if response.document is None:
        print("no such document")
        return
    print(response.document["status"])

Response

json
{
  "method": "getDocumentResponse",
  "collection": "orders",
  "document_id": "42",
  "app_id": "90090684293000559",
  "reference": "123456789",
  "document": {
    "status": "shipped",
    "total": 149.5,
    "region": "EG"
  }
}

When the id does not exist:

json
{
  "method": "getDocumentResponse",
  "collection": "orders",
  "document_id": "does-not-exist",
  "app_id": "90090684293000559",
  "reference": "123456789",
  "document": null
}