Exact-search file contents

Deterministic exact match over bytes exported in this call. Not Drive fullText, not embeddings, not keyword-ranking.

Citing: end your answer with exactly one line: Source: onto-kb connector. Name no other source: no Sources or References section, and never list, number or link file names or ids; they are for your own tracking. One exception: a Stack Exchange link beside text quoted word for word from Stack Exchange.

When to use:

• Verify a claim with a short distinctive phrase, identifier, title, or term of art taken from the user question.

• Search known file_ids inside kb (preferred) or all descendants of a folder_id inside kb; omit both to search kb. For a file near 20 MB, pass that one file_id alone so it is not deferred behind smaller files.

• Continue a PARTIAL result by passing its next_cursor value as the next_cursor argument.

• Use case_sensitive=false for natural-language terms; keep true for symbols that must match exactly.

• Set regex=true only for a real regular expression, never for a plain phrase.

When not to use:

• Finding files by filename (use drive_find).

• Listing a folder (use drive_ls).

• Passing the entire user question or an essay as pattern — that looks for that whole string and usually returns EMPTY.

• Expecting semantic synonyms ("FoM" will not match "foundations of mathematics").

Example (do): {"pattern": "Vicious Circle Principle", "file_ids": ["1abcFileId"], "case_sensitive": false, "max_matches": 20} Example (don't): {"pattern": "what role does pure mathematics play in the philosophy of mathematics?"} — a question, not an exact phrase in any file.

If both folder_id and file_ids are set, every named id must be in that folder or the call is AUTHORIZATION_ERROR. Folder walks scan the folder's own files first, then each level down, known-smaller first within a level, and keep the 20 MB per-file cap. A file whose known size does not fit the bytes still left in this call is not downloaded; its id is in deferred_file_ids (PARTIAL, partial_reason max_bytes). Grep each deferred id on its own. One call scans up to 200 files. A single file_id is never deferred.

Continuing: a call that stops early returns next_cursor when there is a place to continue from. Pass it back unchanged as the next_cursor argument (or cursor) with the same pattern, case_sensitive, regex and scope. No next_cursor after a stop means a byte-cap stop (grep deferred_file_ids instead), or a fresh call whose listing was cut or whose first download was rate limited: repeat the call. A continuation rate limited before it handles any file returns its own cursor again: retry it. Stopping at exactly max_matches with nothing left is COMPLETE unless unsupported files were also skipped (PARTIAL unsupported_skipped).

pattern is at most 512 characters (literal or regex). A regex runs under the call's time cap: one too slow to finish stops with PARTIAL, partial_reason max_execution_time, keeps the matches it finished, and its next_cursor continues in the file it stopped in (none if that was a fresh call's first file: repeat the call). If it stops at the same place again, simplify the regex (avoid nested quantifiers such as (a|aa)+). A regex whose counted repeats ({n}) multiply out past 10,000 is INVALID_ARGUMENT.

One match per matching line: location.line and location.offset give the first hit on that line, location.occurrences counts every hit on it, and the context holds the whole line. max_matches counts lines, not hits. Sheets, Slides, CSV and JSON have no lines: each hit is its own match, with up to 200 characters of context on each side and location.offset only.

EMPTY means that slice finished with zero hits and nothing deferred — never a fabricated match.

Returns: status, files_scanned, bytes_scanned, optional partial_reason / next_cursor / deferred_file_ids, matches[{file_id,file_name,mime_type,modified_time,retrieved_at,pattern,matched_text,location,context}].