# Type.Query Request

This message is used to read existing types.

This message is used to query one or more types using an optional QEL filter. This is a completely new message in Device API v2 format. This message is sent by a directly connected device via the IoTHub to the Ability Platform.

WARNING

The type.query message can deliver a maximum of 100 type definitions at a time. If a query returns a number that exceeds this limit, the 101st and all subsequent type definitions will not be delivered. In this case, the query must specify that any value that is not captured in the 100 delivered types by the query creator also be captured and delivered. Please be aware of this limitation when reviewing a list of delivered types. If exactly 100 types are delivered, there is a high probability that more exist but have not been delivered due to this limit.

The Device API of the Ability platform allows a BL developer to create, read, update, and delete (CRUD) data for managing types from directly connected devices using the Device API. Specifically, the feature supports the type.query message type.

NOTE

At present, the IoT Hub restricts C2D message size to 64kB. This means that a single type definition larger than 64kB will not be properly handled by the Device API. This limitation will be addressed in a future platform release.

NOTE

There are no changes in messaging for Edge devices in Anaheim. Edge support for the type.query Device API v2 message is planned for a future release.

# Idempotency

This request is idempotent, meaning that sending several identical requests will result in the same responses being sent back.

# Event Properties

# Unique Message Headers

Property	Mandatory	Description
model	Optional	Source model definition identifier (modelId). Case sensitive. If not provided, defaults to "abb.ability.device".

# Message Body

The body is composed of a well-formed JSON compliant to the .json schema.

Property	Mandatory	Data Type	Description
filter	Optional	string	Must only include properties applicable to type definitions.

# Message Format

{
    "properties": {
        "iothub-connection-device-id": "<authenticated device id>",
        "msgType": "action",
        "action": "type.query",
        "version": 2,
        "correlationId": "<correlation id>",
        "ack": "<ack>",
        "target": "<connected device path>",
        "timeout":"<integer>",
        "model": "<model definition>",
    "body": {
            "filter": "<query>"
    }
}

# Validation Rules

DCS validates all message properties, that the message body is in proper JSON format, and that all message body properties as specified in the summary of all v2 Device API messages.

# Functionality

# Description

A query against the TDR is performed to fetch all type definitions of a requested source model definition identifier (modelId), with an applied filter.
A separate notification C2D message for each type is not sent back. All types are included in acknowledgement(s).

NOTE Any platform events related to this request that are generated by

the TDR are ignored by the DCS and are not propagated.

If requested, an acknowledgement C2D message is sent back to the directly connected device where it can be propagated further, as needed (based on target). Note that the target is reused from the requested message. For more, see Acknowledgement Handling.
The target is reused from the requested message.

NOTE Since the acknowledgement also contains the types resulting from the

query, not requesting a positive acknowledgement means that the user will not be able to see those types. Therefore, the request must contain the "ack" property value "all" or "positive" to be valid. Providing a different "ack" value will result in a validation error and the request will not be processed.

Depending on the number of types returned, there may be one or more acknowledgement messages. One acknowledgement message cannot exceed the C2D message size limit (64kB, including message headers).

# Format of Returned Acknowledgement C2D Message

The general format of a Device API v2 acknowledgement message is described in Acknowledgement Handling.
CorrelationId and target should be reused from the input action.
Depending on the number of types returned, there may be one or more ack messages.
The DCS will try to pack as many types as possible into one acknowledgement message (limited by IoT Hub capabilities) and then continue with the next one.
The IoT Hub has a message size limit of 64kB (including message headers). Larger messages will be rejected, so one acknowledgement cannot be larger than 64kB.
The format of a successful acknowledgement includes a header and the boolean property true in the body. Note the following:
- Header - contains:
  - a timestamp with a required string data type. The timestamp is rendered in simplified extended ISO format (YYYY-MM-DDTHH:mm:ss.sssZ) and must be a zero UTC offset, as denoted by the suffix "Z".
- Body - contains:
  - a number: Mandatory. This is an integer, corresponding with the message number, starting with 1. Each query results in one or more acknowledgements, each with an incremental number used to de-duplicate and order. Ordering is not guaranteed, thus it is your responsibility to reassemble events in the correct order based on this number if ordering is important in your application.
  - a total: Mandatory. This is an integer, corresponding with the total number of acknowledgements for this query. The total cannot exceed 10 (requests resulting in more than 10 events will fail with a 'response_too_large' exception).
  - data: Mandatory. This is an array data type and corresponds with the actual results of the query execution. May be empty.

Successful Acknowledgement:

    {
  "properties": {
    "msgType": "ack",
    "action": "type.query",
    "version": 2,
    "correlationId": "<correlation id>",
    "target": "<target matches the target in the corresponding action>",
    "timestamp": "<YYYY-MM-DDTHH:mm:ss.sssZ>"
  },
  "body": {
    "success": true,
    "code": "ok",
    "details": "",
    "number": "<number>",
    "total": "<total>",
    "data": [
        "<array of type payloads>"
      ]
    }
  }

The format of a failed acknowledgement includes a header and the boolean property false in the body. Note the following:
- Header - contains:
  - a timestamp with a required string data type. The timestamp is rendered in simplified extended ISO format (YYYY-MM-DDTHH:mm:ss.sssZ) and must be a zero UTC offset, as denoted by the suffix "Z".
- Body - contains:
  - success (false), code, and details

Failed acknowledgement:

{
  "properties": {
    "msgType": "ack",
    "action": "type.query",
    "version": 2,
    "correlationId": "<correlation id>",
    "target": "<target matches the target in the corresponding action>",
    "timestamp": "<YYYY-MM-DDTHH:mm:ss.sssZ>"
  },
  "body": {
    "success": false,
    "code": "<error code>",
    "details": "<error details>"
    }
}

← Type.Delete (V2) Reference.Create (V2) →