Query API requests
- Former user (Deleted)
- Laszlo Frazer
- Mercedes Parrado Mejuto
Overview
Check the list of available endpoints and methods to work with the Query API:
Endpoints and methods | Description |
|---|---|
POST | Run a query. |
GET | Get information about a table, including the data types. |
Endpoints and methods
POST/query
Use this endpoint tu run a query through the API.
Request
Request body
The request JSON body must include an object with the following key-value pairs.
Parameter | Type | Description |
|---|---|---|
|
| This is the query that you want to run, expressed in LINQ. To find the query's LINQ script in the Devo app, open the query in the Data search area, then choose Query code editorfrom the toolbar. The body of the request must contain either the |
|
| This is the ID of the query that you want to run. To find the query ID, open the query in the Data search area, then open the search window menu and select Current query Get ID. The body of the request must contain either the |
|
| The start date as a UTC timestamp in seconds. See the Relative dates section below to learn more about this parameter. |
|
| The end date as a UTC timestamp in seconds. If this parameter is left out, the query will be continuous. See the Relative dates section below to learn more about this parameter. |
|
| This object contains the The possible values are:
These response formats are fully described later in this article. When you indicate a response format other than |
|
| This object specifies where the response should be sent. If this object is left out of the request body, the response will be sent back to the request source. It must include the following parameters:
Depending on the |
|
| This is only required when you specify a
|
|
| Change the timezone of the query, only for mode types other than |
|
| When |
|
| You can use either the |
|
| Limit the results of the query. The query will stop after returning the first X elements of the query or reaching its end. |
|
| Set this parameter to |
|
| Query priority. Allowed values are:
|
|
| Set this parameter to This is only available if you set |
|
| Specifies whether partial results are allowed or not ( |
|
| Object with information about the keep alive message for CSV, TSV and XLS modes. If not provided, live queries aren't accepted for the mentioned modes. Note that this object doesn't apply to any This object must contain the following parameters:
Examples: "keepAlive": {
"type":"empty"
}"keepAlive": {
"type":"token",
"token":"myToken"
} |
|
| Add this object to use time control in your query. Time control allows you to choose either the event date (time when Devo receives the data) or creation date (time when the events are generated in its source) as reference time when you query data. Check this article to learn more about time control and how to use it in the Devo app. This object may include the following parameters:
Setting a reception delay using the |
Example
curl --location 'https://apiv2-us.devo.com/search/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 2e672c8182f67a3bc6cd7a6815864589' \
--data '{
"query": "from siem.logtrust.web.activity",
"limit": 30,
"from": "1s",
"keepAlive": {
"type":"empty"
}
}'
The following are examples of responses:
{
"query": "from demo.ecommerce.data select *",
"from": 1519645036,
"to": 1519645136,
"mode": {
"type": "json"
},
"destination": {
"type": "hdfs",
"params": {
"param1": "value1",
"param1": "value2"
}
}
}{
"from": 1519989362,
"mode": {
"type": "json/simple"
},
"query": "from my.synthesis.vec00.suricataalert group every 30s every 30s select *",
"to": 1519989392
}{
"query": "from demo.ecommerce.data select *",
"limit": 10,
"from": 1528306922,
"to": 1528306952,
"mode": {
"type": "tsv"
}
}GET/table/{tableName}
Get information about a table, including data types.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| A Devo table, such as |
Request example with curl, using jsonlint to add whitespace:
url="https://apiv2-us.devo.com/search/table/my.synthesis.example.customtable"
curl -s -S -H "Content-Type: application/json" -H "Authorization: Bearer $token" $url | jsonlint
Response
Code | Description |
|---|---|
200 | Successful response. {
"cid": "4d9e71cbc840",
"msg": "",
"object": [
{
"fieldName": "eventdate",
"type": "timestamp"
},
{
"fieldName": "example_field_str",
"type": "str"
},
{
"fieldName": "example_field_int",
"type": "int8"
},
{
"fieldName": "example_field_json",
"type": "json"
},
{
"fieldName": "example_field_ip4",
"type": "ip4"
}
],
"status": 0,
"timestamp": 1741291334113
} |
4xx | Bad request. {
"timestamp": 1741293602208,
"cid": "6acc31e8644c",
"msg": "Access not allowed for table 'my.synthesis.incorrect.table'",
"status": 403
}
The Access not allowed message will occur for tokens with scope |
Relative time-ranges
The Query API supports the same date language for relative days as the one used in the Data Search section. Devo encourage to use relative date language to perform Query API requests.
Deprecated date language expressions
A relative date range is a period of time that is relative to the current date (last week, last month, etc). You can add different operators to thefromandtoparameters of your query request to indicate specific time ranges.Note that the date you enter in thetoparameter must always be greater than or equal to thefromdate.
For all the examples that don't use a timestamp to specify a date, weassume that the moment of execution is08-10-2018, 14:33:12 UTC.
Dates
Operator | Description |
|---|---|
| Get the current day at 00:00:00. Note that the
|
| Get the current day and time
|
| If you use this in the
|
| If you use this in the
|
Days
Operator | Description |
|---|---|
| Enter a number followed by
|
| Enter a number followed by
|
Hours
Operator | Description |
|---|---|
| Enter a number followed by
|
| Enter a number followed by
|
Query response formats
Responses to your queries can be either returned to the source of the request, forwarded to an HDFS,S3, SNMP, or Kafka type system, or sent via email.
Given the different possible destinations for query responses, you can also specify the format in which you want the response to be sent. This is specified in themode.typeparameterof the request body. The available response formats are:
Response type JSON
This is the default response format. This means that if you leave out themodeobject from the request body, the response will automatically be returned in this format.
So, to receive responses in JSON format, you can either leave themodeobject out of the request or you can specify it like this:
"mode": {
"type":"json"
}The JSON response will include the following fields:
Field name | Type | Description |
|---|---|---|
|
| This describes the error in the case that the request was not successful. This field will be named The corresponding error code will be shown in the |
|
| Numeric value that specifies the error code. When it shows These are the possible error codes that you may get. The corresponding error descriptions will be displayed in the
|
|
| The content of
See examples below. |
|
| An ID value to uniquely identify yourself across multiple systems. |
|
| Indicates the moment when a certain event occurred. |
Examples
Here is a response in JSON format of a successful query.
{
"status": 0,
"cid": "XXX",
"timestamp": 1528308389081,
"msg": "",
"object": [
{
"eventdate": "2016-10-24 06:35:00.000",
"host": "aws-apiodata-euw1-52-49-216-97",
"memory_heap_used": "3.049341704E9",
"memory_non_heap_used": "1.21090632E8"
},
{
"eventdate": "2016-10-24 06:36:00.000",
"host": "aws-apiodata-euw1-52-49-216-97",
"memory_heap_used": "3.04991028E9",
"memory_non_heap_used": "1.21090632E8"
},
…
}Example when error code 400 (client error):
{
"timestamp": 1732648392046,
"cid": "XXX",
"error": "Bad parameters",
"status": 400,
"object": [
"405 : Date from not valid or not found"
]
}Example when error code 500 (server error):
{
"timestamp": 1732647846299,
"cid": "XXX",
"msg": "Error Launching Query",
"status": 500,
"object": [
"Error Launching Query",
"Unknown identifier `machine`",
"1101001",
"QUERY_PARSING_ERROR",
"NO"
]
}object positions
[0] is the error message
[1] is the user error message
[2] is the internal error code See Search monitoring (error codes) | Code errors for more details.
[3] is the error name
[4] indicates if:
YES the query is recoverable. The query is fine, but there is a temporary problem for retrieving the results.
NO the query is not recoverable. There is a data problem that should be solved.
Response type JSON/compact
To receive responses in JSON/compact format, specify themodeobject in your request like this:
"mode": {
"type":"json/compact"
}The JSON/compact response will include the following fields:
The
mobject lists the fields included in each query result along with theirtypeandindexmetadata.
Field name | Description |
|---|---|
| The datatype of the value returned. This will be one of:
|
| An integer value that indicates the position of the field's value in the arrays returned in the object.d object. |
The
metadataobject gives information about the fields as an array, and includes the following fields:
Field name | Description |
|---|---|
| Name of the field. |
| The datatype of the value returned. This will be one of:
|
The object
dincludes lightweight event info.
Example
Here is an example of a response in JSON/compact format that occurred without error:
{
"m": {
"eventdate": {
"type": "timestamp",
"index": 0
},
"level": {
"type": "str",
"index": 1
},
"srcPort": {
"type": "int4",
"index": 2
}
},
"metadata": [
{
"name": "eventdate",
"type": "timestamp"
},
{
"name": "level",
"type": "str"
},
{
"name": "srcPort",
"type": "int4"
}
],
"d": [
[
1519989828006,
"INFO",
51870
],
[
1519989828392,
"INFO",
51868
],
[
1519989830837,
"INFO",
55514
]
]
}
Response type JSON/simple
To receive responses in JSON/simple format, specify the mode object in your request like this:
"mode": {
"type":"json/simple"
}The response is a stream of JSON objects of the values that the query generates with the structure below.When the query does not generate more information, the connection is closed by the server. In case no dateto value is requested, the connections are kept alive.
Example
{"eventdate":1488369600000,"domain":"none","userEmail":"","country":null,"count":3}
{"eventdate":1488369600000,"domain":"user1@devo.com","userEmail":"0:0:0:0:0:0:0:1","country":null,"count":18}
{"eventdate":1488369600000,"domain":"none","userEmail":"user2@devo.com","country":null,"count":7}
{"eventdate":1488373200000,"domain":"user3@devo.com","userEmail":"127.0.0.1","country":null,"count":10}
{"eventdate":1488373200000,"domain":"user4@devo.com","userEmail":"0:0:0:0:0:0:0:1","country":null,"count":28}
{"eventdate":1488373200000,"domain":"dom","userEmail":"user5@devo.com","country":null,"count":15}
...
Responsetype JSON/simple/compact
To receive responses in JSON/simple/compact format, specify the mode object in your request like this:
"mode": {
"type":"json/simple/compact"
}The response is a stream of JSON objects with the following structure:
The
mobject lists the fields included in each query result along with theirtypeandindexmetadata.
Field name | Description |
|---|---|
| The datatype of the value returned. This will be one of:
|
| An integer value that indicates the position of the field's value in the arrays returned in the object.d object. |
The
metadataobject gives information about the fields as an array, and includes the following fields:
Field name | Description |
|---|---|
| Name of the field. |
| The datatype of the value returned. This will be one of:
|
The object
dincludes the array of values with the returned events data. Every row is a valid JSON object.
When the query does not generate more information, the connection is closed by the server. In case no dateto valueis requested, the connections are kept alive.
Progress data in timestamp
You can receive a timestamp indicating the progress data as an entryp in your response, if the progressInfo parameter is set to true in the request.
Example
{
"m":{
"eventdate":{
"type":"timestamp",
"index":0
},
"level":{
"type":"str",
"index":1
},
"srcPort":{
"type":"int4",
"index":2
}
},
"metadata":[
{
"name": "eventdate",
"type": "timestamp"
},
{
"name": "level",
"type": "str"
},
{
"name": "srcPort",
"type": "int4"
}
]
}
{
"d":[
1519989516834,
"INFO",
49756
]
}
{
"d":[
1519989516874,
"INFO",
51472
]
}
{
"d":[
1519989517774,
"INFO",
49108
]
}
{
"p":[
1519989537574
]
}
{"d":[
1519989538794,
"INFO",
49108
]
}
Response type MsgPack
To receive responses in MsgPack format, specify the mode object in your request like this:
"mode": {
"type":"msgpack"
}The response format is the same as a JSON object, but encoded using MsgPack, an efficient binary serialization format. See the msgpack website for more information.
Response type CSV
To receive responses in CSV format, specify the mode object in your request like this:
"mode": {
"type":"csv"
}The system will return the information in CSV (Comma Separated Values) format. The following is a simple example of a CSV response.
Example
|
|---|
Response typeTSV
To receive responses in TSV format, specify the mode object in your request like this:
"mode": {
"type":"tsv"
}The system will return the information in CSV (Comma Separated Values) format. The following is a simple example of a TSV response.
Example
|
|---|
Response type Excel
To receive responses in XLS format, specify the mode object in your request like this:
"mode": {
"type":"xls"
}The system sends the query results in a Microsoft Excel format file.
Response type Avro
To receive responses in XLS format, specify the mode object in your request like this:
"mode": {
"type":"avro"
}The system sends the query results in Avro binary format. Avro is used with Hadoop or Kafka.
Example Request
api="https://apiv2-us.devo.com/search/query"
query="from siem.logtrust.collector.counter select tag limit 1"
curl -s -S -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $token" \
-d '{"query": "'"$query"'", "from": "now()@1d", "to": "now()", "mode":{"type":"avro"}}' $api --output -Example Response
The response is in binary format.
Objavro.schema?{"type":"record","name":"QueryAvroResponse","fields":[{"name":"tag","type":["null","string"],"default":null}]}|+??e<~z$??t?B>siem.logtrust.collector.counter|+??e<~z$??t?eu