custodian records search

custodian records search finds the records in a collection whose field equals a value. A field must be declared searchable in the schema to be searched. Be signed in first.

custodian records search policies --where policy_number=PY-4471

--where field=value is the equality to match. As with --set, keep a sensitive searched value off the command line by reading it from standard input or a file: --where field=@- reads standard input, --where field=@<path> reads a file.

How a field is searched

What is sent depends on the field's sensitivity:

• A plain searchable field is compared by the server on the value it holds, so Custodian sends the value.
• A masked, tokenised or client_encrypted searchable field is matched on a blind index that Custodian computes locally — the server cannot compute it. The value itself is never sent. Computing the index needs this vault's search key, which needs an enrolled device; without one, the search is refused and nothing is printed.

For an encrypted field, a match may come back as a wider candidate set (records that share the truncated index), which Custodian narrows locally to the true matches before printing anything. When it narrows, it says so on standard error:

Narrowed 6 candidates at 16-bit index locally to 1 true match.

Printing a match is a disclosure

Printing a matched record reads it in full — a real disclosure that appears in the audit trail, one entry per field for each record printed. If you only need the identifiers, use --ids-only, which prints them and reads nothing:

custodian records search policies --where policy_number=PY-4471 --ids-only

rec_8VN2QJ4KpR

If narrowing an encrypted search would need to resolve tokens you have no read_token grant for, the search refuses and prints nothing — not even a count, since a count over a known value is itself a disclosure:

error: Cannot narrow the candidate set for "policy_number": resolving the searched tokens needs a read_token grant on that field, and the API refused. … Ask a vault operator for a read_token grant on "policy_number".

--json returns the true matches only.