Model or dataset
mazzzystar/Queryable avatar
mazzzystar/Queryable

Queryable: running MobileCLIP on iOS for offline natural-language photo search

Run OpenAI's CLIP and Apple's MobileCLIP model on iOS to search photos.

2,997 stars444 forksSwiftMIT

At a glance

What is it?
Queryable is an MIT-licensed iOS app that encodes your photo library with Apple's MobileCLIP and answers free-text queries like 'a brown dog sitting on a bench'. It is a reference implementation first and a shippable product second, and the README says so.
Who is it for?
Adopt Queryable if you want a readable, MIT-licensed example of on-device image-text retrieval in Swift, or if you are porting the same pipeline to another Apple platform. Do not adopt it as a production search backend: the author states he is not a professional iOS engineer, the README points readers at issues #4, #6, #10 and #11 as known weak spots, and the exported model files live on Google Drive rather than in the repository.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 15 days ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • mazzzystar/Queryable2,997 ★ · +11
Star history
Repository2026-09-252026-11-15
mazzzystar/Queryable3k3k

11 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Queryable actually solves, and for whom

The built-in iOS Photos search is category-based. It matches labels Apple has already assigned. Queryable takes a different input: a natural language statement, and the README's own example is `a brown dog sitting on a bench`. That sentence is not a category, and no label list would contain it. Queryable maps the sentence and every photo into the same vector space and ranks by similarity, so the query can describe a scene, a pose or a relationship between objects rather than a single noun.

The second half of the pitch is privacy. The README states the search runs offline, so the album is not sent to Apple or Google. That matters because the alternative way to get this quality of search is to upload the library to a service that has the compute. Queryable pushes the compute onto the phone instead.

The audience is therefore narrow and specific. It is for iOS developers who want a working example of on-device image-text retrieval, and for people who want the app itself from the App Store. It is not a library you import into an existing app, and it is not a server-side search product. The repository is the app: a SwiftUI project under `Queryable/`, plus two Jupyter notebooks used to export the models.

The four-step retrieval loop, and the two encoders behind it

The README describes the pipeline in four steps. Every photo in the album is passed through the image encoder and turned into a vector, and those vectors are saved. Each new text query is passed through the text encoder and turned into a vector in the same space. The text vector is compared against every stored image vector. The top K most similar images are ranked and returned.

The design decision that makes this work on a phone is the split. Queryable separates the text encoder and the image encoder at the architecture level and loads their weights individually, which the README calls "the trick". That split is what allows the expensive half to run once, at indexing time, and the cheap half to run on every keystroke of a query. A single fused CLIP model would force a full forward pass per search.

The default model is Apple's MobileCLIP, specifically the `s2` variant, which the README says balances efficiency and precision. The project originally used OpenAI's CLIP ViT-B/32, and the README strikes that name through, so the switch is visible in the text itself. MobileCLIP arrived in the 2024-09-01 update and is now the default.

The export workflow lives in `PyTorch2CoreML.ipynb` and `PyTorch2CoreML-HuggingFace.ipynb`. The README is blunt about the cost of that workflow: the ImageEncoder's Core ML export has a certain level of precision error, and more appropriate normalization parameters may be needed. That is a real caveat for anyone retraining or re-exporting rather than using the provided files.

Building Queryable in Xcode and running a first search

The model files are not in the repository. The README sends you to a Google Drive folder for `TextEncoder_mobileCLIP_s2.mlmodelc` and `ImageEncoder_mobileCLIP_s2.mlmodelc`. Download both before you open the project, because the app will not have anything to load without them.

Clone the repository, then place the two downloaded model bundles under the `CoreMLModels/` path. The README gives the layout directly:

bash
git clone https://github.com/mazzzystar/Queryable.git
cd Queryable
# put the downloaded model bundles here:
ls CoreMLModels/
# TextEncoder_mobileCLIP_s2.mlmodelc
# ImageEncoder_mobileCLIP_s2.mlmodelc

With the models in place, open the Xcode project under `Queryable/` and run it on a device. The README's instruction is simply to run Xcode and it "should work". Expect the first launch to spend time encoding the album, because that is the indexing pass described in the pipeline. Once indexing finishes, typing a phrase such as `a brown dog sitting on a bench` should return ranked photos rather than category matches.

Where Queryable breaks down

The indexing pass is the first wall. Every photo needs a forward pass through the image encoder before any search is possible, and that cost is paid on the device. The README does not describe incremental indexing, a background schedule, or what happens when you take a new photo after the initial pass. Anyone evaluating this for a large library should read the storage and sorting code rather than assume it scales.

