MarkLogic 12 EA 1 Product Documentation

xdmp.documentAssign

xdmp.documentAssign(
   uri as String,
   forest-count as Number,
   [assignment-policy as String]
) as Number

Summary

Assign a document URI to a forest index, using the same algorithm as xdmp:document-insert. The return value will be a positive integer from 1 to $forest-count.

This function does not insert or update the document; instead, it returns the index of the forest to which the document URI would be assigned if it were inserted as a new document. In order to match the document to the correct forest, use the list of forest-IDs as returned by xdmp:database-forests.

If the document already exists, this function may not return the correct forest for the document. In this case, xdmp:document-forest will return the correct forest.

If "assignment-policy" is specified, this function uses the specified policy to calculate the assignment. Otherwise, it uses the assignment policy of the context database to calculate the assignment.

This function works only with the bucket assignment policy, the segment assignment policy and the (now deprecated) legacy assignment policy. It reports an error if any other policy is specified.

Note that, if there are read-only or delete-only forests in a database that uses the bucket policy, the application may need to call this function twice to get the right assignment. The first call should pass in the total number of forests, including the read-only or delete-only ones. If the returned value happens to be a read-only or delete-only forest, the second call should pass in the number of forests that excludes the read-only or delete-only ones and pass in "legacy" as the third parameter.

Example

xdmp.documentAssign("document-1.xml", 2)
=> 2