Skip to content

Sort results by a property value

PortalCLIAPIIntermediate~10 min

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.

Not on MCP

sortProperty is exposed on GraphQL findNodes, the hadron CLI (--sort-property, added in hadron-cli#265), and the portal's node browser (below) — but not on the MCP hadron_find_nodes tool, which exposes neither sort nor sortProperty. To order MCP results by a property, sort client-side.

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.

From the CLI

The CLI takes the same object as a JSON string on --sort-property, on both hadron search (ranked) and hadron node ls (the deterministic, no-query browse — the better fit for a true ORDER BY over a collection):

# Browse a collection ordered by a numeric property, highest first
hadron node ls -m acme.com:research \
  --object-type competitor \
  --sort-property '{"path":["fundingUsd"],"as":"number","direction":"desc"}'

# Combine with --where to filter, then order (the CLI companion to the
# GraphQL example above)
hadron node ls -m acme.com:research \
  --where '{"path":["stage"],"eq":"series-a"}' \
  --sort-property '{"path":["fundingUsd"],"as":"number","direction":"desc"}'

# On a ranked search, sortProperty re-orders the retrieved window (see the
# vector / hybrid caveat below)
hadron search "series a competitors" -m acme.com:research \
  --sort-property '{"path":["fundingUsd"],"as":"number","direction":"desc"}'

--where and --object-type are the CLI surface of the where predicate; --sort-property is sortProperty. Same grammar, same defaults as the table above.

In the portal

The node browser has the same control, without hand-writing JSON. Open a memory, expand the structured-query panel, and use Sort by property:

  1. Enter the property path — the field name, e.g. fundingUsd. If the memory has a schema and you've picked an Object type, the input suggests that collection's declared field names.
  2. Pick the column (properties or data) and the cast. The cast is filled in for you from the schema when the field is declared — so a number field arrives pre-set to number and you don't repeat the cast mistake below.
  3. Pick the direction.

The label reads "Sort by property (overrides the Sort dropdown)" — a reminder of the same override rule that applies on every surface. Clear all resets the panel.

Encrypted memories

On an encrypted memory the data column is offered but disabled and marked (encrypted), with a note that filters and sorts over data can't match. That's not a UI limitation — data is ciphertext at rest, so there's nothing for the server to compare. Sort over properties instead.

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