Skip to content

Sort results by a property value

PortalMCPCLIAPIIntermediate~10 min

Put records in the order you need: the competitors that raised the most first, or the worklog entries oldest first. The order comes from one of the records' own fields, not from how well they match a search. Ask your agent, or use the sort control in the portal. Neither needs a terminal.

This is the companion to filtering by a field: narrow to the records you want, then order them.

Ask your agent

What you need: an agent connected to Hadron, and read access to the memory. Name the field and the direction, in plain words:

In acme.com:market, list the competitors at series A, the ones that raised
the most first. Its schema is shown when you list my memories.

What you get back: the records, ordered by that field.

What to check:

  • Numbers sorted as numbers. Scan the top few. If 9000000 comes before 12000000 in a largest-first list, the field was compared as text; see below. A field the schema declares as a number or datetime is sorted by its type automatically.
  • One field at a time. Your agent can sort a collection by one field per request. To break ties by a second field, ask it to re-order the results itself.
  • Records without the field come last, in either direction; see below.

Sorting through an agent works on the records in a collection. An agent searching ordinary notes by meaning can't have Hadron sort them by a field. It has to re-order what it got back itself, and that covers only the results it fetched.

In the portal

The node browser has the same control, without hand-writing JSON. Open the memory's Nodes tab, open the Properties filter, 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.

With the API: sortProperty

sortProperty orders findNodes results by the value at a properties or data JSON path. It is an ORDER BY over the graph, available on GraphQL findNodes, on the hadron CLI (--sort-property, added in hadron-cli#265), and in the portal control above.

On MCP, sort a collection with hadron_find_objects

The MCP hadron_find_nodes tool takes neither sort nor sortProperty. The object-store tool hadron_find_objects takes a single-field sort shorthand, { "fundingUsd": "desc" }, and casts the field by its declared type. That is how an agent sorts a collection. See Store and query records.

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.

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