Commands

Overview

Commands are similar to parameters and provide access to all the same functionality that the parameters do, but they have some distinct advantages. Commands give the Search API one piece of information that direct parameters do not: the action being performed. When the API receives a request via parameters only, all it can do is interpret that request directly. The API must assume that the client has applied all search logic -- such as paging, did you mean (DYM), and facet paging -- correctly. When the API receives a request via a command, it has the information it needs to make some intelligent decisions about search logic.

Commands allow the Search API to provide uniform search logic to all clients across different platforms and implementations, without needing to distribute any client code. Using commands reduces client-side search logic and URL-manipulation code. This makes it easier to learn how to use the API, and keeps developers thinking about the business logic specific to their application rather than the internal implementation details of search logic. Commands are also more efficient because the server needs to parse and interpret the query string when it executes a search. This is a perfect time to apply search logic directly to the search, and doesn't require any additional parsing or assembly steps. If search logic is performed on the client side instead, then the client needs to perform the extra steps of parsing the query, applying logic and re-assembling a new query, before it is sent to the API.

Because commands are not guaranteed to be received by the API in any specific order, a natural order is applied to commands. Commands will always be executed in the order they appear in the Quick Reference list.

For more details on specific commands, see the Topics list on the left, and the Quick Reference list.


A Use Case

Assume that an end user does a search via two search terms, author and title. DYM is enabled on the original search, and there are several facet fields specified. When the user receives their results, they page through several facet-value options, click through to page two (for which the client simply sends a new request with s.pn=2, and forgets to disable DYM). Then the client clicks on a facet value to be applied as a filter.

At this point, the correct search logic would be to disable DYM, set page number to one, set all facet-field page numbers to one, and add the facet-value filter. A naive client implementation may simply append one new s.fvf parameter to the existing query string, and send that as the new query. This would appear wrong to the end user, since the result set would completely change, and they would not be directly entering anything that would need spelling correction, yet they could end up on page two of the result set, with spelling corrections coming back, drilled down to pages of facet fields that don't provide any limiting values for the current query.

If the client appended s.cmd=addFacetValueFilter(...) to the existing query instead of appending an s.fvf parameter directly, the API would have detected what the client was doing and applied all of the above-mentioned search logic automatically. The results would make sense to the end user, and the client wouldn't have to do any additional URL manipulation.

Characters may be escaped with the backslash ('\') character. For all command arguments, the following characters must be escaped: ,:\()${}.

Some special characters may need to be escaped for command arguments that hold Lucene-style query syntax. Characters that may need to be escaped include: +-&|!(){}[]^"~*?:\. Lucene special characters only need to be escaped if their special meaning was not intended. If Lucene escaping is needed it must be performed before regular argument escaping.

Example - Building queries via commands

Start with a blank query and ask for ContentType facet field:

  Append:

    s.cmd=addFacetField(ContentType,or,1,10)

  Which becomes:

    s.ff=ContentType%2Cor%2C1%2C10

Search for documents with author of Jonathan Swift and title of Gulliver's Travels:

  Append:

    s.cmd=addTextQuery(Author\:\(Jonathan+Swift\))+addTextQuery(Title\:\(Gulliver's+Travels\))

  To make:

    s.ff=ContentType%2Cor%2C1%2C10&s.cmd=addTextQuery(Author\:\(Jonathan+Swift\))+addTextQuery(Title\:\(Gulliver's+Travels\))

  Which becomes:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10

Move to next page:

  Append:

    s.cmd=nextPage()

  To make:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10&s.cmd=nextPage()

  Which becomes:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10&s.pn=2

Move to next facet-field page:

  Append:

    s.cmd=nextFacetPage(ContentType)

  To make:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10&s.pn=2&s.cmd=nextFacetPage(ContentType)

  Which becomes:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C2%2C10&s.pn=2

Apply ContentType facet-value filter of "Book":

  Append:

    s.cmd=addFacetValueFilter(ContentType,Book)

  To make:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C2%2C10&s.pn=2&s.cmd=addFacetValueFilter(ContentType,Book)

  Which becomes:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10&s.fvf=ContentType%2CBook%2C

Notice that s.pn is removed, resetting the paging, and the ContentType facet field has been reset to page 1.

Try It