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

Parameter Substitution or Macro Expansion is a request templating mechanism that works for search requests across all request parameters, including any JSON body that may be passed via the JSON Request API.

The macro expansion is done at the same point in time that default parameters are applied (i.e. when the request reaches the correct request handler). This means that request handler defaults, appends, and invariants configured for the handler may reference request parameters, and vice-versa.

Here’s a very simple example of parameterizing a range query in lucene/solr syntax:

One can also specify default values:

Substitutions can themselves contain further macro expansions:

If you want to disable macro expansion, simply pass expandMacros=false as a request parameter.


This page was adapted from http://yonik.com/solr-query-parameter-substitution/


  • No labels


  1. This is kind of a hidden feature. Is this not ready to go in?  Although this is fine as a stand-alone page, I feel it would be useful to reference this on other pages, such as local-params page even thought this isn't strictly local-params.

    1. +1 to making this page part of the published Solr Ref Guide - how about it becoming a sub-page of Query Syntax and Parsing say?

      1. I don't know much about this feature, is this page complete? 

        I think at the time this page was written, it was considered part of the JSON Request API, which has never been added to the Ref Guide because the page was mostly a copy of Yonik's blog post and I'm not sure it's ready to publish (e.g., it does not cover all available params or indicate where to find information on params not covered, does not indicate limitations, hasn't been kept up to date with changes in the past 1.5 years, etc.).

        If this feature isn't primarily (or doesn't need to be) tied to the JSON Request API documentation, then +1 also for publishing it. Christine's suggestion for placement feels right to me also.

        edit: I would also suggest that related items from the TODO list that weren't done in previous releases should be added or fixed on the page before it's published.