Entity Instance Query

Use POST /api/workspace/entity/{entityIdOrKey}/instances/query for server-side paging, filters, sorting, and reference includes. Read the installation’s OpenAPI and query options before constructing a request. Never guess field IDs, field keys, system-field IDs, operator values, or supported targets.

This endpoint returns a flat result set. A configured Parent Tree View runtime reuses the same filter and sort language but bootstraps roots and loads direct-child sibling pages through context-preserving Entity UI routes.

Configured record search

The list search box uses this same query endpoint. When the Entity Definition has explicit search targets, query options expose the special SearchTerm field; send it as a Contains condition in the ordinary filter tree. The Web Application’s search URL state is client-side state that is translated into that condition, not a separate Runtime API route or query-string contract.

Search-target configuration, the exact condition payload, literal-substring semantics, relation and Table paths, concurrency, and removed full-text contracts are documented in Entity search. Normal substring terms contain 3 to 256 trimmed characters. Exact #number matches only Number, while #{record-id} matches only Id; both shortcuts may be shorter and remain capped at 256 characters.

Related filter and sort payload

This query filters AidRecord through Community -> District -> Region and sorts by the Region display name:

{
  "Page": 1,
  "PageSize": 25,
  "ArchiveMode": 0,
  "Filter": {
    "Operator": 0,
    "Conditions": [
      {
        "Target": {
          "Path": [
            { "FieldId": "field-community", "FieldKey": "Community" },
            { "FieldId": "field-district", "FieldKey": "District" },
            { "FieldId": "field-region", "FieldKey": "Region" }
          ]
        },
        "Operator": 7,
        "Values": [
          { "Kind": 0, "Value": "region-record-id-1" },
          { "Kind": 0, "Value": "region-record-id-2" }
        ]
      }
    ],
    "Groups": null
  },
  "Sort": [
    {
      "Target": {
        "Path": [
          { "FieldId": "field-community", "FieldKey": "Community" },
          { "FieldId": "field-district", "FieldKey": "District" },
          { "FieldId": "field-region", "FieldKey": "Region" }
        ]
      },
      "Direction": 0
    }
  ]
}

Operator: 0 is Eq; Operator: 7 is In. A terminal Reference compares record IDs, so the operands above are Region record IDs, not Community IDs and not display names. Sorting a terminal Reference uses its Display Name.

For a system field of a related entity, make the synthetic system field the last path segment:

{
  "Target": {
    "Path": [
      { "FieldKey": "Community" },
      { "FieldKey": "District" },
      { "FieldId": "$system:ModifiedAt" }
    ]
  },
  "Direction": 1
}

Copy synthetic system IDs from installation-provided options; do not construct them from this example.

ID and key resolution

Each path segment may use FieldId, FieldKey, or both. Resolution starts on the queried entity definition. After a Reference, the next segment is resolved on that reference’s target definition.

If both ID and key are present, they must identify the same field. A stale ID paired with a current key is an error, not a fallback. Display labels are never field keys.

Use Field only for a direct, one-segment condition or sort. Use Target.Path for related paths. Configuration-provided runtime items expose the exact FilterTarget or SortTarget to copy.

Groups and saved/shared views

Filter.Operator is the group operator (0 = And, 1 = Or). Conditions[] and nested Groups[] can be combined recursively. Table saved views and shared views preserve this query structure, including every complete target path. A configured item is matched to a restored condition by the full canonical path, not by its first segment.

Limits and supported paths

• Filter Target.Path: 1 to 6 segments.
• Sort Target.Path: 1 to 4 segments.
• Applied Sort: at most 3 items.
• Intermediate segments: readable primary-table Reference fields only.
• Terminals: field and system-field targets supported by the query options.
• Table and InverseReference are not deep terminals.
• RowsFilter is a separate direct-Table mechanism and cannot be used as a reference-path hop.
• Statements and object-context facts use their root condition contracts; they are not transported through references.

The terminal option controls operators and operand shape. Use the returned FilterOperators, FieldType, AllowMultiple, reference target definition, classifier metadata, and row-filter options instead of inferring them.

Select and enum operands use option keys

For a Select field, including a generated C# enum projection, send the stable string option key. Do not send the numeric enum ordinal or the display label:

{
  "Target": { "Path": [{ "FieldKey": "Status" }] },
  "Operator": 0,
  "Values": [{ "Kind": 0, "Value": "Parsed" }]
}

Here "Parsed" is the configured option key. A numeric value such as 0 is invalid even if it happens to be the enum’s current ordinal. Invalid operands return HTTP 400 with moltaro.instances.query.operand.invalid; provider exception details are not part of the response.

For a String or Text field whose SemanticRole is Markdown, the raw field Value remains exact Markdown source while compact read contracts may include a separate PlainTextPreview. Treat CanSort=false as authoritative: Markdown is not sortable. Use only the field option’s returned closed FilterOperators and never strip Markdown or render source as trusted HTML in the client.

DateTimeOffset precision

Direct Runtime API DateTimeOffset operands are exact instants. Send ISO 8601 with an explicit Z or numeric offset; equality compares the exact normalized timestamp, including seconds and microseconds.

The Web Application intentionally exposes a minute-precision filter. It keeps the readable condition in saved and shared views, but expands the executable request into exact half-open UTC ranges. For example, UI equality at 10:00 executes as >= 10:00:00 AND < 10:01:00, and a UI Between includes the complete first and last selected minutes. This is a Web Application presentation contract, not a change to direct API operator semantics. An API integration that needs minute-level behavior must construct the equivalent grouped range explicitly.

Null, archived, and permission semantics

• If an intermediate reference is null, a deep condition does not match.
• During sorting, a broken reference chain produces a null sort value. Stable pagination still uses the server’s deterministic tie-breaker.
• Related records are evaluated independently from the root archive mode: active related records require ordinary view access, while archived related records require applicable read-archive access.
• Every hop is checked for the current caller. A filter or sort cannot grant definition, field, record, or archive access.
• Restricted related records must not be disclosed through matches, totals, ordering, lookup labels, or unavailable-target diagnostics.

Execution remains server-side. Related filters compile to the existing correlated/EXISTS plans and related sorts to the existing join plans. Clients must not fetch all rows for local filtering, and they do not need an N+1 read loop.

Common errors

Symptom	Check
Empty or over-depth path	Copy a complete target from options and check the limits above.
ID/key mismatch	Refresh schema/options and replace the stale segment pair.
Unknown segment	Resolve each segment relative to the preceding reference target.
Unsupported intermediate	Confirm it is a primary-table Reference, not a scalar, Table, or InverseReference.
Operator rejected	Use the terminal option’s FilterOperators.
Reference values never match	Send terminal record IDs, not labels or IDs from the root reference entity.
Configured target is unavailable at runtime	Test with the actual user; inspect definition, field, record, and archive permissions at every hop.
Duplicate Table Surface filter	Compare the complete canonical Target.Path; only an exact path duplicate conflicts.

For authoring a Table Surface, start with Table filters and sorting. For generated schemas and exact enum values, use the Runtime API reference and the current installation’s OpenAPI.