Search files and check the results
Search Diagnostics helps you find readable files in a selected folder and understand how the results were obtained. It opens in its own window, so you can keep an inspector report visible alongside it. Drag its title bar to move it and its edges or corners to resize it. Opening Search Diagnostics again brings the existing window forward.
Run a search
- Open Search Diagnostics in the toolbar.
- Choose Choose Folder…. The selected folder and its readable subfolders define the search area. The other setup controls stay disabled until you choose a folder.
- Select a search mode, enter a query, and choose Search or press Return.
- Review the returned paths, dates, content status, and Search stages. Read coverage notes before treating a result list as complete.
Choose a small, relevant folder first. Large folders, long documents, and text recognition can take time. Cancel stops the operation; any results already shown may be incomplete. Done or the window’s close button also stops active work. Changing the query, mode, or folder clears old output.
Choose the right mode
- Metadata text search
- Use a filename or literal text such as
READMEorinstallation. It matches filenames and indexed text, then also checks locally extracted content. Matching ignores case. It does not interpret a question or understand synonyms. - Natural-language search (on-device)
- Ask a question such as “Which document explains how to install the software?” An available Apple Intelligence model interprets the request and evaluates readable metadata and document text on your Mac. Its response is an interpretation; check the returned files and coverage.
Check Model rechecks availability. It does not enable Apple Intelligence or download a model itself. If the model is unavailable, use Metadata text search or a supported date query below. Model availability help.
Find the latest or oldest files
Select Natural-language search (on-device) and use one of these supported English date queries. The app interprets them locally, so they also work when the model is unavailable.
| Example query | What it requests |
|---|---|
| Give me the latest Markdown file. | One Markdown file with the newest modification time. |
| Show the newest 3 created Markdown files. | Up to three Markdown files, ordered by creation time. |
| Show the oldest PDF files. | PDF files ordered from oldest to newest modification time. |
| Show files modified yesterday. | Files modified during yesterday’s local calendar day. |
| Show Markdown files modified in the last 7 days. | Markdown files modified within the preceding seven days. |
“Latest” and “newest” use filesystem modification time unless you say “created.” These are the file’s dates on disk, not dates mentioned inside a document. “Today” and “yesterday” use your Mac’s local calendar. Files with unavailable dates cannot be reliably placed in that order; the report identifies these gaps.
A singular request such as “latest file” asks for one result. A plural request without a number can return all matching files in date order. Adding a number requests that many results; it is not a general search limit.
Which contents can be read?
- Plain text, Markdown, source code, and supported text formats such as CSV, JSON, XML, and HTML.
- PDF text, plus text recognition on PDF pages without extractable text.
- RTF, RTFD, DOC, DOCX, and ODT through native document readers.
- Text in supported images through OCR (optical character recognition). OCR reads visible text; this is not general recognition of objects or scenes in an image.
Readability depends on the file and macOS’s readers. Unsupported formats, locked PDFs, read errors, or model failures can leave gaps. OCR can misread text. A filename or metadata match can still be found when its body cannot be extracted; this is not proof that the complete body was searched.
Read and copy the results
Search coverage reports how many files were checked and what could not be read. Source labels distinguish filesystem retrieval from combined Spotlight/filesystem retrieval. An extraction status, such as “Text streamed locally,” describes how body text was read when extraction was requested. The natural-language Search response summarizes selected evidence; date-query responses describe actual date ordering.
Result lists start with 100 visible rows. Use Show More Results for later rows. There is no fixed overall result-count cap. Copy includes every retained result, stages, and any error or incomplete status, not just the visible page. Long stage details are available through Full Value….
No matches means no match was found in this operation’s checked data. It does not prove that a file is absent, unindexed, or unavailable to every other app.
Technical detail: retrieval and model limits
Literal search combines scoped NSMetadataQuery results with filesystem traversal. Spotlight gathering has a 30-second deadline; failure is reported and filesystem searching continues. There is no fixed global depth, query-character, candidate, result, or overall duration limit.
For general natural-language queries, a requested type can narrow the scope. Otherwise every readable candidate remains eligible. Literal Spotlight hits are prioritized without excluding other files. Metadata and extracted bodies are evaluated in context-sized chunks, with concise judgements. Displayed paths come from scoped retrieval, not invented model identifiers. Model availability, supported languages, context capacity, and safety rules can still limit an operation; incomplete processing is reported.
The results do not expose Apple’s raw relevance scores, embedding vectors, private entity stores, or whether a semantic index is ready. Apple’s on-device model reference.
Search privacy
The inspector does not send files or queries over the network and configures no cloud model. Search reads only within its selected scope. It does not donate file content to an index, force reindexing, execute document scripts, or run importer code. Search-folder access lasts for this session and is not saved as a bookmark.
Copied output can contain paths, metadata, and summaries of document contents. Review it before sharing it with another person or app.