Apache Solr Documentation

6.5 Ref Guide (PDF Download)
Solr Tutorial
Solr Community Wiki

Older Versions of this Guide (PDF)

Ref Guide Topics


*** As of June 2017, the latest Solr Ref Guide is located at https://lucene.apache.org/solr/guide ***

Please note comments on these pages have now been disabled for all users.

Skip to end of metadata
Go to start of metadata

Once you have indexed the content you need in your Solr index, you will want to start thinking about your strategy for dealing with changes to those documents. Solr supports three approaches to updating documents that have only partially changed.

The first is atomic updates. This approach allows changing only one or more fields of a document without having to re-index the entire document.

The second approach is known as in-place updates. This approach is similar to atomic updates (is a subset of atomic updates in some sense), but can be used only for updating single valued non-indexed and non-stored docValue-based numeric fields.

The third approach is known as optimistic concurrency or optimistic locking. It is a feature of many NoSQL databases, and allows conditional updating a document based on its version. This approach includes semantics and rules for how to deal with version matches or mis-matches.

Atomic Updates (and in-place updates) and Optimistic Concurrency may be used as independent strategies for managing changes to documents, or they may be combined: you can use optimistic concurrency to conditionally apply an atomic update.

Atomic Updates

Solr supports several modifiers that atomically update values of a document. This allows updating only specific fields, which can help speed indexing processes in an environment where speed of index additions is critical to the application.

To use atomic updates, add a modifier to the field that needs to be updated. The content can be updated, added to, or incrementally increased if a number.




Set or replace the field value(s) with the specified value(s), or remove the values if 'null' or empty list is specified as the new value.

May be specified as a single value, or as a list for multiValued fields


Adds the specified values to a multiValued field.

May be specified as a single value, or as a list.


Removes (all occurrences of) the specified values from a multiValued field.

May be specified as a single value, or as a list.


Removes all occurrences of the specified regex from a multiValued field.

May be specified as a single value, or as a list.


Increments a numeric value by a specific amount.

Must be specified as a single numeric value.

Field Storage

The core functionality of atomically updating a document requires that all fields in your schema must be configured as stored (stored="true") or docValues (docValues="true") except for fields which are <copyField/> destinations, which must be configured as stored="false". Atomic updates are applied to the document represented by the existing stored field values. All data in copyField destinations fields must originate from ONLY copyField sources.

If <copyField/> destinations are configured as stored, then Solr will attempt to index both the current value of the field as well as an additional copy from any source fields. If such fields contain some information that comes from the indexing program and some information that comes from copyField, then the information which originally came from the indexing program will be lost when an atomic update is made.

There are other kinds of derived fields that must also be set so they aren't stored.  Some spatial field types use derived fields.  Examples of this are solr.BBoxField and solr.LatLonType.  These types create additional fields which are normally specified by a dynamic field definition.  That dynamic field definition must be not stored, or indexing will fail.


If the following document exists in our collection:

And we apply the following update command:

The resulting document in our collection will be:

In-Place Updates

In-place updates are very similar to atomic updates; in some sense, this is a subset of atomic updates. In regular atomic updates, the entire document is re-indexed internally during the application of the update. However, in this approach, only the fields to be updated are affected and the rest of the documents are not re-indexed internally. Hence, the efficiency of updating in-place is unaffected by the size of the documents that are updated (i.e., number of fields, size of fields, etc.). Apart from these internal differences, there is no functional difference between atomic updates and in-place updates.

An atomic update operation is performed using this approach only when the fields to be updated meet these three conditions:

  • are non-indexed (indexed="false"), non-stored (stored="false"), single valued (multiValued="false") numeric docValues (docValues="true") fields;
  • the _version_ field is also a non-indexed, non-stored single valued docValues field; and, 
  • copy targets of updated fields, if any, are also non-indexed, non-stored single valued numeric docValues fields.

To use in-place updates, add a modifier to the field that needs to be updated. The content can be updated or incrementally increased.




Set or replace the field value(s) with the specified value(s).

May be specified as a single value.


Increments a numeric value by a specific amount.

Must be specified as a single numeric value.


If the price and popularity fields are defined in the schema as:

    <field name="price" type="float" indexed="false" stored="false" docValues="true"/>

    <field name="popularity" type="float" indexed="false" stored="false" docValues="true"/>

If the following document exists in our collection:

And we apply the following update command:

The resulting document in our collection will be:

Optimistic Concurrency

Optimistic Concurrency is a feature of Solr that can be used by client applications which update/replace documents to ensure that the document they are replacing/updating has not been concurrently modified by another client application. This feature works by requiring a _version_ field on all documents in the index, and comparing that to a _version_ specified as part of the update command. By default, Solr's Schema includes a _version_ field, and this field is automatically added to each new document.

In general, using optimistic concurrency involves the following work flow:

  1. A client reads a document. In Solr, one might retrieve the document with the /get handler to be sure to have the latest version.
  2. A client changes the document locally.
  3. The client resubmits the changed document to Solr, for example, perhaps with the /update handler.
  4. If there is a version conflict (HTTP error code 409), the client starts the process over.

