MarkLogic中dls:document-add-properties与xdmp:document-add-properties的区别

Great question! I’ve run into this exact confusion before when working with MarkLogic’s managed documents, so let me break down the key differences that matter most:

• Version History Integration
  dls:document-add-properties is built specifically for DLS (Document Library Services) managed documents. When you use it, property changes are tied to the document’s version history—so if you revert to an older version later, the properties from that version will be restored automatically. This keeps your metadata aligned with the document’s lifecycle.

  xdmp:document-add-properties is a generic utility that works on any document. For managed docs, it adds properties directly to the underlying database node, but these changes aren’t tracked in DLS’s versioning system. Create a new version later, and those properties might not carry over, leading to inconsistencies.

• DLS Rule Enforcement
  DLS functions enforce DLS-specific permissions and constraints. dls:document-add-properties will check if you have the right DLS roles (like dls-user or dls-admin), and it won’t let you modify a document that’s locked via DLS unless you have permission to unlock it.

  xdmp:document-add-properties only checks standard MarkLogic read/write permissions for the document. It ignores DLS locks and versioning rules, which could let you accidentally break the managed document’s workflow.

• Metadata Storage & Retrieval
  For managed documents, dls:document-add-properties stores properties in a structure integrated with DLS metadata. This makes it easy to retrieve properties alongside version info using other DLS functions like dls:document-properties.

  xdmp:document-add-properties stores properties directly on the document node, just like it would for a non-managed document. This decouples your metadata from DLS’s versioning, making it harder to track how properties changed across versions using DLS tools.

• When to Use Which

  • Stick with dls:document-add-properties for any DLS-managed document. It’s the safest way to ensure your property changes are part of the version history and comply with DLS workflows.
  • Use xdmp:document-add-properties only for non-managed documents, or if you have a very specific use case where you don’t want the property tied to the document’s version history (though this is rare for managed docs, as it can cause inconsistencies down the line).

Even though you saw the same immediate result in your test, the long-term behavior and integration with DLS will differ a lot. For managed documents, always go with the DLS-specific function to keep everything consistent.

内容的提问来源于stack exchange，提问作者ravi