Skip to main content

​
Order By Properties

NameTypeDefaultDescription
columnIdstringRequiredDot-separated property path to the column to sort by. Must reference a valid property in the entity type
directionstring"asc"Sort direction: "asc" (ascending) or "desc" (descending)

​
Configuration in Sheet YAML

Sorting is configured in two places within the sheet configuration:

​
Global sortBy Section

The top-level sortBy array defines the default sort order applied when the sheet loads: 
sortBy:
  - columnId: outlineNumber
    direction: asc

​
Column-Level sort Property

Individual columns can specify their own default sort direction: 
columns:
  title:
    title: User Need
    width: 300
    sort: asc
NameTypeDefaultDescription
sortstringNoneDefault sort direction for this column. Values: "asc", "desc"
The global sortBy defines multi-column sort priority at the sheet level. The column-level sort property sets the default direction for an individual column. The global sortBy is always re-applied after user-initiated sorts to maintain hierarchy order.

​
Sort Behavior

diagram

​
Client-Side Sorting

  • Sorting is applied on the client side after data is fetched
  • Multiple column sorting is supported and follows the order specified in the sortBy array
  • If direction is not provided, the default is "asc"
  • The configured sortBy is always appended after user-initiated sorts to maintain a stable hierarchical order

​
Interactive Sorting

Users can sort interactively through:
  • Column header click — toggles sort direction on a single column
  • Ctrl+Click on column header — adds to existing sort criteria for multi-column sorting
  • Toolbar sort controls — additional sorting options from the toolbar
Column headers display visual sort direction indicators (ascending/descending icons) and numbered badges for multi-column sort priority.

​
Column Type Sort Behavior

Column TypeSort Behavior
TextAlphabetical sort
NumberNumeric sort
EnumSorts by enum value sequence, not alphabetically
ReferenceSorts by the display value of the referenced entity
Custom renderSorts by the rendered display value
Enum columns sort by the defined enum sequence, not by the string label. This ensures that priority levels like Critical > High > Medium > Low sort in the expected logical order.

​
Validation

Order-by property paths are validated against the entity type metadata at query execution time. The validation ensures:
  • Each property path references a valid property in the domain model
  • Navigation paths (dot-notation) resolve to valid property chains
  • Invalid property paths produce validation errors

​
Query-Level Order By

In the query API, order-by clauses use property path strings with an optional desc suffix: 
propertyPath          -> ascending (default)
propertyPath desc     -> descending
Multiple order-by paths create composite sorting with priority following array order.

​
Multi-Column Sort Example

sortBy:
  - columnId: outlineNumber
    direction: asc
  - columnId: priority
    direction: desc
  - columnId: title
    direction: asc
This sorts primarily by outlineNumber ascending, then by priority descending for items with the same outline number, and finally by title ascending as a tiebreaker.

​
Complete YAML Example

sortBy:
  - columnId: outlineNumber
    direction: asc

columns:
  outlineNumber:
    title: "#"
    width: 80
    sort: asc

  title:
    title: User Need
    width: 300
    hasFocus: true

  priority:
    title: Priority
    width: 100

  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 250

sources:
  - id: requirements
    model: rtm
    query:
      from: UserNeed
      where: <WHERE>
    expand:
      - name: systemRequirements
Sources: KB: sortBy Configuration Guide | Code: OrderByClause.java, sorting.spec.ts, mip_undo_redo.template.yaml, powersheet.yaml
KB ArticlesSource Code
  • OrderByClause.java
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/packages/common/types/api/document.ts
  • prod-powersheet-src/com.nextedy.powersheet.client/src/modules/QueryManager/QueryManager.tsx
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/cypress/e2e/Sheet/reference.spec.ts
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/mip_undo_redo.template.yaml