Decision Insight 20220509 (Latest) Save PDF Selected topic Selected topic and subtopics All content Queries Web Services API Prerequisites Web Services API 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
Queries Web Services API Prerequisites Web Services API 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" } ] }, ... ]