NSMetadataQuery

First: use the NSMetadataQuery API documentation, which is correct as far as it goes (but still woefully incomplete). Ignore the "Searching File Metadata with NSMetadataQuery" Guide, which has many outright lies, and will probably confuse you more than it helps you. (For example, it claims "The query sends notifications as the results are returned in batches using the NSMetadataQueryDidUpdateNotification", which is simply not the correct notification.) (filed: #36211561)

I've seen NSMetadataQuery return results which are outside of the requested search scopes. With 10.13, it no longer returns private results outside of your sandbox (security hole!), but I have seen it return public results outside of your search scopes (e.g., system data files), so always check each result path to make sure it's in a folder you're actually searching.

Spotlight searches don't work inside bundles (such as your own app's bundle), even if you set the "scope" to a folder at or inside them. The contents of a bundle are "files" but they're not indexed by Spotlight so you'll never see them in any results.

• TODO: there's probably lots of other places which aren't indexed, and there's no API for telling if something is indexable or not

NSMetadataItem doesn't include NSMedatadaItemURLKey, even if you put it in valueListAttributes (bug?). It does include NSMetadataItemPathKey always, even if you don't request it, so just build your result URL out of that.