Purge locally document and avoid pull replication

suppose i have an android application with Couchbase LITE 2.0 installed, with pull and push replication active in sync gateway. I have also a couchbase server 5.0.

Every document is associated with a channel, for example channel_company_"id_company".

Now, i’d like to create a document in the android app and push it to the server, and, when the end_datetime field is set( by the application), i’d like to purge my document from android app seen that i will no longer use it, but i need anyway to store the document in my couchbase server.

If i purge the document locally, the push replication will delete the remote’s one as well. I’ve seen that i could set document’s id to not push over, but would be very messy to track every document id.

How could i handle this scenario?

One possible way - You could implement logic on your server end that will move documents that have the end_datetime set to a separate channel (like a “history” channel) that is not replicated over to the clients.

in that case i should save end_datetime locally(in the android application), then, in server set the channel(for example “history” as you suggested) and finally purge the document in the android application?

Yes. You update the document via the app. The Sync function processes the updated document. Thesync functionshould be implemented such that if document has this particular property set, you put it in a “history” channel

Check out this post

You could but you don’t have to purge the document locally. CB Lite has built in purging mechanisms that will remove old revisions. This blog post may be a useful read.

1 Like

No; you’re thinking of deletion. Purges are not replicated, so if you purge a document it will not affect the server.

You can do exactly what you’re asking for by setting an expiration date on the document. After that time it will automatically be purged locally.

Hi, sorry to answer a bit late, but i just have the occasion to test the purge functionality.
If i use this method:


and check sync gateway interface(locahost:4985), the purged document become like this:

  "_rev": "the revision",
  "_id": "the id"

so it seems that the purge action is replicated to the server.
What am i doing wrong?

Suppose that the app can work offline. In that case how could i handle the deleting document?
Because if i purge the document when there is no connection, the data won’t be replicated. I though about filter locally the document that i retrive, for example checking if the end_datetime is setted, and then, when in the replication listener i get an IDLE status, i purge the document. Do you think it could be a good solution or there is a better way?

Another approach could be to set an expiration date, but, as you write in your blog

Note that by specifying an expirationDate manually, you run the risk of expiring documents added to Couchbase Lite in offline mode before they get a chance to sync up with the Sync Gateway.
Do you think that TTL could be a solution in some way?

NB: i tried to set expiration date on a document, but there is no method for that. How can i set it?

I don’t think that’s possible … the purge method deletes the document from the internal SQLite store, so there’s no trace of it left. The replicator won’t even be able to see that the document used to exist.

Can you describe exactly what steps you followed to get your result?

I’ve this singleton database:

          DatabaseConfiguration config = new DatabaseConfiguration(MyApplication.getInstance().getContext());
          mDatabase = new Database(DATABASE_NAME, config);
          mDatabase.addChangeListener(new DatabaseChangeListener() {
                public void changed(DatabaseChange change) {

            mDatabase.createIndex("TypeIndex", Index.valueIndex().on(

            URI uri = new URI(REPLICATION_URL);

            ReplicatorConfiguration replConfig = new ReplicatorConfiguration(mDatabase, uri);

            List<String> channels = new ArrayList<>();

            Replicator replicator = new Replicator(replConfig);

When i purge the document i do, passing the id of the document, where getDatabase return mDatabase, set before:

public void purgeDocument(String id) {
        Document document = getDatabase().getDocument(id);
        try {
        } catch (CouchbaseLiteException e) {

When i call purgeDocument, in CBL there is no trace of the document, and in sync gateway interface i’ve got:

  "_rev": "the rev",
  "_id": "the id"

What was the document before you purged it? Did it get replicated to SG before or after the purge?

Ok, in my ignorance i set ended_at field and saved the document, and just after that i purged it, so when the replicator started, it didn’t find nothing to replicate. Sorry for the newbie error.
So the question is still there, how can i set a field, replicate that change, and then delete the document(for delete i mean that the user of the smartphone won’t see the document anymore, could be a purge, of a filter in the query), even if there is no connection?

I believe I answered this part of the question earlier about how to set a field, replicate and then delete .

Basically, once the document change is replicated and pushed to a different channel as discussed above , you can purge it locally if you’d like. You don’t have to do that though - in the next replication cycle, since document is removed from the channel that the client has subscribed to , you will see it come down with a special _removed flag that you can use as an indication that this document is not to be used by your client.

As for this part of your question
even if there is no connection?

Well- if you are offline, you cannot replicate the change . So you can’t purge the document locally since the the changed document isn’t up on the server.

I would think that you should implement app-layer logic to handle the case- basically disallow usage of the document locally if the flag is set.

1 Like