Automatic and processing search¶
With no processing options, docbank search renewal terms tries hybrid
search when a processing profile has a query embedding binding. The CLI
asks the daemon to search all live files; you do not need profile names or
version UUIDs for this path. The daemon enforces query
consent and index authority.
The CLI runs ordinary lexical search after the hybrid attempt. Its results
are shown when hybrid search falls back. Folders have no content version, so the
hybrid source scope cannot include them. After a successful hybrid search, the
CLI adds folder name matches from the lexical search instead. They are read
after query embedding, like the revalidated hybrid results. Folders count
toward --limit and replace the lowest-ranked hybrid results when the page is
full. The report is truncated when either search omitted a match.
Profiles and query bindings are tried in ascending name order until one
succeeds. A failure that could differ by binding moves on to the next pair:
missing consent, processing_failed, processing_profile_unavailable,
stale_index, or not_found from a binding whose vector index is not built.
A failure that applies to every binding stops at once. Automatic search uses
the whole live population, subject to the vector generation size limit.
When every pair fails, the command reports the first failure reason.
Some requests never try hybrid search and report no degradation:
- no profile has a query embedding binding, or processing is unavailable
- a tag, directory, MIME, or modification filter, or
--fuzzy --limitabove 100, the processing search maximum- query text longer than 8,192 Unicode characters, the processing maximum
--mode lexicalwith no processing options
Cancellation and authentication failures stop the command. Any other hybrid
failure falls back to lexical results with the daemon's stable problem code as
the reason. A failure without a problem code, such as an invalid response,
reports semantic_search_failed with the error text. Search never grants
consent itself.
Human and --json output write one degraded: REASON line to stderr, so
stdout keeps the lexical table or JSON unchanged. --agent output puts the
reason in its header instead.
--json output depends on which search produced the results. Lexical search
returns the ordinary report with hits. Successful hybrid search returns the
processing report with actual_mode, coverage, and results, plus a
folders array of ordinary folder name hits. Check for actual_mode to tell
the shapes apart, or pass --mode lexical to always get the ordinary report.
Empty lexical and automatic hybrid reports can include
hints, which other output
modes print on stderr.
After semantic retrieval, the daemon revalidates the complete report against
current live versions, including unembedded lexical matches. A match trashed or
replaced during query embedding is removed, and moved paths are refreshed. A
file-name match is removed when the file is renamed. A tag edit keeps the match.
Removed candidates make the report truncated, and surviving result ranks and coverage
reflect the final check. This applies to automatic and explicit semantic/hybrid
search, including when expansion and reranking are disabled.
Choose exact versions and a profile¶
Explicit processing search uses rendition text (text derived from a document
version) and, where configured, vectors. It searches only the source set you
name. The CLI obtains the daemon's vault UUID and sends repeated
--source-version values for you:
docbank search "renewal terms" \
--mode hybrid \
--profile <configured-profile> \
--source-version 11111111-1111-4111-8111-111111111111
Explicit processing search requires a mode, executable profile, and at least one source
version. Replace <configured-profile> with a name reported by docbank
processing profiles. A search accepts at most 4,096 unique versions and
returns at most 100 results. --binding is optional when the selected profile
has one embedding binding and required when it has several. Lexical and auto
modes reject --binding. Processing search cannot be combined with ordinary
tag, media-type, directory, or modification-time filters.
Consent before semantic or hybrid search¶
semantic and hybrid send query text to the selected embedding provider.
They require an active query_text consent grant for that profile and provider
disclosure, even when the document's vectors already exist. Missing consent
returns processing_consent_required. Expired or revoked consent returns
processing_consent_expired or processing_consent_revoked. Search does not
grant consent automatically.
Preview docbank processing plan <path-or-id> --profile <configured-profile> --json
and review its query-text disclosure. Then either:
- Run the reviewed processing build with
--plan-fingerprint <fingerprint-from-plan> --consent. This grants the profile's configured operations and runs its document processing. - Grant consent without rebuilding through
POST /api/v1/processing/consent/grants. Send the plan'sselectorand itsfingerprintasplan_fingerprint. Supplyexpires_atfor a grant that expires.
These grants cover the daemon operator's use of that profile across documents
and searches. A profile with reranking includes a query_text_and_excerpt
grant in the same approval. Review the reranking provider and its disclosure
alongside the document and query operations. CLI grants have no expiry.
Explicit processing lexical and auto use text already stored locally. They do not require
query-text consent or call an embedding provider.
Rerank search results¶
Add --rerank to send the query and candidate excerpts to the profile's
configured reranking provider:
docbank search "renewal terms" \
--mode hybrid \
--profile <configured-profile> \
--source-version 11111111-1111-4111-8111-111111111111 \
--rerank
Reranking works with every search mode and runs only when requested. It needs
the profile's active query_text_and_excerpt grant, including in lexical and
auto modes. Review and grant the plan using the consent steps above. Search
does not grant consent itself.
Human output shows the reranking outcome and candidate count. --json includes
a reranking receipt whether or not you pass --explain. In the receipt,
applied means reranking succeeded, skipped means there were no candidates,
and degraded means the search kept its original ordering after a reranking
failure. The configured degrade failure policy returns that original
ordering. fail_closed returns reranking_failed instead. See the
search response contract
for receipt fields and degradation causes.
Modes and coverage¶
lexicalsearches canonical segments from renditions.semanticsearches the selected embedding binding.hybridcombines lexical and semantic candidates.- Explicit
autouses lexical retrieval and reportslexicalas the actual mode.
HTTP and embedded callers can prefer content matches over filenames
with content_first: true or ContentFirst: true.
Each search response reports the actual mode, degradation, and the number of
complete documents in the supplied source set. The coverage API separately
reports rendition and embedding state, including complete, unavailable, stale,
ineligible, and rebuilding counts. previous_generation_serving counts rebuilding
documents whose previous complete result is still available. A rebuild alone
does not establish that a previous result exists. Missing required coverage keeps
the aggregate state partial, even while another result is rebuilding. See the
coverage contract
for the fields and snapshot boundary. A direct-file-only embedding can produce
a match without an excerpt, because Docbank kept no readable text to quote.
Source-fenced consumer contract¶
Callers may send scope: {"kind":"all_live"} with optional metadata filters
instead of a source fence; Docbank selects the current live files on the server
and applies that scope throughout retrieval and reranking.
The source fence is the vault identity and content-version set the caller supplies. Docbank enforces it before retrieval, not as a filter on results. It validates the vault identity and applies the content-version set before lexical retrieval, vector scoring, candidate expansion, and reranking. Only vectors attached to current versions of live documents inside that fence are eligible. Missing vector-row authority stops the search. A foreign vault or an empty, duplicate, malformed, or oversized fence is rejected.
Consumers store a source's identity as (vault_uid, node_id,
content_version_id). A hit's rendition attachment, rendition build, lexical
segment, embedding set, and vector space identify the evidence used for that
query. They are not a second identity for the document. Fetch readable
evidence from Docbank's authenticated rendition endpoint instead of keeping a
parallel chunk or vector corpus.
The consumer must still re-check whether each candidate is visible immediately before presentation. That final check closes the interval between retrieval and display when a source version is revoked or otherwise becomes unauthorized.
Processing search does not require a user-facing evidence sidecar. Results carry evidence references, and an authenticated rendition carries its own identity and navigation metadata. Consumers may request those when they need to explain a result.
For ordinary name and verified plain-text search, see Searching.