Response Writers

A Response Writer generates the formatted response of a search.

Solr supports a variety of Response Writers to ensure that query responses can be parsed by the appropriate language or application.

The wt parameter selects the Response Writer to be used. The list below describe shows the most common settings for the wt parameter, with links to further sections that discuss them in more detail.

JSON Response Writer

The default Solr Response Writer is the JsonResponseWriter, which formats output in JavaScript Object Notation (JSON), a lightweight data interchange format specified in RFC 4627. The default response writer is used when:

  • the wt parameter is not specified in the request, or

  • a non-existent response writer is specified.

Here is a sample response for a simple query like q=id:VS1GB400C3:

{
  "responseHeader":{
    "zkConnected":true,
    "status":0,
    "QTime":7,
    "params":{
      "q":"id:VS1GB400C3"}},
  "response":{"numFound":1,"start":0,"maxScore":2.3025851,"docs":[
      {
        "id":"VS1GB400C3",
        "name":["CORSAIR ValueSelect 1GB 184-Pin DDR SDRAM Unbuffered DDR 400 (PC 3200) System Memory - Retail"],
        "manu":["Corsair Microsystems Inc."],
        "manu_id_s":"corsair",
        "cat":["electronics",
          "memory"],
        "price":[74.99],
        "popularity":[7],
        "inStock":[true],
        "store":["37.7752,-100.0232"],
        "manufacturedate_dt":"2006-02-13T15:26:37Z",
        "payloads":["electronics|4.0 memory|2.0"],
        "_version_":1549728120626479104}]
  }}

The default mime type for the JSON writer is application/json, however this can be overridden in the solrconfig.xml - such as in this example from the "techproducts" configset:

<queryResponseWriter name="json" class="solr.JSONResponseWriter">
  <!-- For the purposes of the tutorial, JSON response are written as
       plain text so that it's easy to read in *any* browser.
       If you are building applications that consume JSON, just remove
       this override to get the default "application/json" mime type.
    -->
  <str name="content-type">text/plain</str>
</queryResponseWriter>
If you are using the JSON formatted response with JSONP to query across boundaries, having Solr respond with text/plain mime type when the browser expects application/json will trigger the browser to block the request.

JSON-Specific Parameters

json.nl

This parameter controls the output format of NamedLists, where order is more important than access by name. NamedList is currently used for field faceting data.

The json.nl parameter takes the following values:

flat

The default. NamedList is represented as a flat array, alternating names and values.

With input of NamedList("a"=1, "bar"="foo", null=3, null=null), the output would be ["a",1, "bar","foo", null,3, null,null].

map

NamedList is represented as a JSON object. Although this is the simplest mapping, a NamedList can have optional keys, repeated keys, and preserves order. Using a JSON object (essentially a map or hash) for a NamedList results in the loss of some information.

With input of NamedList("a"=1, "bar"="foo", null=3, null=null), the output would be {"a":1, "bar":"foo", "":3, "":null}.

arrarr

NamedList is represented as an array of two element arrays.

With input of NamedList("a"=1, "bar"="foo", null=3, null=null), the output would be [["a",1], ["bar","foo"], [null,3], [null,null]].

arrmap

NamedList is represented as an array of JSON objects.

With input of NamedList("a"=1, "bar"="foo", null=3, null=null), the output would be [{"a":1}, {"b":2}, 3, null].

arrntv

NamedList is represented as an array of Name Type Value JSON objects.

With input of NamedList("a"=1, "bar"="foo", null=3, null=null), the output would be [{"name":"a","type":"int","value":1}, {"name":"bar","type":"str","value":"foo"}, {"name":null,"type":"int","value":3}, {"name":null,"type":"null","value":null}].

json.wrf

json.wrf=function adds a wrapper-function around the JSON response, useful in AJAX with dynamic script tags for specifying a JavaScript callback function.

Standard XML Response Writer

The XML Response Writer is the most general purpose and reusable Response Writer currently included with Solr. It is the format used in most discussions and documentation about the response of Solr queries.

Note that the XSLT Response Writer can be used to convert the XML produced by this writer to other vocabularies or text-based formats.

The behavior of the XML Response Writer can be driven by the following query parameters.

version

Optional

Default: 2.2

The version parameter determines the XML protocol used in the response. Clients are strongly encouraged to always specify the protocol version, so as to ensure that the format of the response they receive does not change unexpectedly if the Solr server is upgraded and a new default format is introduced.

The only currently supported version value is 2.2. The format of the responseHeader changed to use the same <lst> structure as the rest of the response.

The default value is the latest supported.

stylesheet

Optional

Default: none

