Named Query Management

isubiker edited this page Dec 24, 2011 · 7 revisions
Clone this wiki locally

Named Query Management

When an extremely complex and common query is used frequently, storing that query can provide significant performance improvements. Stored queries can be submitted as either a string query or a structured query.

Store a named query

Stores a query under the given name. If a query already exists with this name, an error is thrown.

A word about named query names

Query names are allowed to be alpha numeric. All named queries can be used in structured queries, but if the name contains a colon it may also be used in string queries. The prefix before the colon must first be registered via the named query prefix management endpoint.

Named query prefix use case

A user could store a named query for every zip code in the United States. Each one of these named queries could start with "zip:" and in a string query a user could search for zip:90210 to search around Beverly Hills.

Endpoint details

  • Endpoint: /namedquery/<query-name>
  • Request type: POST
  • Parameters:
    • description (optional) - A string to summarize or describe the named query
    • stringQuery - The string query to save
    • structuredQuery - The structured query to save
    • collection (optional, multiple) - A collection to place the stored query in
    • property (optional, multiple) - Must follow a : pattern where the key is alphanumeric, starts with a letter and can contain underscores and dashes
    • permission (optional, multiple) - Must follow a : pattern where capability is one of read or update
  • Returns:
    • If the named query was successfully stored, a 200 is returned with an empty response body
    • If there was an error parsing the query, a 400 is returned

Fetching a named query by its name

Returns the named query specified in the request.

  • Endpoint: /namedquery/<query-name>
  • Request type: GET

Search for named queries

Returns named queries that match the provided parameters. To retrieve all the named queries, don't supply any parameters.

  • Endpoint: /namedquery
  • Request type: GET
  • Parameters:
    • collection (optional) - Fetch queries in the given collection
    • property (optional) - A property name to query on (must supply a value parameter as well)
    • value (optional) - The value of a property to query on (must supply a property parameter as well)
    • matchingDoc (optional) - Fetch queries that match the document at the given URI (very powerful feature!)
    • start (optional, default: 1) - Used to paginate through results
    • length (optional) - Number of results to return
    • outputFormat (optional, default: json) - Output format for the results

Delete a named query

Removes the named query.

  • Endpoint: /namedquery/<query-name>
  • Request type: DELETE
  • Returns:
    • If the named query was deleted, a 200 is returned with an empty response body.
    • If the named query does not exist, a 404 is returned


Might be nice to be able to POST a new document and see which queries would match it, without first saving the document to the database. Same by specifying a URI too.

Might be nice to have a bulk delete, where you delete queries matching a constraint.