ReadonlycountThe number of results gathered so far.
ReadonlyidentifierA unique identifier for this query object (UUID string).
ReadonlyisWhether the query is in the initial gathering phase.
true from "didStart" until "didFinish"; false thereafter while live-monitoring.
ReadonlyisWhether the query is currently running (gathering or monitoring for live updates).
Returns grouped results when grouping attributes have been configured.
Returns an empty array if setGroupingAttributes() was not called.
An array of HSSpotlightGroup objects
Returns the current results as an array of HSSpotlightItem objects.
The result set is briefly frozen during access to ensure consistency. Safe to call
from within a query callback.
An array of HSSpotlightItem objects (may be empty if the query has not run)
Registers a callback that receives query lifecycle events.
of HSSpotlightItem objects describing what changed in this update cycle
Called with lifecycle event name and optional update data containing added/changed/removed item arrays
this query, for chaining
Sets the attributes by which results will be grouped.
When grouping attributes are set, use groups() to retrieve results organised into
HSSpotlightGroup objects. Specifying multiple attributes creates nested subgroups
accessible via group.subgroups().
An array of attribute name strings
this query, for chaining
Sets the NSPredicate query string for this search.
The string must be a valid NSPredicate format expression using kMDItem* attribute
keys and MDQuery operators (==, !=, <, >, BEGINSWITH, CONTAINS, etc.).
If the query is already running when this is called, it is stopped and restarted
automatically.
An NSPredicate-format query string
this query, for chaining
Sets the search scopes that restrict where Spotlight looks.
Pass an array of predefined scope strings from hs.spotlight.scope, absolute
directory paths, or a mix of both. Paths beginning with ~ are expanded to the
user's home directory.
When not set, the query defaults to hs.spotlight.scope.computer.
An array of scope-constant strings or absolute directory paths
this query, for chaining
Sets sort descriptors that control the order of results.
An array of sort descriptor objects
this query, for chaining
Sets the attributes for which aggregate value-list summaries are computed.
After the query finishes, valueLists() returns aggregate data for each specified
attribute: distinct values and the number of results carrying each value.
An array of attribute name strings
this query, for chaining
Starts the query.
The query must have a predicate set (via setQuery()) before calling start().
Calling start() on an already-running query is a no-op.
this query, for chaining
Stops the query while preserving accumulated results.
After stopping, results(), count, groups(), and valueLists() continue to
return the last gathered data. Call start() again to resume.
this query, for chaining
Returns aggregate value-list summaries for attributes set via setValueListAttributes().
Returns an empty array if setValueListAttributes() was not called.
An array of summary objects
A configurable Spotlight search query that can be started, stopped, and queried for results. Create instances via
hs.spotlight.create()or the convenience helperhs.spotlight.search(). Configure the query with chainable setter methods, register a callback, then callstart(). Results accumulate during the initial gathering phase ("didStart"→"inProgress"→"didFinish") and continue to update during the live-monitoring phase ("didUpdate"). Stop explicitly withstop()when you no longer need live updates.