The stylesheet parameter can be used to direct Solr to include a <?xml-stylesheet type="text/xsl" href="…​"?> declaration in the XML response it returns.

The default behavior is not to return any stylesheet declaration at all.

Use of the stylesheet parameter is discouraged, as there is currently no way to specify external stylesheets, and no stylesheets are provided in the Solr distributions. This is a legacy parameter, which may be developed further in a future release.
indent

Optional

Default: none

If the indent parameter is used, and has a non-blank value, then Solr will make some attempts at indenting its XML response to make it more readable by humans.

The default behavior is not to indent.

XSLT Response Writer

The XSLT Response Writer applies an XML stylesheet to output. It can be used for tasks such as formatting results for an RSS feed.

This response writer is part of the scripting module. Since it is a module, it requires configuration before it can be used.

The XSLT Response Writer accepts one parameter:

tr

Optional

Default: none

Identifies the XML transformation to use. The transformation must be found in the Solr conf/xslt directory.

The Content-Type of the response is set according to the <xsl:output> statement in the XSLT transform, for example: <xsl:output media-type="text/html"/>

XSLT Configuration

The example below, from the sample_techproducts_configs configset in the Solr distribution, shows how the XSLT Response Writer is configured.

<!--
  Changes to XSLT transforms are taken into account
  every xsltCacheLifetimeSeconds at most.
-->
<queryResponseWriter name="xslt"
                     class="solr.scripting.xslt.XSLTResponseWriter">
  <int name="xsltCacheLifetimeSeconds">5</int>
</queryResponseWriter>

A value of 5 for xsltCacheLifetimeSeconds is good for development, to see XSLT changes quickly. For production you probably want a much higher value.

XSLT Writer Example

http://localhost:8983/solr/techproducts/select?q=ipod&fl=id,cat,name,popularity,price,score&wt=xslt&tr=example_rss.xsl transforms the results into a RSS feed:

<rss version="2.0">
  <channel>
    <title>Example Solr RSS 2.0 Feed</title>
    <link>http://localhost:8983/solr</link>
    <description>
      This has been formatted by the sample "example_rss.xsl" transform - use your own XSLT to get a nicer RSS feed.
    </description>
    <language>en-us</language>
    <docs>http://localhost:8983/solr</docs>
    <item>
      <title>iPod &amp; iPod Mini USB 2.0 Cable</title>
      <link>
        http://localhost:8983/solr/select?q=id:IW-02
      </link>
      <description/>
      <pubDate/>
      <guid>
        http://localhost:8983/solr/select?q=id:IW-02
      </guid>
    </item>

The sample_techproducts_configs also includes example.xsl which generates a simplistic HTML page and example_atom.xsl that outputs in the Atom format.

updateXml.xsl can be used to convert the standard Solr XML output into the Solr XML add docs format! Indeed you could round trip your data via:

curl -o docs_formatted_as_solr_add.xml "http://localhost:8983/solr/techproducts/select?q=ipod&fl=id,cat,name,popularity,price,score&wt=xslt&tr=updateXml.xsl"
curl -X POST -H "Content-Type: text/xml" -d @docs_formatted_as_solr_add.xml "http://localhost:8983/solr/techproducts/update?commitWithin=1000&overwrite=true"

Lastly, the luke.xsl transformation demonstrates that you can apply very sophisticated transformations: http://localhost:8983/solr/techproducts/admin/luke?wt=xslt&tr=luke.xsl

Binary Response Writer

This is a custom binary format used by Solr for inter-node communication as well as client-server communication. SolrJ uses this as the default for indexing as well as querying. See Client APIs for more details.

GeoJSON Response Writer

Returns Solr results in GeoJSON augmented with Solr-specific JSON. To use this, set wt=geojson and geojson.field to the name of a spatial Solr field. Not all spatial fields types are supported, and you’ll get an error if you use an unsupported one.

Python Response Writer

Solr has an optional Python response format that extends its JSON output in the following ways to allow the response to be safely evaluated by the python interpreter:

  • true and false changed to True and False

  • Python unicode strings are used where needed

  • ASCII output (with unicode escapes) is used for less error-prone interoperability

  • newlines are escaped

  • null changed to None

PHP Response Writer and PHP Serialized Response Writer

Solr has a PHP response format that outputs an array (as PHP code) which can be evaluated. Setting the wt parameter to php invokes the PHP Response Writer.

Example usage:

$code = file_get_contents('http://localhost:8983/solr/techproducts/select?q=iPod&wt=php');
eval("$result = " . $code . ";");
print_r($result);

