Xpath Constraints

XPath Constraints in MDL

This skill provides reference for writing XPath constraint expressions in MDL RETRIEVE statements, page data sources, and security rules.

When to Use This Skill

• Writing retrieve ... where [xpath] statements in microflows
• Writing database from entity where [xpath] in page data sources
• Writing grant ... where 'xpath' for row-level entity access
• Debugging XPath parsing or serialization issues

XPath vs Mendix Expressions

Critical distinction: XPath constraints (inside [...]) use different syntax from Mendix expressions (in SET, IF, DECLARE, etc.):

XPath constraints cannot compute values. where [Seq = $Game/MoveSeq + 1] is a parse error (Mendix XPath has no arithmetic on the value side). Compute the value first, then compare against the variable:

declare $Next integer = $Game/MoveSeq + 1;
retrieve $M from Mod.Move where [Seq = $Next] first;

mxcli check explains this and shows the workaround when it sees +/*/div/ mod inside a constraint.

A negative literal is fine, though. A leading - on a number is a value, not arithmetic, and needs no quoting:

retrieve $L from Mod.T where [Amount > -7];
retrieve $L from Mod.T where [Amount <= -12.5 and Code != 'X'];

Date arithmetic is not available in XPath. addDays(), addMonths() and friends are Mendix expression functions — using one in a constraint fails the build with CE0161 regardless of its arguments. For relative dates use the date tokens ([%CurrentDateTime%], [%BeginOfCurrentDay%], …), or compute the cut-off in a variable first and compare against that:

declare $Cutoff datetime = addDays([%CurrentDateTime%], -7);
retrieve $L from Mod.T where [DueDate > $Cutoff];

Syntax Reference

Simple Comparisons

retrieve $Orders from Module.Order
  where [State = 'Completed'];

retrieve $Active from Module.Customer
  where [IsActive = true];

retrieve $Recent from Module.Order
  where [OrderDate != empty];

retrieve $HighValue from Module.Order
  where [TotalAmount >= $MinAmount];

Operators: =, !=, <, >, <=, >=

Inline vs quoted form. The inline bracket form where [State = 'Completed'] is preferred. The quoted form — where '[State = ''Completed'']', with internal single quotes doubled ('') — is also accepted for retrieve and datasource where clauses, and now stores the identical constraint (it un-escapes the '' and strips the outer quotes). Don't double-bracket: write either [...] or '[...]', not both.

Boolean Logic

-- AND
where [State = 'Completed' and IsPaid = true]

-- OR
where [State = 'Pending' or State = 'Processing']

-- Grouped
where [State = 'Completed' and ($IgnorePaid or IsPaid = true)]

-- NOT
where [not(IsPaid)]
where [not(contains(Name, 'demo'))]

How a Constraint Is Laid Out on Disk

MDL keeps a constraint on one line; how it is stored is decided by mxcli, not by the whitespace you type. A constraint is rebuilt from its parse tree on every write, so there is no original formatting to keep — instead the layout is derived from the expression:

• 80 columns or fewer → stored exactly as written, on one line. This is the common case, and it means adding this changed nothing about existing projects.
• Longer → broken at its top-level and/or joints, one clause per line, the operator leading each continuation line. Where and and or meet, the and runs get explicit parentheses — Mendix binds and tighter, and a filter is being broken up precisely because it had stopped being obvious at a glance.
• Nothing to break on (one long comparison, one long association path) → left whole and over width. Cutting it anywhere else would not be valid XPath.

-- authored (one line, 141 characters)
where [Archived = false and Status = 'Open' and Priority = 'High' and Category = 'Electrical' and Severity > 3 and ReportedOn > '[%BeginOfCurrentDay%]']

-- stored, and what Studio Pro's XPath editor shows
[
  Archived = false
  and Status = 'Open'
  and Priority = 'High'
  and Category = 'Electrical'
  and Severity > 3
  and ReportedOn > '[%BeginOfCurrentDay%]'
]

DESCRIBE puts it back on one line, so a description reads the way it always has and re-executing it re-derives the same stored text — the unit is reported Unchanged. A constraint mxcli cannot parse is stored exactly as given rather than reformatted.

This applies to page datasources, retrieve … where in microflows, and entity access rules alike.

Association Path Traversal

Bare association paths (without $variable prefix) navigate through the domain model:

-- Single-hop: filter by associated object
where [Module.Order_Customer = $Customer]

-- Multi-hop: traverse through associations
where [Module.Order_Customer/Module.Customer/Name = $CustomerName]

-- Existence check: has an associated object
where [Module.Order_Customer/Module.Customer]

-- Negated existence: has NO associated object
where [not(Module.Order_Customer/Module.Customer)]

Rule: Always use the fully qualified association name (Module.AssociationName).

A bare association name is now caught before the build (MDL-XPATH01). [Order_Customer = $currentUser] used to pass mxcli check --references, get written by exec, and only fail at the build with "Error(s) in XPath constraint" (CE0161) — which is the expensive shape, because exec cannot roll back and stops with the model half-updated. check now names the association and the qualified spelling to use instead. It fires only when the bare name is not an attribute of the constrained entity and is a known association, so attributes stay bare and XPath functions are never touched.

= empty / != empty do not work on associations (CE0161 / MDL047). empty tests attribute nullability only. To test whether an object has no associated object, use negated existence: [not(Module.Order_Customer/Module.Customer)] — not [Module.Order_Customer = empty]; to test that it has one, the path itself: [Module.Order_Customer/Module.Customer] — not != empty. mxcli check flags both forms as MDL047 before the build does.

Variable Paths

-- Compare attribute via variable path
where [Module.Assoc/Module.Entity/Name = $Variable/Name]

-- Variable on right side
where [Name = $currentObject/SearchString]

Nested Predicates

Filter intermediate path steps with inline [predicate]:

-- Only lines of completed orders
where [Module.OrderLine_Order/Module.Order[State = 'Completed']]

-- Nested predicate with further traversal
where [Module.OrderLine_Order/Module.Order[State = 'Active']/Module.Order_Category/Module.Category/Name = $CategoryName]

-- reversed() path modifier (traverse association in reverse direction)
where [System.grantableRoles[reversed()]/System.UserRole/System.UserRoles = '[%CurrentUser%]']

Functions

-- String search
where [contains(Name, $SearchStr)]
where [starts-with(Name, $Prefix)]
where [not(contains(Name, 'demo'))]

-- Boolean functions
where [IsActive = true()]
where [Displayed = false()]

Supported functions: contains(), starts-with(), not(), true(), false()

The expression functions startsWith() / endsWith() are not XPath: in a constraint they are CE0161, and check reports them as MDL091. So is an operator inside a function argument — starts-with(Name, 'MS-' + $Key) is CE0161 although Name = 'X-' + $Key is fine: compute the value into a variable first (declare $P String = 'MS-' + $Key;, then starts-with(Name, $P)). A member the entity does not have is a reference error in check -p, and so is a system member written the way describe prints the attribute: XPath spells it createdDate, changedDate, owner, changedBy — [CreatedDate > …] is CE0161.