Databases don’t always know what you want. As engineers, we do our best to build resilient, scalable systems that address your needs with intuitive interfaces, but sometimes, we don’t know how to handle what we’re given. The system does its best, but leaves behind a conflict so you can clarify how you want to handle this situation.

Many databases, including Orchestrate and CouchDB, generate conflictss when they don’t know how to handle something. Conflicts contain all the information you as a developer would need to resolve them how you see fit, such as what happened, and what documents were affected. Then you can fix them up to your heart’s content.

So, in Orchestrate, how do conflicts happen?

Say you’re writing an application that saves names, like this:

    names: ['Max Thayer', 'Mx. Maximiline', 'M. Thayer']

But one of your developers hasn’t dismantled the falsehoods programmers believe about names, so they insert a document like this:

    names: 'Falco, Antony'

But when they try to insert it, they get a 409 -- indexing_conflict. The document is saved, but it doesn’t show up in searches. What gives?

N.B.: This post gets into the nitty-gritty of Orchestrate as a piece of technology. We recognize this implementation falls short of our goal of effortlessness, and we’re working on it. In the meantime, we want to make clear how that implementation affects you, and how you can keep it painless for you.


In Orchestrate, conflicts occur when the database doesn’t know how to handle something. Specifically, it doesn’t know how you want a new document to be searched. Orchestrate does its best, but leaves behind a conflict that you can resolve at your leisure.

Whenever you insert a document, we analyze its contents to determine how to index it for searches. Based on the type of each field in the document, we create a mapping. When you insert more documents, we refer to this mapping for how to index fields, or update it when we encounter fields we haven’t seen yet in your data.

But when a document has data in a known field of an unexpected type, Orchestrate doesn’t know how to index it. Because it’s of a different type, we can’t index it along previous values, but the document is technically valid, so we don’t want to just reject it. So, we create a conflict detailing the difference between what we expected and what we saw, so you can resolve it as you please.