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. Full addresses entered in Search or Omnibox use the separate address resolver, not a new query qualifier. The query 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:
Only added: and date: accept comparison operators. tag:>=tax is rejected. 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. 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, Johnny.Decimal categories, tags, correspondents, document types, sensitivity values, date roles, 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 partial View scopes. 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.

​
Archive research Views

Archive research does not ask the model to invent a rich query. An earlier prototype converted question words into view_query, but RAG retrieval used prefix-OR while saved search text used implicit AND; the resulting View could differ from the cited documents. Save retrieved documents as a view creates an exact snapshot from the authorized documents shown under Evidence. A live View that should match future documents is created explicitly with this query language.
  • RAG retrieval finds evidence for one answer.
  • Rich queries define live filters.
  • Snapshot Views preserve the cited 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.