YakFind query language ======================== YakFind finds words by how close they are to each other, not only by whether they appear. Everything runs on your own computer. If a query cannot be understood it is searched for exactly as typed, and the panel says why. The line under the query box always shows in plain English what will be searched. Words and phrases ----------------- contract The whole word, any capitalisation. It does not match inside "contractor". breach of contract Words typed together are a phrase. Quotes are optional. "loss or damage" Use quotes when the phrase contains an operator word (OR, AND, NOT, S, P ...). terminat* Any ending: terminate, termination, terminating. * also works inside a word. terminat! The same thing, written the way some legal databases write it. wom?n Exactly one unknown letter: woman, women. STEM[pay] All grammatical forms: pay, pays, paying. FUZZY[recieve] Tolerates typing and scanning errors. The tolerance grows with the word's length; FUZZY[word,2] sets it (0 to 4). SYN[damage] The word or any of its synonyms. /\d{4}-\d{2}/ A regular expression between slashes. REGEX(...) is the same. Phrases ignore punctuation ("interest is" matches "interest! Is") but never run across a paragraph, heading or table cell. Punctuation and symbols are not part of words: C++ is searched as C, $500 as 500. Close together -------------- a NEAR 5 b Within 5 words of each other, either order. 1 means next to each other. NEAR alone means NEAR 3. Also written: a /5 b a W/5 b a WITHIN 5 WORDS b a ADJ b b directly after a. ADJ 3 allows b up to 3 words after a. Also written: a +3 b a PRE/3 b a S b In the same sentence. S 2 means within 2 sentences. Also written: a /s b a W/S b a WITHIN 2 SENTENCES b a P b In the same paragraph. P 1 includes the paragraph before and after. Also written: a /p b a PARA b a WITHIN 1 PARAGRAPHS b a NOT 3 b a, except where b is within 3 words of it on either side. Abbreviations (Mr., Ltd., e.g., No. 5), initials and decimal numbers do not end a sentence. In a web page each block (paragraph, heading, list item, table cell) is a paragraph. Combining --------- a OR b Either one. Also: a || b a AND b Both, anywhere in the document. Also: a & b a NOT b a, but only if b is nowhere in the document. Also: a BUT NOT b a % b a XOR b One of them, but not both. Also: a ^ b ( ) Group parts of a query. Order of operations ------------------- Operators are applied in this order, first to last. This is the convention used by legal research databases, and it differs from programming languages: OR comes first. 1. OR 2. NEAR, /n 3. ADJ, +n 4. NOT n 5. S, /s 6. P, /p 7. AND 8. XOR 9. NOT, BUT NOT, % So indemnify NEAR 5 loss OR damage means indemnify NEAR 5 (loss OR damage). Use parentheses whenever you want something else; the plain-English line shows how it was read. Rules ----- - Operators are written in capitals and stand alone between two terms. "and" in lower case is an ordinary word, and the panel points this out. - A number after an operator is a distance only when another term follows it: in page NEAR 5 total the 5 is a distance; in page NEAR 5 it is the thing searched for. - S and P in capitals are operators. To search for the letter itself, put it in quotes: "P". Options ------- Aa Match capitalisation exactly. ab Whole words only (on by default). Turn it off to also match inside longer words. Changes from the 2021 version ----------------------------- - Plain words now match whole words. They used to match anywhere, even inside other words, and were treated as regular expressions. Regular expressions now need /slashes/. - AND, wildcards, SYN and the /n /s /p forms are new. - NOT without a number and XOR now look at the whole document. NOT with a number still means "not nearby", and now checks both sides. - ADJ no longer needs a number. - STEM and FUZZY are written with square brackets, as before; round brackets also work. - The lower-case one-letter aliases (n for NEAR, a for ADJ) are gone; they collided with real words. Ask in plain words (browser, Word and Excel) ============================================ Next to "Exact query" the panel has "Ask in plain words". Type a question or a description and press Enter. The page or document is cut into passages of about a paragraph, and the passages that best match are listed: by shared words, by rare words (reference numbers, names) and by meaning ("how should someone be told the contract is ending" finds "written notice of termination"). Each passage says what found it. Click one to go to it: the browser marks the passage on the page, Word selects the paragraph it starts in. In Excel each row of a sheet is a passage and choosing one selects the used part of that row (see Excel below). Outlook has exact queries only. The meaning model is the same one the desktop app uses (all-MiniLM-L6-v2, about 23 MB). It is shipped inside the extension and the add-in and runs in the panel itself; nothing is downloaded when you search and no text leaves the browser or Word. The first question on a long page takes a few seconds while passages are read; up to 600 passages are compared by meaning and the rest by words only. This ranks passages; it does not promise to list every relevant one, so use an exact query when completeness matters. License (browser, Word, Excel and Outlook) ========================================== Searching, asking and stepping through results are free. Saving searches, and searching more than one place at once ("All tabs" in the browser, "All sheets" in Excel), need a license: open Help in the panel, paste the license text you received and choose "Check license". It is checked in the panel on this device; nothing is sent anywhere. The same license file works in the desktop app if it names that product (or "suite"). The panel in the browser ======================== Chrome and Edge show the panel as a side panel, Firefox (146 or newer) as a sidebar. Click the YakFind toolbar button on the page you want to search, or press Ctrl+Shift+Y (Alt+Shift+Y in Firefox). The click is what lets YakFind read that one tab; "All tabs" asks once for every site. In Firefox the sidebar can also be opened from Firefox's own sidebar menu, but it can only read a page after the toolbar button has been pressed on it. Keys in the panel Enter next result (Ctrl+Enter: previous). In "Ask in plain words": ask. Esc clear the query Arrow Down from the end of the query into the result list Tab moves between the query, the buttons, the term chips, the tabs and the result list. The result list and the row of tabs are one stop each. In the result list Arrow Up/Down, Home and End move and show the result in the document On the tabs Arrow Left/Right, Home and End Space or Enter on a term chip hides or shows that term's highlights n / p / Esc on the page itself while a search is showing: next, previous, clear The panel follows the system's light or dark setting and text size, and can be used at 400% zoom. Screen readers are told how many results a search found. Excel ===== YakFind for Excel is a task pane opened from the Home tab. It searches the cells of the open workbook inside the task pane. The workbook is never changed and nothing is sent anywhere. What is searched The text of every cell that has any, as Excel displays it: a date as "1 Mar 2024" (or however the cell is formatted), an amount as "4,250.75", a formula by the result it shows and not by the formula itself. In a merged area the text belongs to the top-left cell. Cells in hidden rows and columns are searched like any others. "This sheet" (the default) searches the sheet that is showing; "All sheets" searches every sheet, hidden ones included. Searching a sheet is free; "All sheets" and saved searches need a license, entered under Help in the panel and checked on this computer. Not searched: comments and notes, text boxes, shapes, charts, headers and footers, sheet names, and the names of defined ranges. What a hit is Each cell is a paragraph of its own, and cells follow each other row by row, left to right. A phrase never runs from one cell into the next; NEAR and ADJ count words across neighbouring cells, so birch NEAR 6 overdue finds a customer and a status in the same row. A result is listed as sheet!cell (Invoices!B7), at the cell holding its first matched word, with the neighbouring cells as context. Choosing it shows that sheet and selects the cell. In "All sheets" results are grouped by sheet and every sheet is searched on its own: AND, NOT and XOR look at one sheet at a time, and a distance never reaches from one sheet into another. A hit on a hidden sheet is listed with "(hidden sheet)" after its address; Excel cannot show it until the sheet is unhidden, so choosing it does nothing. Ask in plain words Each row is one passage (its cells side by side). Choosing a passage selects the used part of the row (Invoices!A3:F3). Column headings are not added to the rows, so a question works best when it uses or means words that are in the row itself. When the workbook changes Every search reads the cells again. In Excel 2019, 2021 and Microsoft 365 the list also updates by itself when a cell is edited or recalculated, a sheet is added or deleted, or (in "This sheet") another sheet is shown. Excel 2016 does not report changes to add-ins: there the list is brought up to date when you click back into the task pane or search again. Limits - A large sheet is read 20,000 cells at a time; a sheet of 24,000 cells takes a few requests. If Excel on the web refuses a block as too large (cells holding very long text), the sheet is read again in smaller blocks. - While you are typing in a cell Excel does not answer add-ins; the panel says so. Press Enter in the cell and search again. - A result that spans several cells is listed once, at its first cell. Outlook -------- YakFind for Outlook is a task pane opened from a message you are reading. It searches that one message inside the task pane. Nothing is written to the message or the mailbox, and no request is made to the mail server or anywhere else. What is searched The subject, the sender, the To and Cc recipients (name and address), the names of the attachments (pictures placed in the body included) and the body as text. For a formatted (HTML) message Outlook supplies the text a reader sees: link addresses, styles and other markup are not searched, the visible words of a link are. Not searched: what is inside attachments, Bcc and other headers, the date. What a hit is The subject, each person and each attachment name is a paragraph of its own and is labelled (Subject, From, To, Cc, Attachment). In the body, where there are blank lines they separate the paragraphs and a single line break counts as a wrapped line, so a phrase is found across the wrap. A body with no blank line at all is taken one line per paragraph. Results are listed with their context. Outlook gives add-ins no way to select or scroll to text in the message, so choosing a result only marks it in the list; the line at the bottom of the panel says so. When another message is selected Pin the task pane to keep it open while moving between messages; the search is then repeated on each message you select. Outlook versions without pinning close the task pane with the message: open YakFind again from the next one. Limits - One message at a time. There is no folder or mailbox search: Outlook only offers that to add-ins through requests to the mail server, and this add-in makes none. To search mail in bulk, use the desktop app on a .pst or .ost archive. - Exact queries only; there is no "Ask in plain words". - Searching is free; saved searches need a license, entered under Help in the panel and checked on this computer. - Messages being written are not searched. - Outlook does not open add-ins on some messages (for example rights-protected ones). The desktop app =============== The desktop app searches folders of documents on this computer. Add a folder and it reads every PDF, Word (.docx, .doc back to Word 6/95), rich text (.rtf), Excel (.xlsx, .xls back to Excel 5/95), PowerPoint (.pptx, .ppsx, .ppt, .pps), e-mail (.eml, .msg), Outlook archive (.pst, .ost), web page and text file in it, and keeps an index in its own data folder. Nothing is sent anywhere and the documents are never changed. Folders are watched: new, changed and deleted files are picked up a few seconds after they settle. "Check for changed files" does the same on demand and re-reads only what is new or different. Scanned pages and pictures PDF pages that are a picture with no text layer are read by text recognition (Tesseract) and marked "Page n (scanned)", and .png .jpg .tif .bmp files are read too. The copy of Tesseract shipped inside the installer is used when there is one; otherwise one installed on this computer (tesseract on the PATH, or -Dyaksearch.tesseract=/path/to/tesseract). The bottom left of the window says whether scanned pages are being read. Without Tesseract these pages are skipped. Above a document with scanned pages the app says which pages were recognised and how sure the recognition was, for example "Text recognition read pages 2-4, 9, 91% sure". When a page came out below 70% it is named ("page 5 was hard to read (55%), check it against the original"): words on such a page may be wrong, so a search can miss them. FUZZY[word] helps. OCR continues through the final page. The sidebar lists partially indexed PDFs and identifies pages that need OCR or yielded no OCR text. E-mail and Outlook archives A message's attachments are read with it when they are a kind of file listed above, and appear under the message as "Attachment: name" followed by their text; a forwarded message attached to a message is read too. Pictures attached to mail are listed by name but not read (they are mostly logos). An attachment that cannot be read is listed as "Attachment: name (not read: reason)", so a search for the file name still finds the message. In a .pst or .ost archive every message is a document of its own: it has its own entry in the results (subject, then the archive and the folder it is in), its own date for the Changed filter and for "newest first", and its own tags, note and reviewed mark. Attachments stay with their message. The document count at the top left therefore counts messages, not archives. Archives up to 20 GB are read. When an archive changes it is read again as a whole. Files that could not be read Listed at the bottom left with the reason (password-protected, damaged, too large). They are not retried until the file changes. Exact query The query language above, with the same meaning as in the browser and Word. Results are grouped by document, with the page, sheet or slide of each hit; sort by best first, most hits, name or newest. A coloured strip beside the open document shows where its hits are; click it to jump. Ask in plain words Type a question or a description. The passages that best match are listed, found by shared words, by rare words such as reference numbers, by the same words in the same order (a line copied from a document brings that place back first, marked "same wording") and, when the model is installed, by meaning ("cancel the deal" finds "terminate this Agreement"). This ranks passages; it does not guarantee every relevant one is listed, so use an exact query when completeness matters. Passages are about 120 to 220 words and each begins 40 words inside the one before, so a sentence that falls where one passage ends is still whole in the next. In e-mail, lines that appear in many messages (disclaimers, signatures, mailing-list footers) are left out when passages are ranked and when near-copies are found, so a message is matched on what it says rather than on its footer. Exact queries still find those lines. Filters (left side) File type, Changed (last 30 days / last year), Tagged, and Mentions (a reference number, amount, defined term, case or e-mail address found in several files). Filters apply to exact queries, to questions and to "passages like this". Saved searches "Save this search" keeps the query or question under a name; click the name to run it again. Tags and notes "Tag or note" on the open document. Tags and notes are kept in the app's data folder (not in the document), can be filtered on, and are included in reports. "Tag all..." above the results puts one tag on every document listed (or takes it off them all), so a search can be turned into a named batch in one step. Working through a list "Mark reviewed" above the open document records that it has been dealt with; "Reviewed, next" (Ctrl+Enter) marks it and opens the next one in the list that is not yet reviewed. Reviewed documents show a tick in the results, the line above the results counts them ("12 of 87 reviewed"), and "Hide reviewed" on the left leaves them out of every search until switched off. Reviewed is kept like a tag: it survives re-indexing and appears in reports. "Copy all..." copies every document listed into a folder you choose, with an index.csv naming each one's tags, note and original place. Files are copied unchanged; a message from a mail archive is written as a text file. Nothing in the folder is overwritten: a name already there gets a number. Keys F3 / Shift+F3 next / previous hit in the open document Ctrl+L to the query box Ctrl+Enter mark the open document reviewed and open the next Tab, Enter/Space reach and work every other control (Cmd in place of Ctrl on a Mac) License Searching, reading, tagging and reviewing work without a license. Saving reports, "Copy all...", saved searches and serving the Word panel need one. A license is a small text file: "Enter license..." at the bottom left (or: YakFind license /path/to/file) checks it on this computer and keeps a copy in the app's data folder. Nothing is sent anywhere and there is no activation or account. A license does not expire: it covers every version released up to its "updates-until" date, for ever. Use the file exactly as it was sent; a changed file is refused. Reports XLSX, PDF or CSV next to the result count. One row per hit: query, file, location, matched text, context, tags, note, path. The XLSX also has a summary sheet. Related (in the document viewer) Key sentences the sentences most representative of the document Cross-references "Section 4.2", "clause 9.1(b)", "Schedule 1", "Exhibit B": click to go to the clause it names; references to something the document does not contain are listed as not found Versions and near-copies other files sharing much of the wording, with the share; "Compare" shows the two side by side with changed words marked Names, or is named by files whose name this document mentions, and files mentioning it Mentions the same references files citing the same reference numbers, amounts, defined terms, cases or e-mail addresses Similar passages elsewhere passages in other files with a similar meaning "Find passages like this" (above the document) lists passages elsewhere that mean much the same as the paragraph being read. Serve the Word panel Bottom left. Serves the Word add-in's panel at https://localhost:3000 on this computer only, so Word can use YakFind without any outside host. Needs the local certificate made once by "npx office-addin-dev-certs install"; the app says so if it is missing or has expired. Limits: files over 200 MB are skipped (mail archives: 20 GB). Meaning-based search covers the first 4,000 prose passages of a file (of each message, in a mail archive); the rest of a very long file is found by words. Desktop term-list reports ------------------------- Choose Term-list report in the search pane and paste one exact query per line. Save the results to a new CSV file. Each row gives the query, index revision, matching document count, hit count, and any query error. Blank lines are skipped. The report searches the full local index with whole-word, case-insensitive matching. The command-line equivalent is YakFind term-report queries.txt new-report.csv. Desktop metadata search ----------------------- Put metadata restrictions before the text query. For example: from:alice to:bob sent:2023-03-01..2023-03-31 "notice period" The text fields are from, to, cc, subject, author, and filename. Values match case-insensitive substrings. Quote values containing spaces. The date fields are sent, received, and modified. Dates are inclusive UTC calendar days. All leading restrictions must match. Omit the text query to list matching documents without counting text hits. Missing metadata does not match a field restriction. Refresh an older library to extract its metadata. OpenDocument text, spreadsheets, and presentations (.odt, .ods, .odp) are read from their stored paragraphs and headings. Enable Indexed words in Desktop to see spellings beginning with the last word you typed. Each count is the number of indexed documents containing that spelling. Select a suggestion to use it in the query. For a possible typo, choose Include spelling variants. Select a query word, review each indexed spelling and its document count, then apply the spellings you want to include. YakFind keeps your original word in the query. Words up to three letters stay exact. Four to seven letters allow one edit and longer words allow two. An adjacent letter swap counts as one edit. A similar word can have a different meaning, so review the choices before applying them. Desktop records completed exact and batch queries in search-audit.csv alongside the local index. Export search history in the sidebar saves a CSV copy with the time, revision, scope, settings, document and hit counts, errors, truncation status, search language and library coverage. Older audit rows leave the newly recorded fields blank. In exact results, Timeline orders documents by sent date, received date, or file modification time and labels the date source. Exact copies groups byte-identical EML and MSG files, including copies held in ZIP, 7z and RAR archives, and matching reconstructed MBOX messages. For PST and OST, it compares message IDs, recipients, headers, bodies and attached file contents. Messages with missing IDs, embedded messages, unreadable attachment data or more than 64 MiB of attachments stay separate. Email threads joins visible messages with explicit reply references. When several parent records reuse a message ID and their contents differ, the reply stays separate. Expand a group to review each source separately. Review screening and redaction ------------------------------ Open Personal data on a document to inspect candidate Social Security numbers, payment cards, labelled bank accounts and birth dates. Choose a finding to read its source. Privilege screening in the sidebar accepts one name or domain per line and applies the Possible privilege tag. Clearing the rules clears the screening tag. Other review tags are independent. For an indexed PDF, choose Redact PDF, drag boxes on the preview and inspect each marked page. Export marked PDF writes a new image-only PDF at 150 dpi. The original file remains available at its existing path. MBOX mailboxes are indexed message by message. Appending new messages keeps existing message paths stable. The individual message limit is 30 MiB. ZIP members are indexed individually with their archive path and folder. Unsupported members appear in the unreadable list. Member extraction is limited to 30 MiB per item and 1 GiB total per archive. On a ZIP update, YakFind hashes the member bytes and reuses completed extraction results for identical members. If the archive cannot be opened, coverage records the failed refresh and the last readable index stays available. In an exact result list, Compare clauses displays matching numbered sections side by side. Unnumbered text before the first section uses paragraph bounds. In Investigator, choose Production from an exact result list, enter a Bates prefix and starting number, and choose the destination folder. Each batch has a fresh subdirectory. The manifest records the source representation, SHA-256 hashes, first and last Bates numbers and individual failures. Original PDFs use rendered pages. Other readable files use their extracted text for the PDF. Firm Suite shared indexes ------------------------- On the publisher, choose Collections → Publish shared index, or run YakFind publish-share , after refreshing the library. Each publication verifies the Lucene files before switching the CURRENT pointer. The shared filesystem must support atomic rename. Reviewers choose Collections → Open shared index, or run YakFind open-share , to open that generation read-only. Restart the viewer to pick up a newer generation. Tags, notes, settings and search history are stored under each user's local application data. The index contains the extracted text of the published library; give the shared folder only to reviewers authorized to read the whole collection. Additional importers and languages ---------------------------------- OneNote section files (.one) use the embedded Apache Tika reader. WordPerfect (.wpd), Pages, Numbers and Keynote files use the locally installed LibreOffice import filters. Set -Dyakfind.soffice to the executable if it is outside PATH. 7z and RAR members use a locally installed 7-Zip with the relevant decoder. Set -Dyakfind.7zip to the executable if necessary. Encrypted or unreadable members carry a diagnostic. Archive member export currently yields extracted text. Keep the container as the original evidence. Choose English, Spanish, French or German under Search language. In Desktop the choice applies to STEM queries and abbreviation handling in sentence queries, including term-list reports. English remains the initial setting. Microsoft 365 reviewer collections ---------------------------------- On a desktop configured for YakFind Microsoft sign-in, choose Collections → Open Microsoft 365 collection, or run YakFind open-cloud. Choose mail or files and sign in to the Microsoft work account that has access to the material. For mail, select a mailbox folder. For OneDrive or SharePoint, paste a folder sharing link that you can open with the same account. YakFind downloads the selected items and opens a separate local index for that account and collection. Open the collection again to check for source changes. Use Disconnect Microsoft 365 when the review ends. This removes the downloaded collection and its local notes and history. To remove a collection without signing in, close its window and run YakFind disconnect-cloud. Searching selected indexes from Copilot and Codex Install YakFind Desktop and index your collection once. Give each index you want to expose a short name and its absolute Lucene directory (for example index-v5 under your local profile). For a published shared index, use the directory that contains CURRENT. Only configure collections you want the AI client to read. Returned excerpts may be sent to the client's model provider. For VS Code Copilot, add a stdio server in .vscode/mcp.json: {"servers":{"yakfind":{"type":"stdio","command":"YakFind","args":["mcp","--index","pilot=/absolute/path/to/index-v5"]}}} For Codex, add this entry to config.toml: [mcp_servers.yakfind] command = "YakFind" args = ["mcp", "--index", "pilot=/absolute/path/to/index-v5"] Use the absolute path to the installed YakFind launcher if it is outside PATH. Repeat --index for additional collections. Ask the client to list_indexes, search a selected index, then get_passage for a citation in its results. A search returns one result per matching document, with the first match in context. Continue with nextOffset and the same revision. suggest_spellings lists candidate spellings, their edit distances and matching document counts.