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 table below lists the most common settings for the wt parameter.

wt Parameter Setting Response Writer Selected

csv

CSVResponseWriter

geojson

GeoJSONResponseWriter

javabin

BinaryResponseWriter

json

JSONResponseWriter

php

PHPResponseWriter

phps

PHPSerializedResponseWriter

python

PythonResponseWriter

ruby

RubyResponseWriter

smile

SmileResponseWriter

velocity

VelocityResponseWriter

xlsx

XLSXResponseWriter

xml

XMLResponseWriter

xslt

XSLTResponseWriter

The 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.

The version Parameter

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.

Currently supported version values are:

XML Version Notes

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.

The stylesheet Parameter

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.

The indent Parameter

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.

The 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.

tr Parameter

The XSLT Response Writer accepts one parameter: the tr parameter, which 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"/>

Configuration

The example below, from the sample_techproducts_configs config set 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="org.apache.solr.request.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.

JSON Response Writer

A very commonly used Response Writer is the JsonResponseWriter, which formats output in JavaScript Object Notation (JSON), a lightweight data interchange format specified in specified in RFC 4627. Setting the wt parameter to json invokes this Response Writer.

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

{
  "responseHeader":{
    "zkConnected":true,
    "status":0,
    "QTime":7,
    "params":{
      "q":"id:VS1GB400C3",
      "indent":"on",
      "wt":"json"}},
  "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” configuration:

<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>

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.

json.nl Parameter setting Example output for NamedList("a"=1, "bar"="foo", null=3, null=null) Description

flat (the default)

["a",1, "bar","foo", null,3, null,null]

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

map

{"a":1, "bar":"foo", "":3, "":null}

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.

arrarr

[["a",1], ["bar","foo"], [null,3], [null,null]]

NamedList is represented as an array of two element arrays.

arrmap

[{"a":1}, {"b":2}, 3, null]

NamedList is represented as an array of JSON objects.

arrntv

[{"name":"a","type":"int","value":1}, {"name":"bar","type":"str","value":"foo"}, {"name":null,"type":"int","value":3}, {"name":null,"type":"null","value":null}]

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

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.

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 aspseudo-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

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

Velocity Response Writer

The VelocityResponseWriter processes the Solr response and request context through Apache Velocity templating.

See Velocity Response Writer section for details.

Smile Response Writer

The Smile format is a JSON-compatible binary format, described in detail here: http://wiki.fasterxml.com/SmileFormat.

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 contrib 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 contrib/extraction/lib/*.jar server/solr-webapp/webapp/WEB-INF/lib/
cp dist/solr-cell-6.3.0.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.

©2017 Apache Software Foundation. All rights reserved.
Site Version: 6.6
Site last generated: 2017-06-09

Apache Solr