Selecting

By default, the search response includes all the data streams of the searched entities. You can retrieve only the information you need using the select sub-document in the search JSON.

The select sub-document can be used only on entity searching and must not be empty.

You can also use this sub-document when you search for information in CSV format.

If the select clause isn’t in the filter, the behavior is the following:

• In JSON format, the response will contain all the data streams collected or provisioned in the devices you are searching.
• In CSV format, the search API raises an error in the response, asking for the select clause.

As described above, any data stream of the default data models or data models defined by the user can be used as select fields.

The order to apply the filters is securitization and next the following fields whenever there are resourceType, sort, filter, select (the data streams to show)

Select JSON object

• select[]: Array of parameters to be selected.

  • name: String. Data stream name in the default or user-defined data models.

  • fields[]: Array of strings with the name of the fields to be retrieved.

    The possible values are: (See current object attributes table for field description):

    • value
    • date
    • at
    • from
    • tags
    • feedId
    • scoring.performance
    • scoring.qrating
    • provType
    • value.simplexAttribute: where simplexAttribute is an attribute of the complex object. For example, the provision.device.location is a complex data stream. If you need only de postal code, the value would be value.postal

  • alias: String. Shortname replaces the parameter’s full name when a CSV format is required. Example:

    • Using “alias”=“imei”
    • The device.communicationModules[].mobile.imei becomes imei in the CSV header

    The complete data stream name in the CSV header will appear if this field doesn’t exist. The CSV format shows this field, but the JSON format ignores it.

Select examples

Here’s how to search devices with a filter with a select clause

The following snippet shows the request using curl:

curl --request POST \
     --data-binary @subscription.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     HTTP://[your_opengate_address]/north/v80/search/devices \
     -H "Content-type: application/json"

You include the filter with the select clause in the request’s body.

Filter using predefined device fields

{
  "select": [
    {
      "name": "provision.device.identifier",
      "fields": [
        {
          "field": "value",
          "alias": "id"
        },
        {
          "field": "date",
          "alias": "date"
        }
      ]
    }
  ]
}

Filter obtaining a field of a complex value

{
  "select": [
    {
      "name": "provision.device.location",
      "fields": [
        {
          "field": "value.postal",
          "alias": "Postal code"
        }
      ]
    }
  ]
}

Depending on the parameter header, the response can be in two different formats, see HTTP Header Options:

• JSON Format (Default)
• CSV Format

Response to the filter in JSON format example

{
  "devices": [
    {
      "id": "bca8cbbb-b151-442b-8b0d-96ed77789c45",
      "device": {
        "operationalStatus": {
          "current": {
            "value": "NORMAL",
            "date": "2017-02-02T09:05:58Z",
            "performance": 75
          }
        },
        "communicationsModules": [
          {
            "identifier": "351873000102290",
            "mobile": {
              "imei": {
                "current": {
                  "value": "351873000102290",
                  "date": "2017-02-02T09:05:58Z"
                }
              }
            }
          }
        ]
      },
      "health": {
        "heart": {
          "rate": {
            "current": {
              "value": 60,
              "date": "2017-02-02T09:05:58Z",
              "performance": 78
            }
          }
        }
      }
    }
  ]
}

Response to the Filter in CSV format example

device.operationalStatus.current.value;device.operationalStatus.current.updated;device.operationalStatus.current.performance;imei.current.value;imei.current.updated;imei.current.performance;rate.current.value;rate.current.updated;rate.current.performance;
"NORMAL";"2017-02-02T09:05:58Z";75;"351873000102290";"2017-02-02T09:05:58Z";;60;"2017-02-02T09:05:58Z";78