Querying KiiObjects
You can run a conditional query for KiiObjects in a bucket. For example: a query that gets up to 10 KiiObjects that have a value of more than 10 for a key named "count" in descending order.
See Query Examples for various query examples.
Executing a KiiObject query
Defining a query condition
You can define a query condition using the following methods of the KiiClause class:
| Method | Query condition |
|---|---|
| equals() | Match when the field value is equal to the specified value. |
| notEquals() | Match when the field value is not equal to the specified value. The condition does not match if the specified field does not exist. |
| greaterThan() | Match when the field value is greater than the specified value. |
| greaterThanOrEqual() | Match when the field value is greater than or equal to the specified value. |
| lessThan() | Match when the field value is less than the specified value. |
| lessThanOrEqual() | Match when the field value is less than or equal to the specified value. |
| inClause() | Match when the field value is equal to one of the specified values. Up to 200 values can be specified. The type of the parameter value must match with the type of the JSON field. |
| startsWith() | Match when the field value (String) starts with the specified string. |
| geoBox() | Match when the field value (GeoPoint) is inside the specified GeoBox (rectangular area). |
| geoDistance() | Match when the field value (GeoPoint) is inside the specified GeoDistance (circular area). |
| hasField() | Match when the field has the specified field type (currently supported types are STRING, INTEGER, DECIMAL, and BOOLEAN). |
You can concatenate multiple query conditions using the following methods of the KiiClause class:
| Method | How to concatenate |
|---|---|
| and() | Concatenate query conditions with an "AND" operator. |
| or() | Concatenate query conditions with an "OR" operator. |
| not() | Concatenate query conditions with a "NOT" operator. The argument is a KiiClause instance. It can be a single-condition clause or a multiple-condition clause concatenated by the and() or or() method. |
See the JSDoc to learn more about KiiClause class.
Querying with a not() clause can decrease performance but you might be able to transform the clause to avoid a not operator. See Transforming a not clause for more information.
Creating a query instance and executing a query
Create a KiiQuery instance by passing a KiiClause instance to the queryWithClause() method. If no KiiClause instance is passed, the query will return all KiiObjects in the target bucket (this is equivalent to an "all" query).
You can fine-tune a query instance by calling the following methods.
- sortByAsc(): sorts query results in ascending order by the specified field.
- sortByDesc(): sorts query results in descending order by the specified field.
- setLimit(): sets the maximum number of KiiObjects returned as query results on the best-effort basis. The maximum value is 200.
The detailed specification of the query feature is as below:
The
sortByAsc()andsortByDesc()methods can be applied to only one field.If neither
sortByAsc()norsorByDesc()method is specified, the query results will be in arbitrary order. If thesetLimit()method is not executed, the maximum number of KiiObjects returned by a query may be up to 200 by default.The
setLimit()method is on a best-effort basis. For example, Kii Cloud does not guarantee to return all 40 KiiObjects when the limit is set to 40 and there are more than 40 KiiObjects that satisfy the query condition (this could happen for performance optimization purposes).If you are going to have more than 200 query results, you will need to use the pagination to divide them into several pages.
The
sortByAsc()andsortByDesc()methods sort query results by an integer field in numerical order and by a string field in dictionary order.Query and sort do not work properly if the type of the field values is not consistent among KiiObjects.
Strings are queried in a case-sensitive manner. For example, if you query with a string of "alice", "Alice" stored in a KiiObject will not be returned.
Query and sort might not work as expected for real number fields. Real numbers whose fractional part is zero are treated as integers. Therefore, for example, 1.0 will be indexed as an integer 1 while 1.1 will be indexed as a real number 1.1. You cannot get the expected result because the difference between the different types of values will not be correctly evaluated. If you need to query or sort KiiObjects with a real number field, convert real numbers to integers by multiplying them with 10, 100, and so forth. Then save the converted integers in an integer field to use when you run a query.
Only the first-level fields within the JSON expression can be queried. You cannot get fields at the subsequent levels because fields at those levels are not indexed.
When you are using the "inClause " method, make sure that the type of the parameter values matches with the type of the JSON field. For example, a JSON string
{"id" : 123}will not match with a string "123" but a number 123. If you specify multiple values to compare, the type must be the same among the values. Do not mix numbers and strings nor decimals and integers.Queryable fields must have the field name up to 250 characters and a value (String) up to 190 characters. Key-value pairs that exceed these limits will not be returned by any query using the field.
To execute a query for KiiObjects, use the executeQuery() method of the target bucket with a query instance.
See the JSDoc to learn more about the KiiQuery class.
The performance of query and sort operations can deteriorate if there are numerous KiiObjects. See Performance for more information.
Using predefined keys for query
In addition to key-value pairs created by your mobile app, you can use predefined keys for query.
Predefined keys include various fields such as the KiiObject ID and created time. For the list of predefined keys, see Predefined keys.
Getting query results
Query results will be returned as a KiiObject array. If the results are split across multiple pages (e.g. The limit is set to 10 and the query returned 30 KiiObjects), Kii Cloud will return a KiiQuery instance along with the query result. You can get the remaining query results by executing the query with this KiiQuery instance.
The SDK might indicate that there are more KiiObjects when actually there are not any, that is to say, the SDK might return a non-null value for the nextQuery() method. It might happen when the number of KiiObjects returned from the server at a time and the number of KiiObjects that meet the query condition are the same. You should be aware that an empty result might be returned when an attempt is made to get a next page.
You need to handle the paging by yourself if you want to show a fixed amount of query results at a time, for example on the Web. The query results can be obtained only in the forward direction, and the number of results may not be constant because the query mechanism works on the best-effort basis. You might want to get the number of KiiObjects first and uses this number to control the paging.