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.

--where names a field within the collection you search, so the same field name in another collection is a distinct field. Naming a field the applied schema does not hold in that collection stops before the search request, without sending your searched value. The search error names the field and lists the collection's searchable fields, so you can see what you can narrow by:

The applied schema declares no field "holder_tax_id". The searchable fields are: policy_number. Apply the schema with `custodian schema apply` or correct the field name.

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.