Solr also includes a PHP Serialized Response Writer that formats output in a serialized array. Setting the wt parameter to phps invokes the PHP Serialized Response Writer.

Example usage:

$serializedResult = file_get_contents('http://localhost:8983/solr/techproducts/select?q=iPod&wt=phps');
$result = unserialize($serializedResult);
print_r($result);

Ruby Response Writer

Solr has an optional Ruby response format that extends its JSON output in the following ways to allow the response to be safely evaluated by Ruby’s interpreter:

  • Ruby’s single quoted strings are used to prevent possible string exploits.

  • \ and ' are the only two characters escaped.

  • Unicode escapes are not used. Data is written as raw UTF-8.

  • nil used for null.

  • => is used as the key/value separator in maps.

Here is a simple example of how one may query Solr using the Ruby response format:

require 'net/http'
h = Net::HTTP.new('localhost', 8983)
hresp, data = h.get('/solr/techproducts/select?q=iPod&wt=ruby', nil)
rsp = eval(data)
puts 'number of matches = ' + rsp['response']['numFound'].to_s
#print out the name field for each returned document
rsp['response']['docs'].each { |doc| puts 'name field = ' + doc['name'\] }

CSV Response Writer

The CSV response writer returns a list of documents in comma-separated values (CSV) format. Other information that would normally be included in a response, such as facet information, is excluded.

The CSV response writer supports multi-valued fields, as well as pseudo-fields, and the output of this CSV format is compatible with Solr’s CSV update format.

CSV Parameters

These parameters specify the CSV format that will be returned. You can accept the default values or specify your own.

Parameter Default Value

csv.encapsulator

"

csv.escape

None

csv.separator

,

csv.header

Defaults to true. If false, Solr does not print the column headers.

csv.newline

\n

csv.null

Defaults to a zero length string. Use this parameter when a document has no value for a particular field.

Multi-Valued Field CSV Parameters

These parameters specify how multi-valued fields are encoded. Per-field overrides for these values can be done using f.<fieldname>.csv.separator=|.

Parameter Default Value

csv.mv.encapsulator

None

csv.mv.escape

\

csv.mv.separator

Defaults to the csv.separator value.

CSV Writer Example

http://localhost:8983/solr/techproducts/select?q=ipod&fl=id,cat,name,popularity,price,score&wt=csv returns:

id,cat,name,popularity,price,score
IW-02,"electronics,connector",iPod & iPod Mini USB 2.0 Cable,1,11.5,0.98867977
F8V7067-APL-KIT,"electronics,connector",Belkin Mobile Power Cord for iPod w/ Dock,1,19.95,0.6523595
MA147LL/A,"electronics,music",Apple 60 GB iPod with Video Playback Black,10,399.0,0.2446348

CBOR Response Writer

Solr supports CBOR response format which is more compact and fast. Use the wt=cbor parameter to get responses in CBOR.

If your client does not support the STRINGREF feature of CBOR, use wt=cbor&str_ref=false

Example Python program

save the following program as cbor_query.py

import cbor2
import json
import requests

// replace 'coll1' with your own collection name. And use appropriate query params
url = "http://localhost:8983/solr/coll1/select?q=*:*&wt=cbor"

# Make the HTTP request
response = requests.get(url, headers={"Accept": "application/cbor"})

# Check the response status
if response.status_code == requests.codes.ok:
    # Decode the CBOR response payload
    cbor_data = response.content
    json_data = cbor2.loads(cbor_data)

    # Dump the JSON data to a file
    with open("response.json", "w") as file:
        json.dump(json_data, file, indent=4)
    print("CBOR response payload dumped to response.json")
else:
    print("HTTP request failed with status code:", response.status_code)

Running the program

  1. Install Python

  2. Install the dependencies

    pip install requests cbor2

  3. Run the program

    python3 cbor_query.py

Smile Response Writer

The Smile format is a JSON-compatible binary format, described in detail here: https://en.wikipedia.org/wiki/Smile_(data_interchange_format)

XLSX Response Writer

Use this to get the response as a spreadsheet in the .xlsx (Microsoft Excel) format. It accepts parameters in the form colwidth.<field-name> and colname.<field-name> which helps you customize the column widths and column names.

This response writer has been added as part of the extraction library, and will only work if the extraction module is present in the server classpath. Defining the classpath with the lib directive is not sufficient. Instead, you will need to copy the necessary .jars to the Solr webapp’s lib directory manually. You can run these commands from your $SOLR_INSTALL directory:

cp modules/extraction/lib/*.jar server/solr-webapp/webapp/WEB-INF/lib/

Once the libraries are in place, you can add wt=xlsx to your request, and results will be returned as an XLSX sheet.