Skip to main content
Suchi uses one bounded query language across ranked Search, Documents, saved Views, Calendar scopes, and the search_documents MCP tool. The parser produces a typed query plan; user text is never interpolated into SQL or passed through as raw FTS5 syntax. For indexing, BM25, recency, autocomplete, similar-document search, and Archive research retrieval, see Search architecture. All clauses, symbolic names, ambiguity suggestions and saved/snapshot View scopes resolve inside the selected or token-bound filing system. jd:13 is a local category filter, not a cross-system lookup. Two-component SYS.AC category addresses entered in Search or Omnibox use the separate address resolver, not a new query qualifier. This interception does not change Documents q, saved Views, Calendar/Ask scopes, autocomplete, MCP search, or persisted jd_category_id; noncanonical three-component text remains an ordinary query. Queries can narrow visible documents, never grant system entry or document ACLs.

​
Quick examples

Search and Documents compile the same query into the same matching document set. Ranked Search adds ranking; Documents applies its selected list ordering.

​
Terms, prefixes, and phrases

A bare word is a Unicode-aware prefix term:
This matches terms beginning with both annu and rep, such as “annual report”. Do not type *; raw FTS wildcard syntax is rejected. Double quotes create an exact phrase rather than a prefix:
Quoted filter values preserve spaces:
Use title: or content: to constrain a text term or phrase to one indexed column:
Bare title: and content: values are prefixes. Quoted values are phrases.

​
Implicit AND

Whitespace between positive clauses means AND:
This means “contains an invoice… term and a renewal… term.” Filters compose the same way:
All three constraints must hold. Do not write AND; explicit Boolean operators are unsupported.

​
Negation

Prefix a term, phrase, or filter with - to exclude it:
Negation applies only to the following clause. There is no grouped negation.

​
Filters

See Document dates for extraction, confidence, review, and Calendar behavior. Examples:
Comparisons are accepted only by date filters, numeric/date custom fields, and asn:. tag:>=tax, has-field:>Receipt, and field:Status>Open are rejected. version: cannot be negated or repeated. All positive date: comparisons and date-role: clauses must match the same Calendar date. Negated date clauses remain independent NOT EXISTS conditions. Dates available to Calendar are readable document metadata, so these predicates require documents:read, not archive_intelligence. An ordinary has-field: clause means that the document has a stored value row. For a documentlink, the exact linked target must also be live and visible to the caller. A hidden, trashed, missing, or permanently deleted target therefore behaves as absent, including for -has-field:. Target visibility is evaluated inside the presence predicate before counts and pagination. Field names resolve in the selected filing system before execution; renaming or deleting a field makes a saved query using the old name fail normally rather than broadening it. field: resolves the exact field name before applying its declared type. Equality on a multi-choice field means membership in the stored list. Document links are intentionally excluded: use Linked documents to follow exact relationships and has-field: to test whether a visible live target exists. Field-value predicates retain the same source-document ACL and caller-relative version rules as every other discovery filter. archive_serial_number is system-scoped physical-filing metadata. The API and web app expose it as ASN n and allow authorized edits; asn:none tests for a null value. Source saved views with exact, missing, greater-than, or less-than archive-number rules import into these selectors. Query matching still applies ordinary system, ACL, Trash, and version-currentness rules. Version currentness is caller-relative. Discovery surfaces use the greatest live document ID the caller can see in each version family; a hidden or trashed newer revision does not suppress an older visible one. Direct detail URLs, exact document snapshots, and Trash are exact-row operations and do not apply this default. Metadata names are resolved before execution. Unknown values return errors; ambiguous values return suggestions.

​
Escaping

Backslash escapes the next character in bare or quoted text. Use it when a literal colon would otherwise start a filter:
Quote values containing whitespace:
Inside quotes, escape a quote or backslash:
A leading - means negation. Escape it when it is literal text:
Whitespace, :, comparisons, quotes, parentheses, *, ^, {, and } must be quoted or escaped when intended as literal text. Non-whitespace control characters are always rejected.

​
Unsupported syntax

Suchi does not implement a general Boolean or raw FTS language:
Explicit OR, AND, NOT, and NEAR; grouping and precedence; proximity; raw FTS5 wildcards, boosts, and columns; and SQL-like expressions are rejected. One query remains an AND-composed set of independently negatable clauses.

​
Suggestions and completion

The Search and Documents query fields recognize an incomplete final qualifier. Suggestions cover filter names, filing categories, tags, correspondents, custom fields, sensitivity values, date roles, version modes, and is: states. Selecting one replaces the active token but does not run the search.

​
Limits

These are API contracts, not only browser limits.

​
Errors

Invalid queries return HTTP 400 with code: "bad_query":
position is a zero-based byte offset in the submitted query. filter names the failing qualifier. suggestions contains closed-vocabulary or ambiguity help when available. The web app keeps the active form visible rather than turning a failed query into an empty result.

​
URLs and MCP

Send the complete query in one URL-encoded q parameter:
MCP accepts the same unencoded string:
Clients should not split or reinterpret clauses themselves.

​
Saved Views

New Views store one normalized query in filter_json.q. Visual category, tag, correspondent, type, sensitivity, and document-date controls are converted into the same language before persistence. Normalization quotes or escapes values and is stable across parse/serialize round trips. Older or imported Views may retain flat filter keys. Consumers such as Calendar send view_id; the server loads an owned or shared View, applies its complete filter, and reapplies document ACLs. Clients must not reconstruct only part of the View’s filters. Snapshot Views instead store document_ids as an array of 1–100 positive, deduplicated IDs. They preserve an exact document list while still reapplying ACLs whenever opened or shared.

​
Views saved from Ask your documents

Ask your documents does not ask the model to invent a rich query. An earlier prototype converted question words into view_query, but broad question matching and saved search text used different rules; the resulting View could contain different documents from the answer. Save these documents as a view creates an exact snapshot from the authorized documents listed under From your documents. Create a live View explicitly with this query language when it should match future documents.
  • Document matching finds text for one answer.
  • Rich queries define live filters.
  • Snapshot Views preserve the exact document list.

​
Security

The compiler emits fixed SQL fragments with bound values. Metadata names become internal IDs before execution. Search, Documents, saved View scopes, Calendar, and MCP append the caller’s visibility predicate inside the database query. A query can narrow access; it cannot expand permissions or reveal a private View.