Posts in this series:
It occurs to me that it would be useful to contrast the CRUD (or ARCUD for Access/Read/Create/Update/Delete) of domino-db with that of Domino Access Services, as I covered it in those two REST posts. There are some very clear, probably not coincidental, similarities. At the end (if I remember), I'll point out an implied similarity that may have profound implications for domino-db's future plans.
I'm going to try to cover this in one post rather than two. If you are confused because I take too many shortcuts, leave a comment and I'll revise the post.
0) Access - Getting a list of collections (views and folders) documents from a database
On this first item, there is a huge difference between DAS (Domino Access Services). DAS approaches access from the traditional Notes mind set of collections of documents in views, so you get a list of views, pick a view, get a list of documents, and then pick a document. But domino-db comes with a different mind set, closer to an SQL query wold view. In this case, DQL is the query language. You start with a DQL query. Period. No second option. You access a document from the results of the query by UNID, not a user friendly value, so you have both the power and responsibility to pull in other values which help you choose a document.
In short, access is through Database.bulkReadDocuments which uses a DQL query to find documents. I guess I'll have to address DQL in another post.
1) Read - Getting the contents of a Notes document and all its fields in JSON
After the big differences in accessing documents, it is nice to see direct parallels when reading a document. There are other alternatives, but essentially you use Document.read to get a JSON object containing metadata such as UNID plus the items in the document. Well, kind of. You have to tell it which items to retrieve, by name, and it won't return rich text or MIME or other "advanced" types. What if you don't know what fields there are? If you know the form, you can often figure out many of the fields, but not those created by processes and agents. If you don't already have a list of fields for the form, you are searching blind.
This is not all bad. It means that it is harder to fish for information that is hidden, whereas the Domino Access Services gives up all its secrets too easily. Still, it is an issue.
Methods: Database.bulkReadDocuments, Database.bulkReadDocumentsByUnid, Document.read
Now, look at a JSON object with the same data:
They look similar, but be aware of the differences.
Methods: Database.createDocument, Database.bulkCreateDocuments
Updating items/fields on a document:
There is another kind of update which is not available to Domino Access Services, though I wish it were. That is the ability to delete specific items. In DAS, the closest way is to do a PUT with everything but the items to delete. This is far more elegant and useful, as you can just specify the items to delete. This can be done on a specific item
While most of these methods expect you to identify the specific items to update or delete for each document, the Database.bulkReplaceItems and Database.bulkDeleteItems are different. These two method let you specify a list of items for all documents that match the DQL query. This allows you to do things like change the status of all documents that match a query selection and so forth. (It also provides a huge opportunity for a software extension I will be announcing, but that is a different story.)
Methods akin to PATCH: Database.bulkReplaceItems, Database.bulkReplaceItemsByUnid, Document.replaceItems
Methods akin to PUT: Database.bulkReplaceDocumentsByUnid, Document.replace
Methods that delete items: Database.bulkDeleteItems, Database.bulkDeleteItemsByUnid,Document.deleteItems
Updating attachments on a document:
While rich text and MIME are not supported, there is an ability to add or delete attachments. I haven't played with this enough to speak knowledgeably about it (as if anything I say is particularly knowledgeable), but it is not as intuitive or easy a concept as attaching documents might seem. I'm guessing this will be a topic for a different post, once I get my head around it. Ugh! This series may go on until I retire at this rate.
Methods: Database.bulkCreateAttachmentStream, Document.deleteAttachments, Document.deleteAttachments
4) Delete - Getting rid of a Notes document
Finally, we can delete documents, either one at a time or in bulk using UNIDs or in bulk using a DQL query. That last one, Database.bulkDeleteDocuments, is particularly powerful. Be careful about your DQL syntax, as you'd hate to delete all the documents in a database because you wrote a sloppy DQL query. As Velma might say in such a situation, Jinkies!
Methods: Database.deleteDocuments, Database.deleteDocumentsByUnid, Document.delete
That's all I have for now. Peace out.
Copyright © 2020 Genii Software Ltd.
Tags: HCL Domino Domino-db appdev NodeJS