It is often preferable to predefine available queries for an application, rather than rely on allowing dynamic Query by any account users (this can lead to higher costs if users, especially anonymous users, are allowed to make queries with any query condition). The customer can set some ACL on each saved query to control which account users (or anonymous) will be allowed to execute it.

Along with the SaveQuery request, the developer should send an xml schema containing all the details of the query to be saved.

Below is an example of the xml schema:

<query>
	<executeACL>all</executeACL>
	<store>testStore</store>
	<condition>
		<![CDATA[ firstName<string>={name}? AND lastName<string>={lastname} AND location<geospatial> WITHIN (0, 0, {dist}) ]]>
	</condition>
	<ftsQuery>test</ftsQuery>
	<returnedFields>
		<field>age</field>
		<field>apsdb.documentKey</field>
		<field>location</field>
		<field>distance(location,'1','1')</field>
	</returnedFields>
	<sort>
		<![CDATA[ lastName<string:ASC> ]]>
	</sort>
	<count>true</count>
	<aggregate>
		<expression>avg($age)</expression>
		<page>true</page>
		<global>false</global>
		<groupBy>
			<field>
				<name>age</name>
				<type>numeric</type>
			</field>
			<field>
				<name>lastName</name>
				<type>string</type>
			</field>
		</groupBy>
	</aggregate>
	<resultsPerPage>10</resultsPerPage>
	<forceCurrentSnapShot>true</forceCurrentSnapShot>
</query>

The following table explains each tag of the above xml schema:

Query Condition

The query "condition" syntax is the same for saved queries and dynamic queries except for the concept of condition's variables that will be explained here.

When writing the condition of a saved query, the fields' values can be replaced by variables and set when running the query by passing the values as parameters to the Query API.
Let's take a look at the following example.

<query>
    <executeACL>anonymous</executeACL>
    <condition>
    	<![CDATA[  firstName<string>={name} and lastName<string> = "Doe" ]]>
    </condition>
    <returnedFields>
    	<field>*</field>
    </returnedFields>
</query>

The value of the field firstName has been replaced by the variable name. When calling the Query API to run this saved query, the parameter name will have to be sent in the request and the query will use its value to execute the condition. Passing the value "Jane" to the parameter name will return all the documents containing the fields firstName with the value "Jane" and lastName with the value "Doe".

The parameter name can set to be optional by adding a question mark after the closing bracket. If the optional parameter is not sent in the Query request then the whole predicate will be ignored.

For example, if the condition is firstName<string>={name}? and lastName<string> = "Doe" and the optional parameter name is not passed in the Query request, then all documents containing the field lastName with the value "Doe" will be returned.

Special mention should be made when dealing with geospatial fields and the "within" operator that consists of two parameters:

<condition>
	<![CDATA[  location<geospatial> within (0,0,{distance}) ]]>
</condition>

<condition>
	<![CDATA[  location<geospatial> within ({point},{distance}) ]]>
</condition>

<condition>
	<![CDATA[  location<geospatial> within ({point},0.200) ]]>
</condition>

Query ACLs can be set using predefined ACL identifiers:

1. creator, meaning that the creator of the query can execute it. (<executeACL>creator</executeACL>).

2. anonymous, meaning that anyone can execute the query (<executeACL>anonymous</executeACL>)

3. authenticated-users, only authenticated users can execute the query.

4. nobody, no one can execute the query. Note that the owner will have access even if ACL is set to "nobody".

The schema sent by the user should conform to the xsd. All ACLs should be of the form ((group:){0,1}[0-9A-Za-z-_]{1,128}(;){0,1})*

(Refer to Common Request Parameters)

(Refer to Common Response Elements)

Sample Request

Request URL: http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/SaveQuery?apsws.time=[timestamp]&apsws.authSig=[signature]

POST parameters:

apsdb.queryName = [query_name]
apsdb.query = [query_xml_definition]
apsdb.update = [true|false]

Sample XML Response

Success XML:

< response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd" >
   < metadata >
      < requestId >xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx< /requestId >
      < status >success< /status >       
   < /metadata >
< /response >

Failure XML:

< response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd" >
   < metadata >
      < requestId >xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx< /requestId >
      < status >failure< /status >
      < errorCode >[errorCode]< /errorCode >
      < errorDetail >[failMsg]< /errorDetail >
   < /metadata >
< /response >

Sample JSON Response

{"response": {
   "metadata": {
      "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status": "success"
   }
}}