There is one algorithm. A first Sync and a Re-Sync differ only in what the phone's own copy of the index already holds: the comparison is between your folders and that copy, on the phone, and a first sync compares against an empty copy, so everything is added.
Figure 1 — the steps of every sync, forced, scheduled or started by pulling the photo grid down. The comparison happens on the phone; only the deletes, the photos to be read and the words to be carried up leave it.
The phone keeps a copy of every document its index holds: the id, the path, the file name, the size, the dates, the camera, the EXIF, the place, the words the photo was read into, the printed text read out of it, the people, your own tags and the md5 of the file. It does not hold the search vector and it does not hold the duplicate keys.
The copy is read out of the index once, at install or reinstall. From then on every write keeps it in step, so it is never read again.
A sync with nothing to do makes no requests at all. For a library of 10,000 photos version 2.4 made about 21 requests and downloaded about 1.8 MB on every single sync, only to find out that nothing had changed.
- Make sure the index is there. Reuse it, create it, or create it again if it vanished; check it carries the app's current configuration. See the phone's index.
- Scan the chosen folders through MediaStore and give every photo its id, the md5 of its path inside the phone's storage. MediaStore already leaves out files still being written and files in the trash.
- Compare, on the phone. The ids and file sizes found in the folders are held against the phone's copy of the index. No request is made, nothing is paged, nothing is downloaded: both sides of the comparison are already on the phone.
- Delete every id that is in the copy but no longer on the phone, 500 per request, and drop it from the copy.
- Hand to Opensolr every photo that is on the phone but not in the copy, every photo whose file size differs from the one the copy holds (a photo edited in place keeps its id and is read again from scratch), every photo you asked to re-sync from the grid, and every photo indexed without words while the plan had no AI or while the AI server could not answer. A photo that comes back without words again waits a little longer each time (1 hour, 4 hours, 16 hours, then once a day) before it is asked again, so it can never keep the sync busy. A missing place never sends a photo again: the place is looked up once, when the photo is handed over, and a position with no known place is simply indexed without one. Five photos per call, to
photos_ingest. - Carry up the words you changed since the last sync — tags, people, wording — through
photos_words, 50 photos per call, with no pictures attached, because only the words changed. A sync may consist of nothing else.
A sync therefore has two kinds of work, and either can be empty: photos that must be read, five per call with a picture attached, and words to be carried up, fifty per call with no picture. After the last call the app makes a hard commit, updates its copy of the index with everything it just wrote, and reads the plan usage again.
The phone's copy and the index are matched to the file by its md5. That is what lets a later pass that cannot read a photo — a plan without vector search, or the monthly AI allowance used up — keep the printed text and the words read out of it earlier instead of clearing them, as long as it is the same file.
A sync that actually wrote something is also what throws away the cached filter lists, so they are asked for again; a sync that wrote nothing leaves them as they are.
Figure 2 — the comparison, both sides on the phone: keep what is in both, add what is only in the folders, delete what is only in the phone's copy of the index.
- For each photo that has to be read, the app reads its camera details on the phone and makes an upright 1024 px JPEG copy carrying the original's EXIF, adding the md5 of the original file, and your tags, your wording and the people you named on that photo when this phone holds them. That copy is the only picture that ever leaves the phone, and it is made only on this path: on a plan without vector search there is nothing to read, so no copy is made and no picture is sent.
- One
photos_ingestcall takes up to ten of those. The server does the rest: it reads the EXIF, asks the image model what the photo shows, has the text printed in the photo read when it carries any, turns the words into the search vector, resolves the GPS position into a place (city, region, province, community, country), takes the names of the people from the phone or keeps the ones already in the index, keeps the tags and wording already in the index for photos the phone did not speak for, writes the duplicate keys, builds the complete document and writes it into your index. - One
photos_wordscall takes up to fifty photos whose words alone changed — tags, people, wording. No picture is attached and no photo is read again: only those fields are written, and everything else the document holds stays as it is. On a plan with vector search the server makes the new search vector out of those words, one embedding for the whole batch. - Both writes carry
commitWithin=10000, so a photo turns up in search within about ten seconds while the next call is already on its way. Nothing is written back into your photos; what comes back is the document the server has just written, and that is what the phone stores in its copy of the index, so the two stay in step.
A photo the monthly allowance cannot cover is indexed without words and without a vector, and read again at a later sync. If it had already been read before, the printed text and the words read out of it are kept, not blanked, as long as it is the same file — the md5 says so.
The phone keeps two things in a private SQLite database: its copy of the index, described above, and your edits that have not gone up yet — the tags, the people and the wording you gave a photo. Both are written the moment you save.
Tagging is local-first. Saving tags, names or wording is finished on the phone, right then; the sync that starts straight after carries the change up, fifty photos per call, with no picture attached. You do not wait for it and nothing is lost if it has to be tried again.
Nothing is ever written to the photo files themselves: your words live in the phone's copy and in your index.
A reinstall is the one moment the whole index is read back, to rebuild the phone's copy — the only time the app reads the index's contents wholesale. After that nothing is re-indexed: an unchanged photo is already in the index and is not touched, a changed one is read again, and the tags and wording in the index come back with its document. Opensolr keeps its own answers, so a picture it has already read is served from its cache instead of being read again.
Skips it, counts it as skipped, carries on. A photo the phone cannot read is not tried again until the file changes or you pick it for Re-sync, and it is listed on the Photos screen under the red icon; a photo refused by the server is tried again at the next sync.
The app paces its calls under your account's limits by itself. If the server still asks it to slow down, the run stops and is started again a little later, rather than holding the phone awake waiting.
Carries on. From the first refused request the rest of the run writes photos without words and without vectors (date, camera, place, file name and your tags only), counts them, and says so on the Sync screen and in a notification. Those photos carry no clip_model, so the first sync after the allowance resets reads them into words. A photo that had already been read keeps the printed text and the words it was read into, matched to the file by its md5.
More than 500 photos waiting to be read waits for the charger, so a long first sync or a reset does not empty the battery.
Stops and posts a notification that opens your Opensolr account.
Nothing is sent to be read at all: no 1024 px copy is made and no picture leaves the phone. Photos are indexed by date, camera, place, file name and the owner's tags, found by those words, and search runs on words only, as Opensolr's site search does on such a plan. A photo read on an earlier plan keeps the printed text and the words it was read into, matched to the file by its md5. The Sync screen says how many photos were indexed this way, and the account screen says why.
Reads the new one from the account and retries.
Stops and asks you to sign in again.
Commits what was written and stops; the next sync continues.
A run never has to start over. The next Re-Sync compares ids again, against the phone's copy, and only adds what is still missing. Pulling the photo grid down reloads it and starts a sync as well; a sync that is running is stopped first and started again.
Re-read on the Sync screen sends every photo through Opensolr again, as when it was first indexed, so it gets whatever Opensolr does better now: the words it is read into, the place, the people and its search vector.
- Nothing is emptied. Search keeps working the whole time; each photo is simply written again.
- Your tags, the people you named and your own wording are kept, taken from the phone, from the index as it is, or from words an older version of the app left in the photo files.
- Your photos are not touched.
- The progress shows the real total from the first photo. If the run stops, for a low battery or because you pressed Stop, the next sync carries on where it was: photos already read again are not sent twice.
- The phone's copy of the index is rewritten photo by photo as the writes go up, so the copy and the index are never out of step.
Use it after an update that improves how photos are read. Reset does the same by emptying the index first, which is only needed when the app says the index configuration changed.
Every configuration carries a version number, inside the index itself (/opensolr-photos-config answers it) and inside the app. A new version of the app can ship a newer schema.xml or solrconfig.xml; when the index is on an older one, nothing happens until you agree:
This version of Opensolr Photos comes with a new index configuration. Your index will now be reset and every photo synced again. — Later keeps searching on the old configuration and pauses syncing; Reset and re-sync starts it.
- Nothing of yours is lost. The tags, the people and the wording — including any that came from a reinstall or from another phone — are already on the phone, in its copy of the index, and they are read out of it before anything is emptied.
- The index is emptied, and only then is the new configuration uploaded: no document ever sits in the index under a schema that is not its own.
- Every photo is handed to Opensolr again, five per call, exactly as in an ordinary sync, with your tags and wording carried along.
- The phone's copy is emptied and rebuilt along with the index, write by write, so the two end the reset in step.
The photo grid shows Rebuilding your index with the count meanwhile, and search keeps working while the photos come back, ten seconds behind each write. An index set up by a newer app than the one installed asks for an app update instead, and is left alone.