SSJS 的 DocumentCollection:stampAll 一次改全部,removeAll 一次刪全部
你在 SSJS 跑了一個 database.search("Form = 'Order' & Status = 'Pending'"),拿到一堆待處理訂單,現在要把它們全部標成「已處理」。第一反應:getFirstDocument / getNextDocument 一路跑,每份 replaceItemValue 再 save。
可以,但 NotesDocumentCollection 本身就有批次招式——stampAll 一次把整批文件的某個欄位改成同一個值,一行、不用迴圈、不用逐份 save:
col.stampAll("Status", "Processed"); // 整個 collection 的 Status 都設成 Processed而它還有一個更兇的兄弟:removeAll 一次把整批文件永久刪掉。威力很大,但 removeAll 尤其要小心——它會精準照你給的 collection 刪,而且是永久的。這篇就講怎麼拿到並走訪一個 collection、這兩個批次招式與風險、怎麼組合 collection,以及它們用誰的權限跑。
拿到與走訪:Count 是屬性,不是 getCount
SSJS 裡,database 全域的 search(formula) / FTSearch(query)、或 view.getAllDocumentsByKey(key),回的都是 NotesDocumentCollection——官方定義就是「Represents a collection of documents from a database」。走訪照舊:
var col = database.search("Form = 'Order'");var doc = col.getFirstDocument();while (doc != null) { // 處理 doc… doc = col.getNextDocument(doc);}一個小坑:要數量是 col.Count(屬性)、不是 getCount()。官方頁列的是 Count 這個唯讀屬性,沒有 getCount 方法——在 SSJS 寫 col.getCount() 會錯。要跳到第幾筆用 getNthDocument(n)。
兩個批次招式:stampAll 與 removeAll
這才是 collection 比「自己迴圈」值得學的地方——不用把文件一份份拉出來、也不用逐份 save:
stampAll(itemName, value):官方「Replaces an item’s value in every document in the collection」。整個 collection 的某個欄位一次設成同一值。要把一批訂單全標成已處理、或蓋上處理時間,一行就好。removeAll:官方「Permanently deletes the collection’s documents from the database」。整批永久刪除。
removeAll 的風險很具體:它刪的是你手上這個 collection——如果你的 search 公式寫太寬、或 collection 不是你以為的那批,它會一聲不響地把多的也刪掉,而且救不回來。動 removeAll 前,先用 Count 和抽查幾筆確認這個 collection 真的是你要刪的那批。
組合 collection:FTSearch 窄化、集合運算
拿到一個 collection 後,還能再加工:
FTSearch(query):對現有 collection 再做一次全文搜尋、把它窄化成符合的子集(前提是有全文索引)。intersect/merge/subtract:集合運算——保留同時也在另一批的(交集)、把另一批併進來(聯集)、把另一批移除(差集)。要「A 查詢的結果裡,排除 B 查詢的」這種組合條件,比寫一條複雜公式乾淨。
誰的權限?stampAll / removeAll 都受 ACL 管
這些批次操作在 SSJS 裡走的是當前使用者的憑證——stampAll 改得動、removeAll 刪得掉,前提是這個使用者對那些文件有足夠權限(作者/編輯/刪除權)。一個一般使用者用 removeAll 刪不掉他沒權限的文件,這是對的。反過來,如果你要以更高權限做批次維護(例如清一批稽核紀錄),就得從 sessionAsSigner.getDatabase(...) 取庫再 search——這套 SSJS 權限模型見 XPages 的 database 用誰的權限開。
另外在 XPages 裡,跑一個大 collection(尤其是迴圈逐份處理)別掛在每次 partial refresh 的路徑上——跟所有貴的後端操作一樣,放進事件、必要時快取。collection 的生命週期由 XPages request 管,你不像 Java standalone 那樣需要自己 recycle。
同類別在其他語言
同一個 NotesDocumentCollection:
- LotusScript:
NotesDocumentCollection,StampAll/RemoveAll/Intersect都在;LS 側的完整用法見 NotesDocumentCollection 那篇。 - Java:
DocumentCollection,方法同名——但多一件事:collection、每份 document 用完要recycle()。 - SSJS 專屬的不是 API(方法共用),而是在 XPages 裡怎麼用:批次操作走使用者權限、要提權走
sessionAsSigner、大 collection 別掛在 render path,而且不用自己 recycle。
參考來源
- NotesDocumentCollection (JavaScript)(走訪、Count、stampAll / removeAll / FTSearch / intersect)— HCL Domino 14.5 Designer Help(官方)
- NotesDatabase (JavaScript)(search / FTSearch 回傳 NotesDocumentCollection)— HCL Domino 14.5 Designer Help(官方)
- Global objects and functions (JavaScript)(database 全域)— HCL Domino 14.5 Designer Help(官方)