Genii Weblog
Branching out: More CRUD with domino-db
Tue 4 Feb 2020, 10:31 AM
Tweetby Ben Langhinrichs
Posts in this series:
- The tree you are busy hugging has new branches,
- Branching out: A few terms
- Branching out: REST, gRPC, and other gory details you can (mostly) ignore
- Branching out: No REST for the wicked - Part 1
- Branching out: No REST for the wicked - Part 2
- Branching out: Let's tackle Node.js
- Branching out: More CRUD with domino-db
- Branching out: Why the domino-db Document is not like NotesDocument
- Branching out: Models, msgs, and microservices
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.
Methods: Database.bulkReadDocuments
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
2) Create - Making a new document with a JSON JavaScript representation
We did this already in the previous post. Creating is very similar to the Domino Access Services POST method, though we use a JavaScript object rather than a JSON object. Note that these two look very similar, so be careful. See the sample code below to create a document:
If you look at the database.createDocument call, the entire argument is a JavaScript object. Extracted out, it looks like this:
Now, look at a JSON object with the same data:
They look similar, but be aware of the differences.
Methods: Database.createDocument, Database.bulkCreateDocuments
3) Update - Updating the contents of a Notes document and all its fields using JSON JavaScript object
Updating items/fields on a document:
The basic mechanism for updating is similar to that for creating. You pass a JavaScript object or array of objects to a method which updates the items. You can do this on a single document or multiple documents at once. Similar to Domino Access Services' REST API, you can use Document.replaceItems where you would use PATCH to replace just the specified items, or you could use Document.replace where you would use PUT. Using the latter Document.replace can be particularly nasty because you can't give replace the rich text and MIME fields, so they just get deleted. In most cases, I'd recommend you stick to Document.replaceItems unless you have a compelling reason to do otherwise, just as I'd recommend you use PATCH unless you have a compelling reason to do otherwise.
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.
What has been said: