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

SolrJ is an API that makes it easy for Java applications to talk to Solr. SolrJ hides a lot of the details of connecting to Solr and allows your application to interact with Solr with simple high-level methods.

The center of SolrJ is the org.apache.solr.client.solrj package, which contains just five main classes. Begin by creating a SolrClient, which represents the Solr instance you want to use. Then send SolrRequests or SolrQuerys and get back SolrResponses.

SolrClient is abstract, so to connect to a remote Solr instance, you'll actually create an instance of either HttpSolrClient, or CloudSolrClient .  Both communicate with Solr via HTTP, the difference is that HttpSolrClient is configured using an explicit Solr URL, while CloudSolrClient is configured using the zkHost String for a SolrCloud cluster.

Single node Solr client
SolrCloud client

Once you have a SolrClient, you can use it by calling methods like query(), add(), and commit().

Building and Running SolrJ Applications

The SolrJ API is included with Solr, so you do not have to download or install anything else. However, in order to build and run applications that use SolrJ, you have to add some libraries to the classpath.

At build time, the examples presented with this section require solr-solrj-x.y.z.jar to be in the classpath.

At run time, the examples in this section require the libraries found in the 'dist/solrj-lib' directory.

The Ant script bundled with this sections' examples includes the libraries as appropriate when building and running.

You can sidestep a lot of the messing around with the JAR files by using Maven instead of Ant. All you will need to do to include SolrJ in your application is to put the following dependency in the project's pom.xml:

If you are worried about the SolrJ libraries expanding the size of your client application, you can use a code obfuscator like ProGuard to remove APIs that you are not using.

Setting XMLResponseParser

SolrJ uses a binary format, rather than XML, as its default response format. If you are trying to mix Solr and SolrJ versions where one is version 1.x and the other is 3.x or later, then you MUST use the XML response parser.  The binary format changed in 3.x, and the two javabin versions are entirely incompatible.  The following code will make this change:

Performing Queries

Use query() to have Solr search for results. You have to pass a SolrQuery object that describes the query, and you will get back a QueryResponse (from the org.apache.solr.client.solrj.response package).

SolrQuery has methods that make it easy to add parameters to choose a request handler and send parameters to it. Here is a very simple example that uses the default request handler and sets the query string:

To choose a different request handler, there is a specific method available in SolrJ version 4.0 and later:

You can also set arbitrary parameters on the query object.  The first two code lines below are equivalent to each other, and the third shows how to use an arbitrary parameter q to set the query string:

Once you have your SolrQuery set up, submit it with query():

The client makes a network connection and sends the query. Solr processes the query, and the response is sent and parsed into a QueryResponse.

The QueryResponse is a collection of documents that satisfy the query parameters. You can retrieve the documents directly with getResults() and you can call other methods to find out information about highlighting or facets.

Indexing Documents

Other operations are just as simple. To index (add) a document, all you need to do is create a SolrInputDocument and pass it along to the SolrClient's add() method. This example assumes that the SolrClient object called 'solr' is already created based on the examples shown earlier. 

Uploading Content in XML or Binary Formats

SolrJ lets you upload content in binary format instead of the default XML format. Use the following code to upload using binary format, which is the same format SolrJ uses to fetch results.  If you are trying to mix Solr and SolrJ versions where one is version 1.x and the other is 3.x or later, then you MUST stick with the XML request writer.  The binary format changed in 3.x, and the two javabin versions are entirely incompatible.

Using the ConcurrentUpdateSolrClient

When implementing java applications that will be bulk loading a lot of documents at once, ConcurrentUpdateSolrClient is an alternative to consider instead of using HttpSolrClient. The ConcurrentUpdateSolrClient buffers all added documents and writes them into open HTTP connections. This class is thread safe. Although any SolrClient request can be made with this implementation, it is only recommended to use the ConcurrentUpdateSolrClient for /update requests.


The EmbeddedSolrServer class provides an implementation of the SolrClient client API talking directly to an micro-instance of Solr running directly in your Java application. This embedded approach is not recommended in most cases and fairly limited in the set of features it supports – in particular it can not be used with SolrCloud or Index Replication. EmbeddedSolrServer exists primarily to help facilitate testing.

For information on how to use EmbeddedSolrServer please review the SolrJ JUnit tests in the org.apache.solr.client.solrj.embedded package of the Solr source release.


  • No labels


  1. We can add an example for CloudSolrServer at this page.

  2. Typo (there is no such thing as ConcurrentHttpSolrServer) : "… The ConcurrentHttpSolrServer buffers all added documents ..." => " … The ConcurrentUpdateSolrServer buffers all added documents ..."

      1. What about concurrent/batch updates using SolrCloud ?
        Does the ConcurrentUpdateSolrServer connect via zokeeperHostString ? 

  3. solrcloud+zookeeper集群下,一般建议什么情况下用CloudSolrServer?什么情况下用LBHttpSolrServer?

    1. questions about using solr/solrj should be sent to the solr-user@lucene mailing list.

      Commenting on these pages should be focused on questions/comments/suggestions on the specific wording of documentation.

      (allthough FYI: not a lot of people on the solr-user mailing list – or who read/response to documentation suggestions - read/understand chinese, so if you can translate your questions to english before sending them you are more likely to get helpful responses)

  4. Three of the links in the first paragraph (SolrClient,  HttpSolrClient, and CloudSolrClient) are dead, leading to 404 errors.  

    1. Looks like the javadoc base URL hasn't been updated to 5.0.0 yet, they're still pointing to 4.10.0.  Those particular classes do not exist in 4.10, they will be new with 5.0 when it is released.

      Thanks for the heads up.  Because 5.0 javadocs don't exist yet, I don't think we want to update the javadoc base URL yet ... doing so will break all javadoc URLs in the entire guide, which would be a lot worse than having a few links like these not work.


  5. I think the HttpSolrClient sample code should use /solr/collection1 for the URL path, or maybe /solr/techproducts to reflect a core name used with the new bin/solr command.

    As I understand it, the legacy solr.xml format goes away in 5.0, taking defaultCoreName with it, and making the default core name hardcoded to collection1.  If my understanding is correct, any core name besides collection1 must be specified when creating the HttpSolrClient.

    1. i updated the URLs to include techproducts to be consistent with how the rest of the usage is already written.

      it's important to note though that that's just one way to use HttpSolrClient, where the client is tied to a specific collection.  Alternatively you can leave the HttpSolrClient init URL pointed t the root URL of your Solr instance, and use SolrRequest.setPath("/techproducts/myhandlername"); to control which collection (and handler) the request goes to ... but since we didn't already have any examples of that sort of thing, i left it alone

  6. The request handler path explanation uses some super-legacy method (setting 'qt' by name).

    It might be better to use SolrQuery.setRequestHandler() in the example if possible. I can see that behind the scenes it also temporarily uses qt parameter as storage. However, being explicit about this is quite confusing, especially when combined with a long legacy explanation in solrconfig.xml and the fact that the legacy setup is actually turned off.

  7. Helping someone on IRC, I have realized that we don't include all the logging jars that a developer will need in dist/solrj-lib, and there's not a lot of detail on jars at all.

  8. Why does SolrClient solrClient = new HttpSolrClient(url ); not work in Android despite having all the jar files as recommended above. It throws runtime exception:

    AndroidRuntime:  Caused by: java.lang.VerifyError: Rejecting class org.apache.solr.client.solrj.impl.HttpClientUtil because it failed compile-time verification (declaration of 'org.apache.solr.client.solrj.impl.HttpClientUtil' appears in /data/app/

    1. As far as I know, SolrJ will work in Android, although it is a bad idea to expose a Solr installation on the Internet, so I don't know how useful it will be in practice.

      I would mention this exception on a forum, mailing list, or other support avenue for Android development, to determine whether your project is correct.  If they believe that there is a bug in SolrJ that is causing this, then please feel free to bring it up on the Solr mailing list.

      1. I will follow your advice. I am making Solr temporarily available for research purpose behind a proxy once am done will sort other means. Thanks Shawn

  9. I am very new to Solr/SolrJ. I want to get suggestions for my query, to do so I have created one request handler called "suggest" (I am using following link as reference : Suggester#LookupImplementations). It is providing the correct output, but in beans format, even if I have provided the parameter : query.set("wt", "json"). How do I get the response in JSON format or how do I convert the response in some POJO. I am able to do this successfully when I am using default request handler i.e. "select", it provides a response which I am able to convert into POJO as the response contains all same fields which I have in Solr schema. Please let me know if you require any additional information. Thank you in advance.

    1. The response in SolrJ objects will always be in NamedList, regardless of what wire transfer format you choose (the wt parameter).  For efficiency reasons, it's best to leave the format at the default, which is javabin.

      There are sugar methods and classes available, one of which is SpellCheckResponse.Suggestion:


      All the response sugar in SolrJ is using the NamedList<Object> object, which is somewhat like a Map, but with slightly different capabilities.  The NamedList can be retrieved from the response with the getResponse() method and explored directly.  This object contains the entire Solr response converted to POJOs like String, Integer, Date, etc.  If you do not know exactly what will be in the response, you can do a toString() on the NamedList and get a decent representation in String format.  One of the more useful methods on NamedList is findRecursive().

      If you want to get the actual text response in something like JSON or XML, you have the option of making HTTP calls directly with something like HttpClient.  At that point you will not be using SolrJ.  There may be a way in SolrJ to get the actual response back, but I am not familiar with it, because it is generally better to handle response objects directly, or retrieve the NamedList and dive down from there.

      1. Thank you Shawn for a good explanation, it showed me a path to reach the solution. We can cast the members of NamedList<Object> object to SimpleOrderedMap<Object>, elements of which can further be cast. I wanted to reach to ArrayList of actual suggestion terms. Thank you again.

  10. for the memories:

    CloudSolrClient.setParallelUpdates(boolean) enables sending document batches to shards in parallel, but it is still sequential in scope of a shard.

    Presumably, concurrent sending in scope of a shard can be enabled if CloudSolrClient is supplied with LBHttpSolrClient descendant, which overrides makeSolrClient(String) and creates ConcurrentUpdateSolrClient instead a plain HttpSolrClient 

  11. Do we information about with working with schema and DIH using SolrJ?

  12. Hi, I am using CloudSolrClient as mentioned to query from the external website. I have to set the proxy server and port through which it can connect.

    Could you kindly let me know how to set the proxy for the CloudSolrClient along with the url while creating the instance?


    I tried the following

    System.setProperty("http.proxyHost", proxyserver);
    System.setProperty("http.proxyPort", Integer.toString(proxyport));

    HttpHost proxy = new HttpHost(proxyserver, proxyport);
    RequestConfig defaultRequestConfig =
    RequestConfig.custom().setProxy(new HttpHost(proxyserver, proxyport)).build();

    HttpGet httpget = new HttpGet(baseUrl);


    HttpGet httpget = new HttpGet(baseUrl);

    HttpClientBuilder builder = HttpClientBuilder.create();

    CloseableHttpClient httpclient = builder.build();

    httpclient.execute(proxy, httpget);


     solrClient = new CloudSolrClient(baseUrl, httpclient);

    I could see the httpclient establishing the connection but when i pass the httpclient to CloudSolrClient i am getting the exception as java.net.UnknownHostException. It doesnt seem to use the property of the httpclient passed.


    Could you kindly let me know how to pass the proxydetails to the CloudSolrClient. Request you to kindly update this page also with the information to connect using proxy.


    1. First thing to say is that the comment section of this wiki is not the appropriate place for help requests. Please use the solr-user mailing list.


      I'm not sure why this isn't working. Please send a message to the mailing list – a lot more people will see it.

      The documentation update you have requested is not trivial, and is only one example of many things that can be done by creating the HttpClient object explicitly.

  13. Hi Team, 

    Is there any tuning parameters in using sorlj to upload huge documents, as it is resulting OutOfMemory of us. 

    Please share any documents for tuning solr indexing and usage of solrj

    Thanks in advance

    1. Please use the solr-user mailing list or the IRC channel for support.  Once there, we'll need logs from your SolrJ application as well as the Solr server.  The version of SolrJ and the version of Solr will be important to know.


      These comments are for the documentation – not support requests.

  14. Is there any way to set a timeout with a CloudSolrClient?

    1. Please use the mailing list or IRC channel for support requests.

      1. I figured since the answer should, IMO, be included on this page, I'd ask it here, but okay.

        Is there a way to subscribe to just responses to the questions I ask on the mailing list, or do I have to subscribe to every single message or none at all? I thought when I submitted a question I'd automatically get emails for a response, but I just checked the archives and saw a question I asked a week ago got a response.

        Also, it'd be good if this page actually included the mailing list address – solr-user@lucene.apache.org instead of just "solr-user@lucene". 

      2. Sorry for posting this here, but you seem to be in favor of the mailing list, so I figure you can probably answer these.

        Is there any way for me to respond to my own question in the mailing list? If I come up with the solution and would like to help others that might have the same/a similar question, it doesn't seem that there's a way to do that. Or if I want to elaborate on a question I've asked, can I do that somehow? And is there no way to respond to a topic without replying to the email you get if you're subscribed (and therefore, no way to reply to topics posted before you subscribed)?

        This is my first experience with a mailing list, and I'm just blown away that such a seemingly crippled form of support was ever thought of as a good idea.

        1. It's just email, unless you're accessing it through a subscribed forum like Nabble.

          Assuming that it's email, if you are receiving copies of your own messages (which you probably are), just reply to the message.  The default reply-to is the mailing list, so that's who your reply will be addressed to unless you change it.

  15. Some sample response format documentation would be wonderful, since the UpdateResponse is largely ambiguous. 

  16. Hi Team,


     I am trying to create an instance of SolrClient by using below code using zookeeper.


    String zkHostString = "localhost:2184";
    SolrClient solr = new CloudSolrClient.Builder().withZkHost(zkHostString).build();


    But it shows the error as follows.Can you please let me know what wrong I am doing.


    110 [main] INFO org.apache.solr.common.cloud.SolrZkClient - Using default ZkCredentialsProvider
    log4j:WARN No appenders could be found for logger (org.apache.zookeeper.ZooKeeper).
    log4j:WARN Please initialize the log4j system properly.
    145 [main] INFO org.apache.solr.common.cloud.ConnectionManager - Waiting for client to connect to ZooKeeper
    org.apache.solr.common.SolrException: java.util.concurrent.TimeoutException: Could not connect to ZooKeeper localhost:2184 within 10000 ms
    at org.apache.solr.common.cloud.SolrZkClient.<init>(SolrZkClient.java:181)
    at org.apache.solr.common.cloud.SolrZkClient.<init>(SolrZkClient.java:115)
    at org.apache.solr.common.cloud.SolrZkClient.<init>(SolrZkClient.java:105)
    at org.apache.solr.common.cloud.ZkStateReader.<init>(ZkStateReader.java:227)
    at org.apache.solr.client.solrj.impl.CloudSolrClient.connect(CloudSolrClient.java:555)
    at org.apache.solr.client.solrj.impl.CloudSolrClient.requestWithRetryOnStaleState(CloudSolrClient.java:1003)
    at org.apache.solr.client.solrj.impl.CloudSolrClient.request(CloudSolrClient.java:992)
    at org.apache.solr.client.solrj.SolrRequest.process(SolrRequest.java:149)
    at org.apache.solr.client.solrj.SolrClient.query(SolrClient.java:942)
    at org.apache.solr.client.solrj.SolrClient.query(SolrClient.java:957)
    at org.solr.test.SolrCloud.main(SolrCloud.java:45)
    Caused by: java.util.concurrent.TimeoutException: Could not connect to ZooKeeper localhost:2184 within 10000 ms
    at org.apache.solr.common.cloud.ConnectionManager.waitForConnected(ConnectionManager.java:235)
    at org.apache.solr.common.cloud.SolrZkClient.<init>(SolrZkClient.java:173)
    ... 10 more


    1. Well as it says, "Could not connect to ZooKeeper localhost:2184", it doesn't seem to be able to connect to ZooKeeper. 

      I've always known ZK to use port 2181 by default. Did you change it to 2184? If not, I'd try changing your code to

  17. I  am getting the following exception while creating a Solr client. Any help is appreciated
    =====This is code snipper to create a SolrClient===============
    public void populate (String args) throws IOException, SolrServerException  {
        String urlString =  "http://localhost:8983/solr";
        SolrClient  server = new HttpSolrClient.Builder(urlString).build();
    Exception in thread "main" java.lang.VerifyError: Bad return type
    Exception Details:
        org/apache/solr/client/solrj/impl/HttpClientUtil.createClient(Lorg/apache/solr/common/params/SolrParams;)Lorg/apache/http/impl/client/CloseableHttpClient; @57: areturn
        Type 'org/apache/http/impl/client/SystemDefaultHttpClient' (current frame, stack[0]) is not assignable to 'org/apache/http/impl/client/CloseableHttpClient' (from method signature)
      Current Frame:
        bci: @57
        flags: { }
        locals: { 'org/apache/solr/common/params/SolrParams', 'org/apache/solr/common/params/ModifiableSolrParams', 'org/apache/http/impl/client/SystemDefaultHttpClient' }
        stack: { 'org/apache/http/impl/client/SystemDefaultHttpClient' }
        0x0000000: bb00 0359 2ab7 0004 4cb2 0005 b900 0601
        0x0000010: 0099 001e b200 05bb 0007 59b7 0008 1209
        0x0000020: b600 0a2b b600 0bb6 000c b900 0d02 00b8
        0x0000030: 000e 4d2c 2bb8 000f 2cb0               
      Stackmap Table:
     at org.apache.solr.client.solrj.impl.HttpSolrClient.<init>(HttpSolrClient.java:209)
     at org.apache.solr.client.solrj.impl.HttpSolrClient$Builder.build(HttpSolrClient.java:874)
     at PDFParseExtract.populate(PDFParseExtract.java:60)
     at PDFParseExtract.main(PDFParseExtract.java:53)
    1. Hi Tariq,

            The primary problem seems to be:


          Type 'org/apache/http/impl/client/SystemDefaultHttpClient' (current frame, stack[0]) is not assignable to 'org/apache/http/impl/client/CloseableHttpClient' (from method signature)  
         Try using  org.apache.http.impl.client.CloseableHttpClient   instead.  That works fine for me. 
    2. Kevin has highlighted the issue, and I have already responded on the question you asked on the mailing list.  The mailing list is the correct place for this discussion, not these comments.

  18. I have done the solr cloud setup for hybris 6.3 but when i run the indexing I am getting this error 


    org.apache.solr.client.solrj.impl.HttpSolrClient$RemoteSolrException: Error from server at http://localhost:8983/solr/master_Product_default_shard1_replica1: Invalid version (expected 2, but 116) or the data in not in 'javabin' format
    org.apache.solr.client.solrj.impl.HttpSolrClient.executeMethod(HttpSolrClient.java:590) ~[solr-solrj-6.1.0.jar:6.1.0 4726c5b2d2efa9ba160b608d46a977d0a6b83f94 - jpountz - 2016-06-13 09:46:59]
    org.apache.solr.client.solrj.impl.HttpSolrClient.request(HttpSolrClient.java:259) ~[solr-solrj-6.1.0.jar:6.1.0 4726c5b2d2efa9ba160b608d46a977d0a6b83f94 - jpountz - 2016-06-13 09:46:59].


    Thanks in Advance!!!



    1. These comments are for reporting problems with the documentation, not for getting support.  Please use the mailing list or the IRC channel for help.


      On the mailing or IRC channel, please include more details.  We don't know anything about hybris.  You might need to get help from them for this issue.