MLE-28335 added fragment option in fromSearch

- Add 'fragment' option support to fromSearch() for MLS 12.1+
- Valid values: 'document' (default), 'properties', 'locks', 'any'
- Client-side validation in PlanSearchOption (plan-builder-base.js)
- Updated JSDoc for fromSearch() in plan-builder-generated.js
- Added xdmp-lock-acquire/release privileges to rest-evaluator role
  in both test-setup-users.js and rest-evaluator.json (Gradle config)
- Added fragment option integration tests to test-basic/plan-search.js
  (TC0-TC5, gated on serverVersion >= 12.1)

Author: RitaChen609

etc/test-setup-users.js

@@ -68,6 +68,16 @@ function setupUsers(manager, done) {
             'privilege-name': 'xdmp-get-session-field',
             action: 'http://marklogic.com/xdmp/privileges/xdmp-get-session-field',
             kind: 'execute'
+          },
+          {
+            'privilege-name': 'xdmp-lock-acquire',
+            action: 'http://marklogic.com/xdmp/privileges/xdmp-lock-acquire',
+            kind: 'execute'
+          },
+          {
+            'privilege-name': 'xdmp-lock-release',
+            action: 'http://marklogic.com/xdmp/privileges/xdmp-lock-release',
+            kind: 'execute'
           }
         ]
       }

lib/plan-builder-base.js

@@ -136,6 +136,13 @@ function castArg(arg, funcName, paramName, argPos, paramTypes) {
             throw new Error(
                 'bm25LengthWeight must be a number'
             );
+          case 'fragment':
+            if (['document', 'properties', 'locks', 'any'].includes(value)) {
+              return true;
+            }
+            throw new Error(
+                `${argLabel(funcName, paramName, argPos)} fragment can only be 'document', 'properties', 'locks', or 'any'`
+            );
           default:
             return false;
         }});

lib/plan-builder-generated.js

@@ -9012,7 +9012,7 @@ fromSearchDocs(...args) {
     * @param { PlanSearchQuery } [query] - Qualifies and establishes the scores for a set of documents. The query can be a cts:query or a string as a shortcut for a cts:word-query. The fragments are not filtered to ensure they match the query, but instead selected in the same manner as "unfiltered" cts:search operations.
     * @param { PlanExprColName } [columns] - Specifies which of the available columns to include in the rows. The available columns include the metrics for relevance ('confidence', 'fitness', 'quality', and 'score') and fragmentId for the document identifier. By default, the rows have the fragmentId and score columns. To rename a column, use op:as specifying the new name for an op:col with the old name.
     * @param { XsString } [qualifierName] - Specifies a name for qualifying the column names.
-    * @param { PlanSearchOption } [option] - Similar to the options of cts:search, supplies the 'scoreMethod' key with a value of 'logtfidf', 'logtf', 'simple', 'zero', 'random', or 'bm25' to specify the method for assigning a score to matched documents or supplies the 'qualityWeight' key with a numeric value to specify a multiplier for the quality contribution to the score. Specify a value between 0 (exclusive) and 1 (inclusive) for bm25LengthWeight if 'bm25' scoring method is used.
+    * @param { PlanSearchOption } [option] - Similar to the options of cts:search, supplies the 'scoreMethod' key with a value of 'logtfidf', 'logtf', 'simple', 'zero', 'random', or 'bm25' to specify the method for assigning a score to matched documents or supplies the 'qualityWeight' key with a numeric value to specify a multiplier for the quality contribution to the score. Specify a value between 0 (exclusive) and 1 (inclusive) for bm25LengthWeight if 'bm25' scoring method is used. As of MLS 12.1, supplies the 'fragment' key with a value of 'document' (default), 'properties', 'locks', or 'any' to specify which document fragment type to search. Note: on servers earlier than MLS 12.1, the 'fragment' option is silently ignored and all fragment types are searched.
     * @returns { planBuilder.AccessPlan }
     */
 fromSearch(...args) {

test-app/src/main/ml-config/security/roles/rest-evaluator.json

@@ -65,6 +65,16 @@
       "privilege-name": "xdmp-xslt-invoke",
       "action": "http://marklogic.com/xdmp/privileges/xslt-invoke",
       "kind": "execute"
+    },
+    {
+      "privilege-name": "xdmp-lock-acquire",
+      "action": "http://marklogic.com/xdmp/privileges/xdmp-lock-acquire",
+      "kind": "execute"
+    },
+    {
+      "privilege-name": "xdmp-lock-release",
+      "action": "http://marklogic.com/xdmp/privileges/xdmp-lock-release",
+      "kind": "execute"
     }
   ]
 }

test-basic/plan-search.js

@@ -308,4 +308,185 @@ describe('search', function() {
       }).catch(error => done(error));
     });
   });
+
+  describe('fragment option tests for fromSearch', function() {
+    const setupXquery = `
+      xquery version "1.0-ml";
+      let $jsondoc1 := object-node {"AllDataTypes": array-node {object-node {"word":"dog"}, object-node {"rank":1}, object-node {"score":4}}}
+      let $jsondoc2 := object-node {"AllDataTypes": array-node {object-node {"word":"cat"}, object-node {"rank":2}, object-node {"score":5}}}
+      let $jsondoc3 := object-node {"AllDataTypes": array-node {object-node {"word":"duck"}, object-node {"rank":3}, object-node {"score":6}}}
+      return (
+        xdmp:document-insert("range-prop-1.json", $jsondoc1, xdmp:default-permissions(), ("elemCol","jsondoc-range")),
+        xdmp:document-insert("range-prop-2.json", $jsondoc2, xdmp:default-permissions(), ("elemCol","jsondoc-range")),
+        xdmp:document-insert("range-prop-3.json", $jsondoc3, xdmp:default-permissions(), ("elemCol","jsondoc-range")),
+        xdmp:document-set-properties("range-prop-1.json", (<my-prop>opticfragmentpropvalue</my-prop>)),
+        xdmp:lock-acquire("range-prop-1.json", "exclusive", "0", "dog rose",  xs:unsignedLong(120)),
+        xdmp:lock-acquire("range-prop-2.json", "exclusive", "0", "cat tulip", xs:unsignedLong(120)),
+        xdmp:lock-acquire("range-prop-3.json", "exclusive", "0", "duck lily", xs:unsignedLong(120))
+      )
+    `;
+
+    const teardownReleaseLocks = `
+      xquery version "1.0-ml";
+      (
+        xdmp:lock-release("range-prop-1.json"),
+        xdmp:lock-release("range-prop-2.json"),
+        xdmp:lock-release("range-prop-3.json")
+      )
+    `;
+
+    const teardownDeleteDocs = `
+      xquery version "1.0-ml";
+      (
+        xdmp:document-delete("range-prop-1.json"),
+        xdmp:document-delete("range-prop-2.json"),
+        xdmp:document-delete("range-prop-3.json")
+      )
+    `;
+
+    before(function(done) {
+      if (serverConfiguration.serverVersion < 12.1) {
+        this.skip();
+      }
+      pbb.dbWriter.xqueryEval(setupXquery).result()
+        .then(() => done())
+        .catch(done);
+    });
+
+    after(function(done) {
+      pbb.dbWriter.xqueryEval(teardownReleaseLocks).result()
+        .then(() => pbb.dbWriter.xqueryEval(teardownDeleteDocs).result())
+        .then(() => done())
+        .catch(done);
+    });
+
+    // TC0: No fragment option — default behavior searches document content (same as fragment:'document')
+    it('TC0: fromSearch without fragment option should search document content by default', function(done) {
+      execPlan(
+        p.fromSearch(
+          p.cts.wordQuery('dog')
+        )
+        .joinDocAndUri('doc', 'uri', p.fragmentIdCol('fragmentId'))
+        .orderBy('uri')
+        .select(['uri', 'doc'])
+      ).then(function(response) {
+        const output = getResults(response);
+        assert(output.length === 1, 'Expected exactly 1 document containing "dog" with default fragment');
+        assert(output[0].uri.value === 'range-prop-1.json', 'Expected range-prop-1.json');
+        assert(output[0].doc.type === 'object', 'Expected default fragment to return JSON document');
+        assert(output[0].doc.value.AllDataTypes[0].word === 'dog', 'Expected word "dog" in document content');
+        done();
+      }).catch(done);
+    });
+
+    // TC0b: Invalid fragment value → client-side error (no server call needed)
+    it('TC0b: should throw error for invalid fragment value', function() {
+      assert.throws(function() {
+        p.fromSearch(
+          p.cts.wordQuery('dog'), null, null, { fragment: 'unknown' }
+        );
+      }, /fragment can only be/);
+    });
+
+    // TC1: fragment:'locks' — doc joined from locks fragment must be XML containing 'lock-type'
+    it('TC1: fromSearch with fragment:locks should find documents by lock token', function(done) {
+      execPlan(
+        p.fromSearch(
+          p.cts.locksFragmentQuery(p.cts.wordQuery('dog')),
+          null, null, { fragment: 'locks' }
+        )
+        .joinDocAndUri('doc', 'uri', p.fragmentIdCol('fragmentId'))
+        .orderBy('uri')
+        .select(['uri', 'doc'])
+      ).then(function(response) {
+        const output = getResults(response);
+        assert(output.length === 1, 'Expected exactly 1 result from locks fragment');
+        assert(output[0].uri.value === 'range-prop-1.json', 'Expected range-prop-1.json');
+        assert(output[0].doc.type === 'element', 'Expected lock doc to be XML element');
+        assert(output[0].doc.value.includes('lock-type'), 'Expected lock-type element in lock document');
+        done();
+      }).catch(done);
+    });
+
+    // TC2: fragment:'properties' — doc joined from properties fragment must be XML containing the property value
+    it('TC2: fromSearch with fragment:properties should find doc by its properties', function(done) {
+      execPlan(
+        p.fromSearch(
+          p.cts.wordQuery('opticfragmentpropvalue'),
+          null, null, { fragment: 'properties' }
+        )
+        .joinDocAndUri('doc', 'uri', p.fragmentIdCol('fragmentId'))
+        .orderBy('uri')
+        .select(['uri', 'doc'])
+      ).then(function(response) {
+        const output = getResults(response);
+        assert(output.length === 1, 'Expected exactly 1 result from properties fragment');
+        assert(output[0].uri.value === 'range-prop-1.json', 'Expected range-prop-1.json');
+        assert(output[0].doc.type === 'element', 'Expected properties doc to be XML element');
+        assert(output[0].doc.value.includes('opticfragmentpropvalue'), 'Expected property value in properties document');
+        done();
+      }).catch(done);
+    });
+
+    // TC3: fragment:'any' — returns all fragment types; verify both XML (lock/properties) and JSON (document) rows present
+    it('TC3: fromSearch with fragment:any should return results across fragment types', function(done) {
+      execPlan(
+        p.fromSearch(
+          p.cts.locksFragmentQuery(p.cts.wordQuery('dog')),
+          null, null, { fragment: 'any' }
+        )
+        .joinDocAndUri('doc', 'uri', p.fragmentIdCol('fragmentId'))
+        .orderBy('uri')
+        .select(['uri', 'doc'])
+      ).then(function(response) {
+        const output = getResults(response);
+        assert(output.length > 1, 'Expected multiple rows (all fragment types) with fragment:any');
+        const types = output.map(row => row.doc.type);
+        assert(types.includes('element'), 'Expected at least one XML fragment (lock or properties)');
+        assert(types.includes('object'), 'Expected at least one JSON document fragment');
+        done();
+      }).catch(done);
+    });
+
+    // TC4: fragment:'document' — doc must be JSON containing the word 'dog'
+    it('TC4: fromSearch with fragment:document should find documents by content word', function(done) {
+      execPlan(
+        p.fromSearch(
+          p.cts.wordQuery('dog'),
+          null, null, { fragment: 'document' }
+        )
+        .joinDocAndUri('doc', 'uri', p.fragmentIdCol('fragmentId'))
+        .orderBy('uri')
+        .select(['uri', 'doc'])
+      ).then(function(response) {
+        const output = getResults(response);
+        assert(output.length === 1, 'Expected exactly 1 document containing "dog"');
+        assert(output[0].uri.value === 'range-prop-1.json', 'Expected range-prop-1.json');
+        assert(output[0].doc.type === 'object', 'Expected document fragment to be JSON');
+        assert(output[0].doc.value.AllDataTypes[0].word === 'dog', 'Expected word "dog" in document content');
+        done();
+      }).catch(done);
+    });
+
+    // TC5: explain() on a locks fragment plan should return a valid execution plan structure.
+    // Note: the server-side equivalent (TEST26) additionally exercises plan:parse()/plan:execute()
+    // on the explain output, but the Node client has no equivalent of those functions.
+    it('TC5: explain() on a locks fragment plan should return a valid plan structure', function(done) {
+      const plan = p.fromSearch(
+        p.cts.locksFragmentQuery(p.cts.wordQuery('dog')),
+        null, null, { fragment: 'locks' }
+      )
+      .joinDocAndUri('doc', 'uri', p.fragmentIdCol('fragmentId'))
+      .orderBy('uri')
+      .select(['uri', 'doc']);
+
+      pbb.explainPlan(plan)
+        .then(function(output) {
+          assert(output.node === 'plan', 'Expected explain output to have node:"plan"');
+          assert(output.expr != null, 'Expected expr to be present in explain output');
+          done();
+        })
+        .catch(done);
+    });
+  });
 });