Query

Location /api/apps/{appID}/things/query
This resource represents a query to obtain a set of things from the accessed application.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

POST

/api/apps/{appID}/things/query

Description

Perform a query and retrieve the things that match with the specified conditions. The queriable fields that can be used for filtering and sorting are:

Field Name Field Type
_thingID String
_vendorThingID String
_thingType String
_vendor String
_firmwareVersion String
_productName String
_lot String
_created Integer
_disabled Boolean
_stringField1..5 String
_numberField1..5 Integer

Security

This action can be executed by the administrator and any authenticated user. Things and anonymous users are not allowed.

In case an authenticated user performs the action, the request should contain the appropriate clauses that match only with the things owned by the user or by groups in wihch the user is a member. Otherwise the request will not be authorized. Consider using the "contains" clause to reduce the matching things.

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

A request to perform a query.

The request is composed of the following information:

  • thingQuery: 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 things 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 things 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 thing 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 thing 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 thing 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 things in the application. This clause cannot be nested in other clauses (e.g., boolean clause or not clause).
  • range: Range clause. Check if the value in the thing 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 thing 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 things that do not match with a given clause.
    The additional field for this clause is as follows:
    • clause: The clause the things should not match.
  • hasField: "Has Field" clause. Check if the thing has a value for 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"
  • contains: "Contains Value" clause. Allows to filter the things owned by a given user or group.
    The additional fields for this clause are as follows:
    • field: Two possible values: "userOwners" in case of looking for things owned by a given user, or "groupOwners" when looking for things owned by a group.
    • value: The userID or groupID owner of the things

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
Params
Name Required? Type Description
thingQuery ThingQuery 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 things to get in the query result. The number set will be treated in a best effort way.
Sample Request
{
  "thingQuery": "[ThingQuery]",
  "paginationKey": "[string]",
  "bestEffortLimit": "[string]"
}
Responses
200

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

The query has been performed successfully. A set of things that match with the query will be returned.
Contents
Name Type Description
queryDescription string Description of the query.
results ThingRetrievalResponse Array of things that match the query.
_thingID string The identifier of the thing generated by Kii Cloud.
_vendorThingID string The provided identifier of the thing.
_thingType string The type of the thing.
_vendor string The vendor of the thing.
_firmwareVersion string The firmware version of the thing.
_productName string The product name.
_lot string The production lot.
_created long The creation date of the thing in UNIX epoch format (msec in UTC).
_stringField1 string The field for storing arbitrary string data.
_stringField2 string The field for storing arbitrary string data.
_stringField3 string The field for storing arbitrary string data.
_stringField4 string The field for storing arbitrary string data.
_stringField5 string The field for storing arbitrary string data.
_numberField1 long The field for storing arbitrary numeric data.
_numberField2 long The field for storing arbitrary numeric data.
_numberField3 long The field for storing arbitrary numeric data.
_numberField4 long The field for storing arbitrary numeric data.
_numberField5 long The field for storing arbitrary numeric data.
nextPaginationKey string The pagination key for getting the next page of result (if available).
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 ThingQuery 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 perform the query.
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).