PUT /v1/config/query/(default|{name})

Summary

Create or replace named query options.

Response

Upon success, MarkLogic Server returns status 201 (Created) or 204 (Updated).

If the payload is invalid, MarkLogic Server responds with status 400 by default. However, validation may be disabled. For details, see /config/properties.

Required Privileges

http://marklogic.com/xdmp/privileges/rest-admin

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

For more details, see Configuring Query Options in the REST Application Developer's Guide.

The request body must be a valid search:options node, expressed in either XML or JSON, depending upon the request Content-Type header or format parameter. See the Usage Notes, below.

By default, options are validated. Options validation can be disabled using the /config/properties service.

If the named options do not exist, they are created. If the named options exist, the options in the request body replace the existing query options.

If {name} is default, the default search options are modified.

Query options are expressed as a multi-level JSON or XML structure. The following list is brief summary of the top level option XML elements or JSON objects. For details, see Search Customization Using Query Options in the Search Developer's Guide and Appendix: Query Options Reference in the Search Developer's Guide.

additional-query

Additional serialized queries that are AND'd with any string or structured query supplied to a request.

concurrency-level

The maximum number of threads used to resolve facets.

constraint

Constraints used to control the search and faceting.

debug

Activate debugging mode.

default-suggestion-source

Define content to be used as the default source of search suggestions.

extract-metadata

Specify data to return in the metadata section of the response output.

forest

One or more forest ids.

fragment-scope

The global fragment scope over which to search, either properties or documents.

grammar

Specify a custom search grammar. The default grammar defines "Google-style" parsing.

operator

A list of state elements, each representing a unique runtime configuration option.

page-length

The number of results per page. The default is 10.

quality-weight

A weighting factor to use in the query. The default is 1.0.

return-aggregates

Whether to include results from builtin or user-defined aggregate functions in the search response. Default: true.

return-constraints

Whether to include the original constraint definitions in the results. Default: false.

return-facets

Whether to include resolved facets in the results. Default: true.

return-frequencies

Whether to include value frequencies in range indexes and lexicons in the results. Default: true.

return-metrics

Whether to include statistics in the results. Default: true.

return-plan

Whether to include xdmp:plan output in the results. Default: false.

return-qtext

Whether to include the original query text in the results. Default: true.

return-query

Whether to include the XML query representation in the results. Default: false.

return-results

Whether to include search results in the output. Default: true.

return-similar

Whether to include a list of URLS of similar documents with each search result. Default: false.

return-values

Whether to include values from range indexes and lexicons in the results. Default: true.

search-option

For advanced usrs. Additional options to pass in, such as filtered, unfiltered, and score-logtfidf. Default: No additional options.

searchable-expression

An expression to search. Whatever expression is specified is return from the search. Due to security and performance considerations, beginning in MarkLogic 9.0-10, the searchable-expression property/element in query options is deprecated. In addition, in 10.0-2 and moving forward, the searchable-expression requires the eval-search-string privilege.

sort-order

Set the default sort order.

suggestion-source

A constraint source to override a named constraint when using search:suggest.

term

Specifies handling of empty searches and controls option for how individual are represented when parsing the search.

transform-results

Specifies a function for processing search results to create snippet output.

tuples

Specifies constraints for finding value range index and lexicon co-ocurrences.

values

Specifies constraints for finding values in range indexes and lexicons.

Example

$ curl --anyauth --user user:password -T './options2' -i \
  -H "Content-type:application/xml" \
  http://localhost:8000/v1/config/query/scene

==> MarkLogic Server creates or updates the query options named "scene".
    The response includes the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: close