Query Stages API

The Query Stages API provides endpoints to: * manage query stage instances. * list query stage configuration properties * test processing on a set of queries

List Query Stages or Properties of an Query Stage Type

The path for this request is one of:

api/apollo/query-stages/schema

api/apollo/query-stages/schema/<type>

When no type name is specified, a GET request returns a listing of all configuration properties for all query pipeline stages. When a type name is specified, a GET request returns the properties for that type.

This provides a type template, listing the name and type information of all properties, if they are required, and what the default value is (if any).

List a Query Stage

The path for this request is:

api/apollo/query-stages/instances/<stageId>

where <stageId> is the name of an query stage instance.

If the pipeline stage instance is specified, it returns the properties for that stage, else it returns the currently configured properties for all query pipeline stage instances.

If no query stage instances have been created, this request returns the empty list "[ ]".

Create, Update, or Delete a Query Stage

The path for this request is:

api/apollo/query-stages/instances/<stageId>

where <stageId> is the name of a query stage instance.

  • POST - create a new stage. Returns a listing of the specified properties. No <stageId> path parameter is necessary; the information in the POST body to determine the stageId.

  • PUT - update an existing stage. Returns a listing of the specified properties.

  • DELETE - remove an query pipeline stage.

Send a Test Query through a Query Stage

`GET /api/apollo/query-stages/instances/stageId/test/?key=value `

POST /api/apollo/query-stages/test? `key=value`

The path for this request is:

api/apollo/query-stages/instances/<stageId>/test?<key=value>

where <stageId> is the name of a query stage instance and <collectionName> is the name of an existing collection and <key=value> is a valid Solr query.

A GET request will send the defined key=value pair through the defined stage.

A POST request allows you to define a stage and test it on a query to see the possible response.

Input

A POST request takes a query stage specification as a JSON object.

Note that when using the POST request to test a stage that does not yet exist, the stage is not created, even if the response is successful.

Output

The output will be a query response in JSON format, or an error if the stage was not defined correctly.

Examples

Get the properties for the "apply-defaults" type:

REQUEST

curl -u user:pass http://localhost:8764/api/apollo/query-stages/schema/set-params

RESPONSE

{
  "type" : "object",
  "title" : "Additional Query Parameters",
  "description" : "This stage allows you to set, append, and remove additional query parameters",
  "properties" : {
    "skip" : {
      "type" : "boolean",
      "title" : "Skip This Stage",
      "description" : "Set to true to skip this stage.",
      "default" : false,
      "hints" : [ "advanced" ]
    },
    "label" : {
      "type" : "string",
      "title" : "Label",
      "description" : "A unique label for this stage.",
      "hints" : [ "advanced" ],
      "maxLength" : 255
    },
    "condition" : {
      "type" : "string",
      "title" : "Condition",
      "description" : "Define a conditional script that must result in true or false. This can be used to determine if the stage should process or not.",
      "hints" : [ "code", "javascript", "advanced" ]
    },
    "params" : {
      "type" : "array",
      "title" : "Parameters and Values",
      "items" : {
        "type" : "object",
        "required" : [ "key" ],
        "properties" : {
          "key" : {
            "type" : "string",
            "title" : "Parameter Name"
          },
          "value" : {
            "type" : "string",
            "title" : "Parameter Value"
          },
          "policy" : {
            "type" : "string",
            "title" : "Update Policy",
            "enum" : [ "replace", "append", "remove", "default" ],
            "default" : "append"
          }
        }
      }
    }
  },
  "category" : "Advanced",
  "categoryPriority" : 2

See all defined query pipeline stages, regardless of type:

REQUEST

curl -u user:pass http://localhost:8764/api/apollo/query-stages/instances

RESPONSE

[{
  "type" : "query-logging",
  "id" : "detailed-logging",
  "detailed" : true,
  "skip" : false,
  "label" : "detailed-query-logging",
}]

Add a new query stage:

REQUEST

curl -u user:pass -X POST -H 'Content-type: application/json' -d'{ "type" : "query-logging", "id" : "detailed-logging", "detailed" : true }' http://localhost:8764/api/apollo/query-stages/instances

RESPONSE

 {
  "type" : "query-logging",
  "id" : "detailed-logging",
  "detailed" : true,
  "skip" : false,
  "label" : "query-logging"
}

Update a query stage:

REQUEST

curl -u user:pass -X PUT -H 'Content-type: application/json' -d'{ "type" : "query-logging", "id" : "detailed-logging", "detailed" : true, "label" : "detailed-query-logging" }' http://localhost:8764/api/apollo/query-stages/instances/detailed-logging

RESPONSE

{
  "type" : "query-logging",
  "id" : "detailed-logging",
  "detailed" : true,
  "skip" : false,
  "label" : "detailed-query-logging",
}

Note that all required elements must be included in the update.

Delete a query stage:

REQUEST

curl -u user:pass -X DELETE http://localhost:8764/api/apollo/query-stages/instances/detailed-logging

No response is returned. To check that the stage is no longer defined, list all query stage instances.

Test that a set-params stage defines properties correctly:

REQUEST

curl -u user:pass -X POST -H 'Content-type: application/json' -d '{"type":"set-params", "params":[{"key":"rows", "value":"2", "policy":"append"}]}' http://localhost:8764/api/apollo/query-stages/solr/test?q=*:*

RESPONSE

{
  "request" : {
    "headers" : {
      "User-Agent" : [ "curl/7.30.0" ],
      "Content-Type" : [ "application/json" ],
      "Accept" : [ "*/*" ],
      "Host" : [ "localhost:8764" ],
      "Content-Length" : [ "80" ]
    },
    "params" : {
      "q" : [ "*:*" ],
      "rows" : [ "2" ]
    }
  },
  "response" : null,
  "totalTime" : 0
}