Skip to content

Named Query Management

Jump to bottom
isubiker edited this page Dec 24, 2011 · 7 revisions

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

Discussion

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.

Clone this wiki locally