# Searching your documents This page shows you how to find things with SearchBox: how a search actually works, how to read the results page, and how to use the `::` filters to narrow a search down to exactly the files you want. By the end you'll be able to write a query like `quarterly report::pdf::docx` and know precisely what it will return. ## How searching works SearchBox doesn't only match file names — it reads *inside* your files. When you index a folder or upload a document, SearchBox extracts the text from it and adds it to an index (a catalog of every word in every file, built ahead of time so searches come back in milliseconds). Two things are worth knowing up front: - **Search is typo-tolerant.** Typing `quartarly` still finds documents about "quarterly." You don't have to spell perfectly. - **Nothing runs until you say so.** SearchBox searches when you press **Enter** or click **Search Documents** — not on every keystroke. > 🔒 Every search happens on your own computer. Your queries and your documents never leave your machine. ## Running a search 1. Type what you're looking for in the search box on the home screen. 2. Press **Enter**, or click **Search Documents**. That's it. Clicking the magnifying glass icon in the search box does the same thing. Once results appear, the search box moves to a bar at the top of the page — type there and press **Enter** to search again. Two more buttons sit next to **Search Documents**: - **Search Images** — runs your query against your indexed pictures and opens the image results page. - **Explore** — opens a browsing view of everything in your index, no query needed. ![The SearchBox home screen with the search box and buttons](img/home-screen.png) ## Reading a result Each result on the page has the same anatomy, top to bottom: - **Type badge** — a small colored label showing the file format: red **PDF**, blue **DOC**, gray **TXT**, green **MD**. - **Source line** — where the file lives, with an icon: **Folder** (a folder you indexed), **Vault** (an encrypted document — these also carry a small lock badge, because a PIN is required to view them), **ZIM Archive** or **ZIP Archive** (a file inside an indexed archive), or **qBittorrent** (a downloaded file). The line also shows the file type and size. - **Title** — the file's name, cleaned up for reading (the extension is dropped and underscores become spaces). Words that matched your search are highlighted. - **Snippet** — the first stretch of matching text from *inside* the file, again with your search terms highlighted. This is how you can tell at a glance whether the document is the one you want. Documents that contain pictures show a small thumbnail beside the snippet, plus a badge with the picture count. On the right side of the results page you'll see the **image rail** — a vertical strip of up to seven pictures. SearchBox runs a second, image-only search using the same query and shows the best matches there. (Standalone image files are deliberately kept out of the main results list so they don't crowd it — the rail is where they live.) Click a picture to preview it, then click **View Document** to open it fully. If there are more matches than fit, a **View More** tile at the bottom shows how many, and clicking it takes you to the full image results page. ![A results page showing the parts of a result and the image rail](img/search-results-anatomy.png) ## Moving through pages Results come ten to a page. The line above the results tells you where you are — for example, "Page 2 of 14 (137 results in 6ms)." At the bottom of the list you'll find **Previous** and **Next** buttons plus numbered page buttons; click any of them to jump. The page scrolls back to the top for you. ## Filtering with `::` Add `::` and a file type to the end of your query to narrow the search. For example, `budget::pdf` finds only PDFs that mention "budget." You can chain several types together: `budget::pdf::docx` searches PDFs *and* Word documents. | Filter | What it narrows to | Example | |---|---|---| | `::pdf` | PDF documents | `tax return::pdf` | | `::docx` `::doc` | Word documents | `meeting notes::docx` | | `::txt` | Plain text files | `server log::txt` | | `::md` | Markdown notes | `recipe::md` | | `::jpg` `::jpeg` `::png` `::gif` `::webp` `::svg` `::bmp` | Image files of that format | `logo::png` | | `::image` | Jumps to the image results page for your query | `sunset::image` | | `::vault` | Only documents in your encrypted vault | `passport::vault` | | `::zim` `::zip` | Only content from indexed ZIM or ZIP archives | `physics::zim` | | `::torrent` | Only files downloaded through qBittorrent | `dataset::torrent` | > 💡 **Tip:** Write file types without a dot — `::pdf`, not `::.pdf`. ### Combining conditions Three operators let you build compound searches: | Operator | Meaning | What it does | |---|---|---| | `::&&` | AND | Both parts must match | | `::\|\|` | OR | Either part can match | | `::!` | NOT | Exclude what follows | Realistic examples: ``` quarterly report::pdf::docx ``` Finds "quarterly report" in PDFs and Word documents. ``` "neural networks"::pdf::&& "deep learning"::txt ``` PDFs about neural networks AND text files about deep learning. ``` recipes::md::|| recipes::txt ``` Recipes in Markdown notes OR plain text files. ``` report::pdf::! draft::txt ``` PDF reports, but NOT text-file drafts. ### Wildcard and exact phrases - `*` on its own browses everything in your index. - `*::pdf` lists every PDF you've indexed; `*::vault` lists everything in your vault. - Wrap words in double quotes to match them as an exact phrase: `"financial report"::pdf`. ## Live syntax colors As you type, the search box border changes color to tell you how your query looks: - 🟢 **Green** — the syntax is valid and ready to run. - 🟠 **Orange** — you're partway through an operator (for example, the query ends in `::&&` with nothing after it). Finish the thought. - 🔴 **Red** — there's an error, such as a file type SearchBox doesn't recognize (`::xyz`). ![The search box showing a green border on a valid filtered query](img/search-syntax-green.png) ## The "Search Syntax Issues" popup If you run a search that has problems anyway, SearchBox stops and shows a popup titled **Search Syntax Issues Detected**. It repeats your query, lists each issue it found, and offers a suggestion for each one. You get two choices: - **Fix Syntax** — closes the popup and puts your cursor back in the search box so you can correct the query. - **Continue Anyway** — runs the search as-is. It will still work as a plain search, but the advanced filters may not behave the way you intended. ![The Search Syntax Issues popup with Fix Syntax and Continue Anyway buttons](img/search-syntax-issues.png) ## Built-in help A round **?** button sits in the bottom-right corner of the page. Click it to open **Help & Search Commands** — a reference of every filter, operator, and example on this page, available inside the app whenever you need a reminder. ![The in-app Help & Search Commands reference](img/search-help-modal.png) ## Related pages - [Bookmarks and suggested searches](./bookmarks-and-history.md) — pin your five most-used documents and let SearchBox suggest queries. - [The vault](./vault.md) — how encrypted documents work and how `::vault` finds them. --- [← Back to the manual](./README.md)