Incrementing Values Atomically with Cloud Firestore

Hey, there Firebase Developers! We wanted to let you know of a new feature we added to Cloud Firestore, and that’s the ability to increment (or decrement) numeric values directly in the database! Why is this a big deal? Because previously, if you wanted to increment a value in the database, you would need to use a transaction to keep it safe from concurrent writes.

Incrementing a step counter

For instance, imagine that your fitness app has a feature that allows groups of friends to pool their steps together for a “team step counter”. Then, imagine Bob and Alice both have their current team’s total steps recorded locally and try to add their values to it…


If both clients send down these new values at around the same time, it’s possible for Alice’s changes to be written first…

…and then for Bob’s changes to come in and overwrite Alice’s changes.

Why not a transaction?

In the past, if you wanted to prevent this from happening, you would have to use a transaction. And while transactions are still a fine solution, they are a little more difficult to write, they don’t support cases where the user is offline, and frankly, they seem a bit heavy-handed for something as simple as adding two numbers together.

Introducing the increment FieldValue

So now, if you want Bob to record his 500 steps in the app, you can simply do that by asking the server to increment the step_counter value. In an iOS app, for instance, you would write code that looks a little something like this.

  updateData(["step_counter" : FieldValue.increment(500)])

With this call, the database would instantly make the change based on whatever value it has. So even if Alice sneaks in a change before Bob’s request reaches the server, everything still works.

Now, there are two things to keep in mind when it comes to performing these operations:

Using increment with transactions

First of all, if you do want to add some logic to your operation (like, for instance, making sure this new value doesn’t go over or under a certain limit), you’ll still need to use a transaction. Luckily, we will soon release a fantastic video all about transactions that I can heartily recommend as a completely unbiased observer.

Document QPS limit

Second, don’t forget that documents are still limited to a sustained write limit of 1 QPS per document. I know it’s tempting to look at these numeric functions and start making counters left and right in your database, but if you think these are values you’re going to be updating more than once per second, you’re still going to want to rely on something like our distributed counter solution.

Reach out!

As always, if you have questions, feel free to contact us on any of our support channels, or post questions on Stack Overflow with the [google-cloud-firestore and firebase tags]( Good luck, and have fun!