Query

Location /api/apps/{appID}/groups/{groupID}/buckets/{bucketID}/query
This resource represents a query to obtain a set of objects from the accessed bucket.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

POST

/api/apps/{appID}/groups/{groupID}/buckets/{bucketID}/query

Description

Query the bucket and retrieve the objects that match with the specified conditions.

Security

The administrator can execute this action. For other users, the permission to execute this action is determined by the ACL set on the bucket and objects.

In detail, the administrator can retrieve all the matching objects. For a user and thing, you first need to have the permission QUERY_OBJECTS_IN_BUCKET on the bucket to query the bucket. If the user/thing has the permission READ_OBJECTS_IN_BUCKET granted on the bucket, the query result will contain all the matching objects. Otherwise, the query result will contain only the matching objects on which the user/thing has the permission READ_EXISTING_OBJECT.

Content-Type application/vnd.kii.QueryRequest+json

A request to perform a query.

The request is composed of the following information:

  • bucketQuery: A JSON object that contains:
    • clause: The clause for the query. The details are explained in below.
    • orderBy: The field used for aligning the query result. This field is optional.
    • descending: A boolean field indicating whether the objects should be sorted in a descending or ascending order. This field works in pair with the "orderBy" and has no effect if the "orderBy" is not provided. This field is optional. If not provided, the field will be set to false by default.
  • paginationKey: The pagination key for getting the next page of the query result. The key will be provided when the result is returned in the paginated manner.
  • bestEffortLimit: The maximum number of objects to retrieve in one response.

Clauses The conditions of the query. There are several types of clauses available. For all clauses, the type of the clause is to be set in the field "type". Some clause types require more fields.

The available clause types are as follows:
  • eq: Equality clause. Check if a field in the object has the specified value.
    The additional fields required for this clause are as follows:
    • field: The name of the field.
    • value: The value that the specified object field should have.
  • prefix: Prefix clause. Only valid for string fields. Check if a string field starts with a specified prefix.
    The additional fields required for this clause are as follows:
    • field: The name of the field.
    • prefix: The prefix that the specified object field should start.
  • and: Boolean clause that concatenates a list of clauses with an "AND" connector.
    The additional field for this clause is as follows:
    • clauses: An array of clauses.
  • or: Boolean clause that concatenates a list of clauses with an "OR" connector.
    The additional field for this clause is as follows:
    • clauses: An array of clauses.
  • all: All clause. This clause returns all objects in the bucket. This clause cannot be nested in other clauses (e.g., boolean clause or not clause).
  • range: Range clause. Check if the value in the object field is in the specified range of values.
    The additional fields required for this clause are as follows (either the upper or the lower limit can be omitted, but not both):
    • field: The name of the field.
    • upperLimit: The upper limit of the range.
    • upperIncluded: Boolean field that indicates if the upper limit is included in the range. The default value is "true".
    • lowerLimit: The lower limit of the range.
    • lowerIncluded: Boolean field that indicates if the lower limit is included in the range, The default value is "true".
  • in: In clause. Check if the object field has one of the specified values.
    The additional fields for this clause are as follows:
    • field: The name of the field.
    • values: The list of values to match.
  • not: Not clause. Returns all the objects that do not match with a given clause. The condition does not match if the specified field does not exist.
    The additional field for this clause is as follows:
    • clause: The clause the objects should not match.
  • hasField: "Has Field" clause. Check if the object has a specified field.
    The additional fields for this clause are as follows:
    • field: The name of the field.
    • fieldType: Type of the field. The possible values are "STRING", "INTEGER", "DECIMAL", and "BOOLEAN"
  • geobox: "Within a box" clause. Allows to search objects in a given rectangle defined by the northeast and southwest points.
    The additional fields for this clause are as follows:
    • field: The name of the field.
    • box: JSON containing 2 properties of type point*:
      • ne: North East point with its corresponding longitude and latitude.
      • sw: South West point with its corresponding longitude and latitude.

      * Point type: Contains the following fields:

      • lat: Latitude. Decimal value in range ]-90, +90[
      • lon: Longitude. Decimal value in range ]-180, +180[
  • geodistance: "At a distance from point" clause. Allows to search objects that are at a given distance from a single point.
    The additional fields for this clause are as follows:
    • field: The name of the field.
    • center: The center.
    • radius: The radius from the center in meters. The allowed value is from 0 to 20000000.
    • putDistanceInto: The name of the field for storing the distance from the "center" in the query response. This field is optional. If this field is set, the field "_calculated" will be set for each object in the response. Inside this field, the field with the specified name will be set as the subfield with its value set to the distance from the "center" (in meter).

Headers
Name Required? type Description
Authorization Yes string Authorization can be of type Basic or Bearer.
  • Authorization Basic: header for granting an anonymous access.
    • Set a Base64-encoded string of AppID and AppKey concatenated with a colon (APP_ID:APP_KEY).
    • The header should look like:
      Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
  • Authorization Bearer: using Oauth2 Bearer Token.
    • The header should look like:
      Authorization: Bearer ht5fpHQAyrPPwLftK1rAqllv5WNVPCnYfPiCvPocFuQ
Params
Name Required? Type Description
bucketQuery BucketQuery A JSON object which represent a query.
clause Clause The query clause(s).
orderBy string The field used for sorting the query result.
descending string The sort order. True if the order is in the descending order.
paginationKey string The pagination key obtained in the previous request. Setting the pagination key will allow you to get the next page of the result.
bestEffortLimit string The maximum number of objects to get in the query result. The number set will be treated in a best effort way.
Sample Request
{
  "bucketQuery": "[BucketQuery]",
  "paginationKey": "[string]",
  "bestEffortLimit": "[string]"
}
Responses
200

Content-Type application/vnd.kii.QueryResponse+json

The query has been performed successfully. A set of objects that match with the query will be returned.
Contents
Name Type Description
queryDescription string Description of the query.
results JSONObject Array of JSON objects that match the query.
nextPaginationKey string The pagination key for getting the next page of result (if available).
404

Content-Type application/vnd.kii.GroupNotFoundException+json

The group was not found.
Contents
Name Type Description
errorCode string Error code "GROUP_NOT_FOUND".
message string The error message.
groupID string The groupID of the group.
appID string The ID of the application.
400

Content-Type application/vnd.kii.QueryNotSupportedException+json

The query was not supported. The clauses were used incorrectly, or invalid values were used in the clause.
Contents
Name Type Description
errorCode string Error code "QUERY_NOT_SUPPORTED".
message string The error message.
query BucketQuery The query that caused the error.
clause Clause The query clause(s).
orderBy string The field used for sorting the query result.
descending string The sort order. True if the order is in the descending order.
clause Clause The clause within the query that caused the error.
reason string The explanation of the error.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to query data in the bucket.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).