When the client resubmits a changed document to Solr, the _version_ can be included with the update to invoke optimistic concurrency control. Specific semantics are used to define when the document should be updated or when to report a conflict.

  • If the content in the _version_ field is greater than '1' (i.e., '12345'), then the _version_ in the document must match the _version_ in the index.
  • If the content in the _version_ field is equal to '1', then the document must simply exist. In this case, no version matching occurs, but if the document does not exist, the updates will be rejected.
  • If the content in the _version_ field is less than '0' (i.e., '-1'), then the document must not exist. In this case, no version matching occurs, but if the document exists, the updates will be rejected.
  • If the content in the _version_ field is equal to '0', then it doesn't matter if the versions match or if the document exists or not. If it exists, it will be overwritten; if it does not exist, it will be added.

If the document being updated does not include the _version_ field, and atomic updates are not being used, the document will be treated by normal Solr rules, which is usually to discard the previous version.

When using Optimistic Concurrency, clients can include an optional versions=true request parameter to indicate that the new versions of the documents being added should be included in the response.  This allows clients to immediately know what the _version_ is of every documented added with out needing to make a redundant  /get request.

For example...


For more information, please also see Yonik Seeley's presentation on NoSQL features in Solr 4 from Apache Lucene EuroCon 2012.

Document Centric Versioning Constraints

Optimistic Concurrency is extremely powerful, and works very efficiently because it uses an internally assigned, globally unique values for the _version_ field. However, In some situations users may want to configure their own document specific version field, where the version values are assigned on a per-document basis by an external system, and have Solr reject updates that attempt to replace a document with an "older" version. In situations like this the DocBasedVersionConstraintsProcessorFactory can be useful.

The basic usage of DocBasedVersionConstraintsProcessorFactory is to configure it in solrconfig.xml as part of the UpdateRequestProcessorChain and specify the name of your custom versionField in your schema that should be checked when validating updates:

Once configured, this update processor will reject (HTTP error code 409) any attempt to update an existing document where the value of the my_version_l field in the "new" document is not greater then the value of that field in the existing document.

versionField vs _version_

The _version_ field used by Solr for its normal optimistic concurrency also has important semantics in how updates are distributed to replicas in SolrCloud, and MUST be assigned internally by Solr.  Users can not re-purpose that field and specify it as the  versionField for use in the DocBasedVersionConstraintsProcessorFactory configuration.

DocBasedVersionConstraintsProcessorFactory supports two additional configuration params which are optional:

  • ignoreOldUpdates - A boolean option which defaults to false. If set to true then instead of rejecting updates where the versionField is too low, the update will be silently ignored (and return a status 200 to the client).
  • deleteVersionParam - A String parameter that can be specified to indicate that this processor should also inspect Delete By Id commands. The value of this configuration option should be the name of a request parameter that the processor will now consider mandatory for all attempts to Delete By Id, and must be be used by clients to specify a value for the versionField which is greater then the existing value of the document to be deleted. When using this request param, any Delete By Id command with a high enough document version number to succeed will be internally converted into an Add Document command that replaces the existing document with a new one which is empty except for the Unique Key and versionField to keeping a record of the deleted version so future Add Document commands will fail if their "new" version is not high enough.

Please consult the DocBasedVersionConstraintsProcessorFactory javadocs and test solrconfig.xml file for additional information and example usages.


  • No labels


  1. I don't see a good description of updateRequestProcessorChain in the new reference guide.  There's a bit of info in "SolrCloud with Legacy Configuration Files".  In a single page need to cover: defining your custom chain, referencing your chain from an update processor, how to invoke (I think there's 3 ways: 1: reference it in default update, 2: update.chain=, and 3: I think maybe if it's the only chain defined, not sure on that), and then explain better about solr.LogUpdateProcessorFactory, solr.DistributedUpdateProcessorFactory, solr.RunUpdateProcessorFactory and the ORDER that they appear in.  Mentions of item running "only once" if placed before Distributed seems a bit odd in a SolrCloud environment, I can only think of 1 use case (log transaction to external system only once, not once per replica), and what happens if I don't include RunDupateProcessorFactory at all, and does it matter where I place the Log entry.  The old wiki has a bit more info but is also lacking, and also covers 1x/3x/4x.  A coordinated page covering basic end-to-end on this topic would be good, even if it resorted to linking to other pages for fine details.

    1. There is an open JIRA issue to add update processor chains to the Ref Guide:


      JIRA Issues Macro: Unable to locate JIRA server for this macro. It may be due to Application Link configuration.

      As with most things, someone just needs to sit down and do it. If you are knowledgeable about the subject, you could add some content to that JIRA and a committer can add it to the Guide. While editing the Guide is limited to the committers of Lucene & Solr, anyone can submit content to be added, either as a comment on a page or in JIRA issues.

  2. About "remove" modifier,when i remove a multiValued and solr.TrieDateField type field,it doesn't work.

    my schema is following:

    <fieldType name="date" class="solr.TrieDateField" precisionStep="0" positionIncrementGap="0"/>

    <dynamicField name="*_dts" type="date"    indexed="true"  stored="true" multiValued="true"/>

    my json is following:


    by the way,if string type,it works.

    is date type unsupported this modifier?


    i saw the source about DistributedUpdateProcessor.java 's doRemove method,the input param "Object fieldVal" is:

    pattern A: with url json,fieldVal will be a list<String>

    pattern B: with solrj api,fieldVal will be a String

    but original value is a Date.

    i think this is a reason why Collection can't match this value and remove it.

  3.  Is it correct to set the value of "versionField" as "_version_" in the class called "DocBasedVersionConstraintsProcessorFactory"? 


    1. great question! .. no, you can not use the existing _version_ field as your "versionField" in that processor – the _version_ must be assigned by solr for distributed document updates to work properly.

      I've added a special note about this – thank you for asking.

  4. Cassandra Targett, regarding "remove Removes (all occurrences of) the specified values from a multivalued field." - actually it looks like the "remove" command only removes the first occurrence from the list of values, not all matches. At least with Solr 5.2.1.



    1. it's definitely remove all, and there are passing tests that demonstrate this (see AtomicUpdatesTest)


      If you are having difficulty with a feature, please email the solr-user mailing list directly with the details of your situation+problem

      1. I agree with Alexander Kanarsky the documentation isn't correct here, the "remove" action only removes the first instance of a value from a multi-valued field. The source code in AtomicUpdateDocumentMerger confirms this, as does testing using curl. The unit tests in AtomicUpdatesTest don't actually cover this behaviour - adding an extra assertQ confirms that only the first instance of a value is removed.

        Using "removeregex" does remove all instances, however.

        I will raise a JIRA ticket with some more unit tests for this, but it's something that has bitten us - until we looked into the actual field values after updates.

        1. I added more tests, if someone would be kind enough to review and merge this Jira..  SOLR-9505


      2. having same problem with

        • solr-spec5.3.0

        • solr-impl5.3.0 1696229 - noble - 2015-08-17 17:10:43

        Unfortunately can't test env. on newer versions

        1. Please use the mailing list or IRC channel for support requests.  And be more descriptive than "having same problem."


  5. What is the java-methods to be used to accomplish the same ?
    I have tried the methods described for earlier versions, but those overwrites the document, and only saves the values from the new SolrInputDocument.

    Do I have to code my java-program to use http-requests with Json (or XML) in order to update a 5.0.3-index ? 

    1. Here is some SolrJ code (Java 7 compliant) for utilizing the Atomic Update feature. To make change, you need to use a Map object as the field value:


      SolrJ code for Atomic Update

        String solrBaseurl = "http://hostname:port/solr";
       String collection = "mydocs";

       SolrClient client = new HttpSolrClient(solrBaseurl);
       SolrInputDocument doc = new SolrInputDocument();

       doc.addField("id", "test");
       Map<String, String> cmd1 = new HashMap<>();
       Map<String, String> cmd2 = new HashMap<>();
       cmd1.put("set", "newvalue");
       cmd2.put("add", "additionalvalue");
       doc.addField("field1", cmd1);
       doc.addField("field2", cmd2);
       client.add(collection, doc);


      This is also covered at the bottom of this blog post:


  6. In Solr 5.0.0 our application was using child documents. In order to update a solr document that had child documents we had to jump through some hoops. Basically, do a get of the original document from the collection, (SolrDocument returned), perform a deep copy of the parent and add in the child documents again (to a SolrInputDocument - the deep copy didn't seem to include the children) - update the new document with the changes. Delete both parent/children from collection and then add the new updated document.

    A section of the 5.0 code looked like:


    SolrInputDocument newDocument = ClientUtils.toSolrInputDocument(originalDocument).deepCopy();
    for (SolrDocument child : childDocuments){


    In 6.0, ClientUtils.toSolrInputDocument was removed - maybe my google foo is lacking but I have not found documentation on how to achieve the same (yes, I could pull out all the original values into a hash and reinsert into a SolrInputDocument but I was hoping for a nicer way).




  7. Hii,

      Last 2 day am trying to update the solr document. am using 6.0

    This is my document { "id" : "14", "solrid" : "solr|school|14", "name" : "test update solr 14", "status" : "pending", "state" : "Andhra Pradesh", "board" : "CISCE", "updated" : "2016-05-26T02:24:25Z", "pincode" : "0" }

    I want to update particular data on document as per id. example i want to change the name,status ...

    How to update the document.

    i am using  PHP Solarium .

    1. This page tells you how to do what you are trying to do.

      After you try the documentation here, if you run into problems, please use the mailing list to get help. Be sure to explain what you have already done and what happened.

    2. if i understand correctly what u are looking for, soln is if your "id" is unique key in managed-schema xml then if you try to enter the same doc it ll update.

      1. Please move this conversation to the user's list, we try to reserve comments here for documentation problems, not usage questions.

  8. There should be a paragraph introducing how to apply atomic update using format other than JSON, e.g. in XML. I happen to find this article in solr-user: