For the list of all supported Decision Insight downloads and releases, see the Downloads page.

Queries Web Services API

Prerequisites

Query service

This service allows data integrators to retrieve data stored into a node using a Query.

Usage

The query is invoked by sending a JSON formatted body via an HTTP request to the URL <node url>/ws/query/<space name>/<query name>

Example of HTTP body 
{ 
  "tnd-query.transactionTime" : "1506945997310263297",
  "tnd-query.referenceTime": "2014-12-25T10:00:00+01:00",
  "vip": false
}

URI format

All requests must be POST request to the following URL:

<node url>/ws/query/<space name>/<query name>[?options]

URI options

Name Default value Description
maxRowCount 500 Maximum number of rows returned by the query

Examples 

POST: <node url>/ws/query/hvp/List_Payments?maxRowCount=25

Header format

All requests must include three HTTP headers:

Header Description

Authorization

Credentials of the user that wants to execute the query.

This user must have all the following permissions:

  • "Access data integration API" permission on the node
  • "Access" permission on the space of the query
  • "Access the application" permission on the application with access to the space of the query

The credentials must be sent using the HTTP Basic authentication scheme (ex: Basic YWRtaW46YWRtaW4= )
Version Version of the API to use. Currently, the only supported value is 1.
Content-Type

Content type of the request. It must be set to either application/json, text/json or text/plain.

Body format

The request must contain in the body a JSON object containing the parameters declared for the query. A special parameter named "ReferenceTime" is used to indicate the time used by the query to query data against.

{
    "tnd-query.referenceTime": "NOW"
    "customerName": "Acme Corp"
}

The parameters to send to the query are the parameters expected by the query.

Query parameter type JSON data type Example
Boolean boolean true
Decimal double 123.45
Duration
  • integer with the duration in milliseconds
  • ISO 8601 formatted duration string

1234

"PT1849S"
Instance
  • UUID string
  • long identifier

"dd68f200-8475-11e4-b4a9-0800200c9a66"

1487522985861449729

Instant
  • integer with the number of milliseconds since Unix epoch
  • ISO 8601 formatted date string
  • one of the following constants:
    • NOW
    • TODAY
    • YESTERDAY
    • FROM_START
    • UNTIL_END

1418660002223

"2014-12-15T16:13:22.223Z"
Integer integer 123
String string "Hello"
Interval

string containing an ISO 8601 formatted interval

(2 instants separated with a slash character '/')

"2014-12-25T00:00:00.000+01:00/2014-12-26T00:00:00.000+01:00"

"2014-12-14T12:00:00.000Z/ UNTIL_END "

"YESTERDAY/TODAY"
CalendarDuration

string containing a scalar and a duration field type.

The following duration field types are supported:

  • millis
  • seconds
  • minutes
  • hours
  • days
  • weeks
  • months
  • years

"1 minutes"

"3 days"

"2 weeks"

Beware

The type of the parameter expected by the Web service might not be the type of the parameter of the query. For example, if you have selected a parameter of type Instant in the query and a function Intersect, the type of the parameter expected by the Web service will be Interval.

Response format

The response is a JSON list of rows.

Each row is a map containing the "columns" that were requested along with their values.

  • The key of the map is the name of the attribute (as displayed in the Data integration > Queries User Interface)
  • The value of the map is a list of objects containing three fields
    • "value": This field contains an object containing one or more fields
      • "Value": The actual value. Its type depends on the type of the requested attribute
      • "Label": For attributes of type Classifier only: The label of the classifier value (string)
      • "Rank": For attributes of type Classifier only: The rank of the classifier value (integer)
    • "validTime" (optional): The validity interval of the value
    • "knowledgeTime" (optional): the knowledge time of the value

Here is a typical response:

HTTP response body 
[
  {
    "name": [
      {
        "value": {
          "Value": "Screening Reject"
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "STP": [
      {
        "value": {
          "Value": false
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "inProcessCountStatus": [
      {
        "value": {
          "Value": "00000002-0001-0000-130b-29020cc02800",
          "Rank": 0,
          "Label": "NORMAL"
        },
        "validTime": "2014-12-25T10:25:00.000Z/2014-12-25T10:26:00.000Z",
        "knowledgeTime": "2014-12-25T10:25:02.589Z"
      }
    ]
  },
  {
    "name": [
      {
        "value": {
          "Value": "Manual Repair"
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "STP": [
      {
        "value": {
          "Value": false
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "inProcessCountStatus": [
      {
        "value": {
          "Value": "00000002-0001-0000-130b-29020cc02800",
          "Rank": 0,
          "Label": "NORMAL"
        },
        "validTime": "2014-12-25T10:25:00.000Z/2014-12-25T10:26:00.000Z",
        "knowledgeTime": "2014-12-25T10:25:02.589Z"
      }
    ]
  },
  ...
]

For more information, read Inside a Query Result.

Examples

The following examples use the authorization token Basic YWRtaW46YWRtaW4= which is the Base64-encoded version of the default credentials of the admin user account (user: admin / password: admin).

If you have changed the default credentials of the admin account, you should replace the authorization token with valid Base64-encoded credentials.

Executing a query that lists all instances of an Entity

Given the following query:

To list all steps that are alive now, you need to send the following HTTP request:

URL 
POST: http://localhost:8080/ws/query/hvp/List_Steps

To retrieve a maximum of 5 rows, you need to send the following HTTP request:

URL 
POST: http://localhost:8080/ws/query/hvp/List_Steps?maxRowCount=5
HTTP Headers 
Authorization: Basic YWRtaW46YWRtaW4=
Version: 1
Content-Type: application/json
HTTP body 
<empty>

The Web service will return a response with a content similar to:

HTTP response body 
[
  {
    "name": [
      {
        "value": {
          "Value": "Screening Reject"
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "STP": [
      {
        "value": {
          "Value": false
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ]
  },
  {
    "name": [
      {
        "value": {
          "Value": "Manual Repair"
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "STP": [
      {
        "value": {
          "Value": false
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ]
  },
  ...
]

Executing a query that lists all instances of an Entity at a certain time

Given the following query:

To list all steps that were alive on December 25th 2014 at midnight GMT, you need to send the following HTTP request:

URL 
POST: http://localhost:8080/ws/query/hvp/List_Steps
HTTP Headers 
Authorization: Basic YWRtaW46YWRtaW4=
Version: 1
Content-Type: application/json
HTTP body 
{
	"tnd-query.referenceTime": "2014-12-25T00:00:00Z"
}
HTTP response body 
[
  {
    "name": [
      {
        "value": {
          "Value": "Screening Reject"
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "STP": [
      {
        "value": {
          "Value": false
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ]
  },
  {
    "name": [
      {
        "value": {
          "Value": "Manual Repair"
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "STP": [
      {
        "value": {
          "Value": false
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ]
  },
  ...
]

Executing a query that lists instances of an Entity filtered by an attribute

Given the following query:

 

To list all STP steps that are alive, you need to send the following HTTP request:

URL 
POST: http://localhost:8080/ws/query/hvp/List_Steps
HTTP Headers 
Authorization: Basic YWRtaW46YWRtaW4=
Version: 1
Content-Type: application/json
HTTP body 
{
	stp: true
}
HTTP response body 
[
  {
    "name": [
      {
        "value": {
          "Value": "Routing"
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ],
    "STP": [
      {
        "value": {
          "Value": true
        },
        "validTime": "2014-12-22T23:00:00.000Z/UNTIL_END",
        "knowledgeTime": "2014-12-31T09:24:23.728Z"
      }
    ]
  },
  ...
]

Related Links