Device support is the second wall. The README records that devices below iPhone 11 could not run the app, and that this was fixed by a contributor. That history tells you the model has a hardware floor, and it is worth checking which floor applies to the `s2` MobileCLIP build rather than the older CLIP build.

Precision is the third. The README states plainly that the ImageEncoder's Core ML export carries a certain level of precision error. An earlier contribution from `jxiong22` converted the HuggingFace `clip-vit-base-patch32` model and, according to the README, significantly reduced that error in the image encoder. So the accuracy of your results depends on which export path produced your model files, not just on which base model you chose.

Finally, this is the wrong tool if you want a maintained SDK. The author writes that he is not a professional iOS engineer and asks readers to forgive his Swift, suggesting they focus on the loading, computation, storage and sorting of the model. That is an honest description of scope. It is a reference implementation, and the parts around the model are the parts you are expected to replace.

PicQuery on Android and Searchable on macOS

If you need this on Android, the README points to PicQuery, a separate project by `greyovo` available on Google Play, which supports both English and Chinese. The difference in approach is not the model but the platform integration: PicQuery is its own app built against Android's media access rather than a port of the Swift code. The README notes the author said the code would be released in the future, so check the repository before planning around it.

On the desktop side, `yujinqiu` built a macOS version called Searchable, which the README describes as not open-sourced and as supporting full-disk search. That is a meaningfully different scope: Queryable reads the Photos album, while Searchable indexes files across the disk. If your problem is finding images anywhere on a Mac rather than inside Photos, Queryable is the wrong starting point and Searchable is the relevant one, with the caveat that you cannot read its source.

Within the Apple ecosystem the honest comparison is against the Photos app itself. Apple's search is faster and already indexed, and it costs you nothing to use. Queryable wins only on query expressiveness and on the privacy argument that the README makes explicitly.

Licence, maintenance and what a fork costs you

Queryable is MIT licensed, copyright 2023 Ke Fang. That permits commercial use, modification and redistribution, provided the copyright notice and permission notice are included. It does not grant rights to the MobileCLIP weights or to OpenAI's CLIP weights, which come from their own upstream projects and carry their own terms. The README does not discuss those terms, so treat the model licences as a separate question from the code licence. This is a description of the licence text, not legal advice.

The repository is not archived, and the last push was on 2026-03-29. That is recent enough that the project has not been abandoned, but the README does not describe a release cadence, a versioning scheme, or a deprecation policy, and the repository has no published GitHub releases. The upgrade cost you should plan for is not dependency churn. It is model churn: swapping the encoder means re-exporting with the notebooks, re-checking the normalization parameters the README warns about, and re-indexing every photo on every device, because the stored vectors belong to the encoder that produced them. That is the real maintenance bill here.

The README also asks that you not simply restyle the app and list it on the App Store, which is a request rather than a licence restriction. Under MIT you are not bound by it, but it tells you how the author views derivative store listings.

Editorial conclusion

Adopt Queryable if you want a readable, MIT-licensed example of on-device image-text retrieval in Swift, or if you are porting the same pipeline to another Apple platform. Do not adopt it as a production search backend: the author states he is not a professional iOS engineer, the README points readers at issues #4, #6, #10 and #11 as known weak spots, and the exported model files live on Google Drive rather than in the repository. Before committing, verify three things in the code: how image vectors are persisted across app launches, which devices fall below the MobileCLIP threshold, and whether the encoder precision error noted in the Core ML export section affects your own model.

Frequently asked questions

What is Queryable and what does it do?

Queryable is an open source iOS app that searches your Photos album using natural language statements, such as `a brown dog sitting on a bench`, instead of Apple's category-based search. It runs offline, so the README states your album is not sent to any company.

How do I run Queryable in Xcode?

Download `TextEncoder_mobileCLIP_s2.mlmodelc` and `ImageEncoder_mobileCLIP_s2.mlmodelc` from the Google Drive link in the README, clone the repository, place the models under the `CoreMLModels/` path, and run Xcode. The README says it should work at that point.

Which model does Queryable use?

The default is Apple's MobileCLIP, specifically the `s2` variant, which the README says balances efficiency and precision. The project previously used OpenAI's CLIP ViT-B/32, and the README still shows that name struck through.

Does Queryable work on older iPhones?

The README records that devices below iPhone 11 could not run the app and that a contributor fixed this. That history indicates a hardware floor, and the README does not state which devices the current MobileCLIP `s2` build supports.

Official sources

  1. Issues
  2. License: MIT
  3. mazzzystar/Queryable on GitHub
  4. Project website
  5. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/mazzzystar-queryable.svg)](https://hysenlabs.com/projects/mazzzystar-queryable)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/mazzzystar-queryable.svg)](https://hysenlabs.com/projects/mazzzystar-queryable)

Was this useful?