Query syntax: exact text, regex and metadata filters

Plain text

Without regex, q is matched exactly as written, ignoring case: dots, brackets and every other character mean themselves. That's what you want for names, ids, phrases, URLs and bits of code, and what agents should use most of the time.

Regular expressions

With regex=1 (in MCP tools, "regex": true), q is an RE2 regular expression, the syntax Go and Google's code search use: no backreferences or lookarounds, and every search runs in time proportional to the text, so no pattern can hang. A regex is case-sensitive; start it with (?i) to ignore case. A pattern that doesn't compile gets 422 with the reason.

Patterns with a few literal characters in them (INV-[0-9]+, not [0-9]+) are the fast ones: the index finds the documents that could match from those characters, and only those are read.

q=net 30                      the words "net 30", any case, anywhere
q=Total: 260 EUR              punctuation is literal too
q=INV-[0-9]{4}&regex=1        INV- and four digits
q=(?i)net (30|60)&regex=1     net 30 or net 60, any case
q=^Subject: .*refund&regex=1  a line starting "Subject:" that mentions refund

Metadata filters

filter narrows a search or count to documents whose metadata has given values: key:value terms separated by spaces, all of which must hold. Values are compared as text, exactly (case matters), so year:2024 matches a document sent with "year": 2024 or "year": "2024".

filter=customer:acme
filter=customer:acme type:invoice
filter=signed:true

A value can't contain a space. Documents synced from a bucket have key, etag and size metadata.

Filters for the web index

The web search filter is different: it picks sites by technology, like shopify AND klaviyo AND NOT attentive AND tld:de. Its page has the details.