One of the big differences between searching for files using the Finder’s Find and using Spotlight’s window is the latter uses ranked search, aiming to produce a Top Hit, and a shortlist of highly ranked alternatives, rather than an exhaustive list containing all the files meeting the search criteria. This article looks at how Spotlight decides which hits to include.

As before, this is based on multiple log extracts obtained with log privacy disabled, in a macOS 26.5.2 virtual machine running on a Mac mini M4 Pro also running 26.5.2. Extracts given below are from a search across all Spotlight domains for the term SPQUParse. This was actually embedded in at least two JSON (text) .logui files saved to the VM’s ~/Documents folder, but Spotlight (both in the Finder’s Find and its own window) is only able to find that term consistently in a single file, LogUI2026_07_06_22-44-00spotQuery1.logui.

To avoid the complication of incremental searching, the search term was pasted into Spotlight’s window, at a start time of 0.466508 seconds. Within 0.006 seconds Spotlight announced its query task, and started queries across all domains after a total elapsed time of 0.04 seconds:
0.506034 com.apple.spotlight [qid=37][SPQueryTask]["SPQ...<9 chars>"] Starting all queries
"SPQ...<9 chars>" is used throughout log entries as shorthand for the search term of SPQUParse.

As the first of those were completing, parsec and parsecd made a series of significant entries. First,
0.508379 com.apple.parsecd ECC completionsForInput: SELECT completion, type, score, MAX(engagement_date) AS engagement_date, topic_data, SUM(1.0 - ((1.0 - 0.1) / POWER(1.0 + 0.5 * EXP(0.008 * (((engagement_date - 805410600) / 3600.0) + 240.0)), 2.0))) AS freshness_score, count(1) as scount FROM completion_cache_engagement WHERE (input between ? and ? OR transformed between ? and ?) AND client == 2 GROUP BY completion HAVING COUNT(1) >= 2 ORDER BY freshness_score DESC LIMIT 1;
reveals the computation being used to arrive at the freshness_score, used subsequently in ranking search hits.

The equation given there can’t be taken at face value, though. The constant given there of 805410600 turns out to be Unix seconds for the time Monday 10 July 1995 21:10:00 GMT+0000, exactly 31 years (978307200 seconds) before the time of that log entry. That suggests the engagement_date is also given in Unix seconds, the difference being converted to hours, then computed as stated. Unfortunately, that can’t result in values of the freshness_score observed, between 0.5 and 0.65. I suspect values actually used by parsecd are transformed somewhere in the process, although the entry still establishes that freshness_score is based on a non-linear function of engagement_date.

Further and more opaque evidence of parsec involvement follows:
0.508709 com.apple.parsec FTE description lookup for parsecd/1 (VirtualMac2,1; macOS 26.5.2 25F84) spotlight/1, returning FTE of length 294
0.508740 com.apple.parsec FTE learn more lookup for parsecd/1 (VirtualMac2,1; macOS 26.5.2 25F84) spotlight/1, returning FTE of length 11
0.508768 com.apple.parsec FTE continue lookup for parsecd/1 (VirtualMac2,1; macOS 26.5.2 25F84) spotlight/1, returning FTE of length 8
0.509213 com.apple.parsecd cache lookup: '[private]' qtype Optional("suggest_with_results") suggest [private]
Note that key content in that last entry remains censored even when log privacy protection has been disabled (for the sake of simplicity here, square brackets replace the original angle brackets around private).

About 0.025 seconds later, the Metadata domain search reports it has found the search term:
0.534942 com.apple.SpotlightServices [qid=37]["SPQ...<9 chars>"][Metadata][complete] Sending response (time=28.870ms) with topHitIsIn:1 #(total):1 #(sections):1 section:{"com.apple.other" = 1;}

Ranking of hits proceeds in two phases, first as SpotlightRanking, then SpotlightPlusRanking
0.547288 com.apple.spotlight [SpotlightRanking] <Model> preparing 1 items for bundle com.apple.other
This is ranked to L1 before moving to SpotlightPlusRanking
0.547769 com.apple.spotlight [qid=37]["SPQ...<9 chars>"][SpotlightPlusRanking] Using MRScoringConfig Default, ScoringAlgo Default, queryKind SPQueryKindAsYouTypeTopHitSearch

The Top Hit, and only hit on this occasion, is then announced
0.547924com.apple.SpotlightServices [qid=37]["SPQ...<9 chars>"][SpotlightPlusRanking][i=1] topKBundle bundleID=com.apple.other, name="Log...<40 chars>", mrScore: 0.0898, mrScoreFreshness: 0.64881882, mrScoreResultType: -0.2000, freshnessDate: 2026-07-06 21:59:16 +0000, pommesL1=0.0000, L2=-4999.0000
The freshnessDate given there is the date of creation and last modification of the file to be returned as the Top Hit.

At this stage, Spotlight starts including related_search for two other files in the same folder as the Top Hit, both of which are of the same type and have other similarities, but weren’t returned in the metadata search, and later three items are added from com.apple.parsec.web_index. Unlike the Top Hit, those contenders have pommesL1 and L2 scores of 0.0000, compared to the Top Hit’s of 0.0000 and -4999.0000. As a result, only the single hit is returned, as the local file /Users/howardoakley/Documents/LogUI2026_07_06_22-44-00spotQuery1.logui. That file’s icon is obtained from QuickLook and displayed in the Spotlight window, as Spotlight completes its task.

Salient features of Spotlight’s AsYouTypeTopHit ranked search include:

• inclusion of hits across multiple search domains;
• a freshness_score as a measure of recency or topicality;
• three opaque scores of mrScore, pommesL1 and pommesL2;
• related search considering similar data sources and websites;
• identification of Top Hits.

These are dependent on several other subsystems, including parsec and parsecd, which must have access to a database of engagement_dates for items in different domains such as files and websites. This is likely to be Biome, which I haven’t attempted to document for some years, but is reflected in Apple’s documentation for CSSuggestion, part of Core Spotlight, which brings us full circle.