Table filters and sorting

Table surfaces can filter and sort by a field reached through a chain of ordinary references. A record type does not need separate Community, District, and Region fields to expose all three controls.

For an AidRecord that stores only Community, a table may expose:

• Community
• Community / District
• Community / District / Region

The complete query path is the target identity. These three targets may coexist because their paths differ, even though they share the same first field. Only an exact duplicate of the complete path is rejected.

When the Table Surface uses Parent Tree View, each root or child sibling set is sorted independently by the server. Search and filters retain visible ancestor context; changing the query reloads roots and branches.

Read supported targets first

Read the installation-provided options before writing configuration:

GET /api/workspace/admin/entity-definitions/{aidRecordDefinitionId}/ui/table-surfaces/configuration/options

FilterTargets[] and SortTargets[] contain human-readable labels, stable technical keys, field metadata, operators, and the complete typed path. Match the desired labels and copy the returned Target or SortTarget object. Do not guess record IDs, field IDs, field keys, or enum values.

A field segment may contain both EntityFieldDefinitionId and EntityFieldKey. When both are supplied, they must identify the same field. Each segment after the first is resolved relative to the entity definition targeted by the preceding reference.

Configure three filters with one root

The following abbreviated request shows the relevant table properties. The IDs are examples; copy the real targets from your options response.

{
  "FilterItems": [
    {
      "Target": {
        "TargetKind": 0,
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" }
        ]
      },
      "Label": "Community",
      "Visible": true,
      "VisibleByDefault": true,
      "ReferenceInputType": 2,
      "ReferenceRendererType": 0,
      "ReferencePath": [],
      "SortOrder": 10
    },
    {
      "Target": {
        "TargetKind": 0,
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" },
          { "EntityFieldDefinitionId": "field-district", "EntityFieldKey": "District" }
        ]
      },
      "Label": "District",
      "Visible": true,
      "VisibleByDefault": true,
      "ReferenceInputType": 2,
      "ReferenceRendererType": 0,
      "ReferencePath": [],
      "SortOrder": 20
    },
    {
      "Target": {
        "TargetKind": 0,
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" },
          { "EntityFieldDefinitionId": "field-district", "EntityFieldKey": "District" },
          { "EntityFieldDefinitionId": "field-region", "EntityFieldKey": "Region" }
        ]
      },
      "Label": "Region",
      "Visible": true,
      "VisibleByDefault": true,
      "ReferenceInputType": 2,
      "ReferenceRendererType": 0,
      "ReferencePath": [],
      "SortOrder": 30
    }
  ],
  "SortItems": [
    {
      "Target": {
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" },
          { "EntityFieldDefinitionId": "field-district", "EntityFieldKey": "District" },
          { "EntityFieldDefinitionId": "field-region", "EntityFieldKey": "Region" }
        ]
      },
      "Label": "Region",
      "Visible": true,
      "SortOrder": 10
    }
  ],
  "DefaultSort": [
    {
      "Target": {
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" },
          { "EntityFieldDefinitionId": "field-district", "EntityFieldKey": "District" },
          { "EntityFieldDefinitionId": "field-region", "EntityFieldKey": "Region" }
        ]
      },
      "Direction": 0,
      "SortOrder": 10
    }
  ]
}

Use the other required properties from the current table configuration when sending the replace request.

Target.Path is not ReferencePath

These properties solve different problems:

• Target.Path identifies the terminal field used by the server-side query. In the Region filter above, the picker values are Region record IDs.
• ReferencePath controls breadcrumb rendering inside a reference value picker. It never changes which field is filtered.

Changing ReferencePath cannot turn a Community filter into a Region filter. For a related target, copy the full Target.Path from FilterTargets[], then choose ReferencePath independently from that target’s ReferencePathOptions[].

Validation and limits

• Filter paths contain 1 to 6 segments.
• Sort paths contain 1 to 4 segments.
• A request may apply at most 3 sort items.
• Every intermediate segment must be a readable, primary-table Reference.
• Table and InverseReference are not valid path terminals here.
• Statement and object-context-fact targets are root-only.
• A related system field is terminal, for example three reference segments followed by { "SystemField": 1 } for the related record’s Display Name.

The terminal field determines the available operators and value editor. Reference Eq and In operands are IDs of records in the terminal entity definition.

Read back and verify

After PUT, read the table configuration again and confirm all paths:

GET /api/workspace/admin/entity-definitions/{aidRecordDefinitionId}/ui/table-surfaces/{surfaceKey}/configuration

Then open the table as an ordinary user:

1. Apply District and Region filters and verify rows and total count.
2. Sort by Region and verify visible order and pagination.
3. Confirm restricted related fields or records do not become visible through target labels, matches, or counts.
4. Clear temporary filters and restore the intended default view.

For exact Runtime API payloads, see Entity Instance Query.