Skip to content

Sort results by a property value

sortProperty orders findNodes results by the value at a properties or data JSON path — an ORDER BY over the graph. It's the companion to the where predicate: filter to the rows you want, then order them by a field.

GraphQL-only

sortProperty (and the sort enum) are exposed on GraphQL findNodes only. The MCP hadron_find_nodes tool exposes neither — to order MCP results by a property, sort client-side. The CLI has no structured query surface yet (hadron-cli#265).

The shape

sortProperty reuses the where leaf addressing:

query TopFunded {
  findNodes(
    filter: {
      objectType: "competitor"
      where: { path: ["stage"], eq: "series-a" }
    }
    sortProperty: {
      path: ["fundingUsd"]     # required — object-key path into the column
      field: properties        # optional, default properties
      as: number               # optional, default text
      direction: desc          # optional, default asc
    }
  ) {
    hits { node { loc name properties } }
    total
  }
}
Field Default Meaning
path — (required) Object-key path into the column, e.g. ["fundingUsd"].
field properties Which JSONB column — properties or data.
as text Value typing — text, number, datetime, boolean.
direction asc asc or desc.

Cast, or you sort strings

Like where, the default cast is text, which orders lexically. To sort numbers as numbers or dates chronologically, set as. Without as: number, fundingUsd values sort as strings — "9000000" after "12000000", which is almost never what you want.

Missing and unparseable values sort last

number and datetime casts route through the same DB guards as where. A node whose sort path is missing, null, or unparseable sorts last — regardless of direction. So direction: desc puts the highest values first and the missing ones at the very bottom, not the top. Ties are broken by loc ascending, giving stable pagination.

It overrides the sort enum

When sortProperty is present it overrides the sort enum (relevance, loc, seq, updatedAt). Pass one or the other, not both — sortProperty wins if you pass both.

The vector / hybrid caveat

On vector and hybrid modes, sortProperty re-orders the retrieved candidate window, not the whole collection — the ranking runs against the vector index, and sortProperty reorders whatever came back. This is the same caveat as the sort enum: you're sorting the semantically-retrieved page, not running a global ORDER BY over every node. For a true global ordering, use a lexical mode or the no-query browse (where the predicate and sort apply in-query).

Next steps