marklogic-data-modeling

MarkLogic Data Modeling

Three decisions, in order: which models, how documents are shaped and named, and whether an envelope is warranted.

1. Model selection

Choose the least machinery that answers the query goals.

Use	When	Skip it when
Documents	always — the base model	never
Triples	cross-entity relationships, graph traversal, taxonomy links	relationships are simple parent-child → just nest them in the document
Vectors	semantic similarity, RAG, recommendations	no similarity requirement
TDE / Optic	GROUP BY, joins, aggregation	no analytical queries

State for each model you keep: why it fits, what it holds, what query capability it unlocks. Being explicit about what you are not using is as valuable as the inclusions.

2. Document design

• Collection strategy — one collection per entity type; a <source>-raw collection per source system when harmonizing.
• URI pattern — see §3.
• Range index candidates — the fields used for filtering, sorting, or ml_values_query. Check what exists with ml_indexes_list.
• TDE view candidates — the fields needing GROUP BY or JOIN.
• Never store "". Empty strings pollute range indexes, break range queries, and create misleading TDE rows. Omit the field, or use null.
• Dates as ISO-8601 strings, to match a dateTime range index scalar type.

3. URI design — six rules

URIs are stable identity. Get them wrong and every later query is awkward.

1. Prefix with the collection or entity type. The prefix is the directory; ml_document_list scopes to it. /orders/order-{orderId}.json ✓ — /{orderId}.json ✗ (no grouping possible)
2. Embed every primary key value. Deterministic and collision-free. Avoid UUIDs unless the source has no key. /events/gdelt/{GlobalEventID}.json ✓ — /orders/order.json ✗ (overwrites on every write)
3. Match the URI prefix to the collection short name. Collection orders → URIs under /orders/.
4. URL-safe characters only — letters, digits, /, -, _, .. Replace spaces and colons with -; turn slashes in values into path segments.
5. Right extension — .json / .xml for content, .sjs / .xqy for modules (Modules database), .tdej for JSON TDE templates (Schemas database).
6. Nest child entities under the parent key. /customers/{customerId}/orders/{orderId}.json lets you list one customer's orders by directory.