Solr supports an alternate request API which accepts requests composed in part or entirely of JSON objects.
This alternate API can be preferable in some situations, where its increased readability and flexibility make it easier to use than the entirely query-parameter driven alternative.
There is also some functionality which can only be accessed through this JSON request API, such as much of the analytics capabilities of JSON Faceting
Building JSON Requests
The core of the JSON Request API is its ability to specify request parameters as JSON in the request body, as shown by the example below:
JSON objects are typically sent in the request body, but they can also be sent as values for json-prefixed query parameters. This can be used to override or supplement values specified in the request body. For example the query parameter json.limit=5 will override any limit value provided in the JSON request body. You can also specify the entire JSON body in a single json query parameter, as shown in the example below:
If multiple json parameters are provided in a single request, Solr attempts to merge the parameter values together before processing the request.
The JSON Request API has several properties (filter, fields, etc) which accept multiple values. During the merging process, all values for these "multivalued" properties are retained. Many properties though (query, limit, etc.) can have only a single value. When multiple parameter values conflict with one another a single value is chosen based on the following precedence rules:
Traditional query parameters (q, rows, etc.) take first precedence and are used over any other specified values.
json-prefixed query parameters are considered next.
Values specified in the JSON request body have the lowest precedence and are only used if specified nowhere else.
This layered merging gives the best of both worlds. Requests can be specified using readable, structured JSON. But users also have the flexibility to separate out parts of the request that change often. This can be seen at work in the following example, which combines json.-style parameters to override and supplement values found in the main JSON body.
curl http://localhost:8983/solr/techproducts/query -d '
"limit": 5, // this single-valued parameter was overwritten.
"filter": ["inStock:true","cat:electronics"] // this multi-valued parameter was appended to.
Solr uses the Noggit JSON parser in its request API. Noggit is capable of more relaxed JSON parsing, and allows a number of deviations from the JSON standard:
bare words can be left unquoted
single line comments can be inserted using either // or #
Multi-line ("C style") comments can be inserted using /* and */
strings can be single-quoted
special characters can be backslash-escaped
trailing (extra) commas are silently ignored (e.g., [9,4,3,])
nbsp (non-break space, \u00a0) is treated as whitespace.
If you want to see what your merged/parsed JSON looks like, you can turn on debugging (debug=timing), and it will come back under the "json" key along with the other debugging information.
Note that debug=true and debugQuery=true can often have significant performance implications, and should be reserved for debugging. Also note that debug=query has no effect on JSON facets in SolrCloud.