The Query API allows a User to retrieve data by running a dynamic Query.
A query is used to return document data from the specified store according to the query condition provided. The query request can be called with one or more of the following parameters:
• The query condition
• The list of fields to be returned
• The list of fields to be used to sort the results
• The count parameter that controls if the total number of available results should be returned
• A search string to be used to perform a full text search on all the documents that are indexed
• The number of results per page and the page number to be returned
• An aggregate function to perform on the query results
• The forceCurrentSnapshot parameter that controls whether the query should be executed on a read-only snapshot or the master snapshot
• The runAs parameter that allows the account owner to execute the query with the same permission as an account user
• The queryName parameter that gives to the user the possibility to execute a previously saved query
The user should write his query using the following predicate format composed of three parts: leftOperand comparisonOperator rightOperand
name<string> = “James”
The leftOperand is composed of one mandatory part and one optional part: fieldName<fieldType>
The mandatory fieldName is the name of the field. Note that some special fields (metadata) having the “apsdb.” prefix are always available for the users such as apsdb.documentKey, apsdb.versionNumber, apsdb.latestVersion, apsdb.creator, apsdb.creationTime, apsdb.lastModifiedBy, and apsdb.lastModifiedTime.
Special mention goes to the following versioning metadata fields:
- The "apsdb.versionNumber" metadata field specifies which version of the document to retrieve. If not specified, all versions of the document are returned. Example: (apsdb.documentKey = "myDoc") AND (apsdb.versionNumber = 1) --- returns the 1st version of the document keyed by "myDoc".
- The "apsdb.latestVersion" field can be used to return only the latest version of documents. It takes 0 or 1 as possible options, where 1 indicates a match for the latest version. For example, the condition ((apsdb.documentKey = "myDoc") AND (apsdb.latestVersion=1)) returns the latest version of the document keyed by "myDoc".
The optional fieldType is the type of the field; it could be numeric, string, geospatial or date and defaults to string. Note that we do not support fields of type text in the query condition, however, you can query on them using the Full Text Search feature.
The format to use for the fields of type 'date' is either yyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ssZ.
The comparisonOperator can be =, !=, >, >=, <, <=, in, in-all or like.
Note that if the comparisonOperator is like, then the rightOperand should be a string and cannot start with the wildcard %.
Special mention should be made when dealing with geospatial fields.
Geospatial fields do not support the comparison operators listed above. Instead, when dealing with geospatial fields, the "within" operator should be used. It allows queries to search for geospatial locations that lie within a specified distance from a reference point. Consequently, this operator requires 2 parameters: a geospatial reference point (represented as a pair of latitude/longitude decimal degrees), and a distance value (in kilometers). As an example, the following query condition can be used to find all locations that are 200m away from the Eiffel Tower: location<geospatial> within (48.8580, 2.2951, 0.200).
The rightOperand is the value of the field. If the type of the field is numeric then quotes (”) should be omitted, otherwise they are required. A more complex query will include logical operators (AND, OR) and parentheses to set the precedence. Note that in the absence of parentheses: The two logical operators “AND” and “OR” have the same precedence and the query will be executed by reading the conditions in order from left to right. The following is an example of a complex query syntax, you will notice that we have omitted quotes (“) to specify the fieldType for the string field “name” as it will be read as a string by default:
(name = "James" AND birthday<date> = "1982-05-30") OR (name = "John" AND age<numeric> = 26)