Skip to main content
Version: 5.0

Sidebar and Timeline API

SME Query Parameters

NameTypeDescriptionDefault value
calculateStatsbooleanFlag to calculate statistics and timeline.false
sidebarHandlerstringHandler for calculating the sidebar. Can be java or aggs. If java, the sidebar is returned with the query result; if aggs, it must be calculated via the Sidebar endpoint.java
timelineHandlerstringHandler for calculating the timeline. Can be java or aggs. If java, the timeline is returned with the query result; if aggs, it must be calculated via the Timeline endpoint.java

Validate

Performs validation of the query and returns whether aggregations can be used to compute the sidebar and timeline.

GET _sme/queryStats/validate

Params

NameDescription
queryThe query string URL encoded

Example request:

source tweets | sort num 
GET _sme/queryStats/validate?query=source%20tweets%20%7c%20sort%20num

Example response:

{
"sidebar": false,
"timeline": true
}
note

If the query includes multiple indices separated by commas, aggregation-based calculation of the sidebar and timeline is not possible.

Example request:

GET _sme/queryStats/validate?query=source%20tweets1,tweets2

Example response:

{
"sidebar": false,
"timeline": false
}

Timeline

GET _sme/queryStats/timeline

Params

NameDescription
startTimeQuery start time
endTimeQuery end time
timefieldName of the time field
queryquery string using URL encode

Example request:

source test_windows
GET _sme/queryStats/timeline?startTime=2022-04-01T10:49:16Z&endTime=2023-04-06T10:49:16Z&timefield=@timestamp&query=source%20test_windows

Example response:

{
"fields": [{
"@timestamp": "2022-04-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-05-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-06-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-07-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-08-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-09-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-10-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-11-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-12-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2023-01-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2023-02-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2023-03-01T00:00:00.000Z",
"count": 361718
}, {
"@timestamp": "2023-04-01T00:00:00.000Z",
"count": 115282
}
],
"total": 477000
}

Example request with search:

source test_windows | search event.code.keyword == 4776
GET _sme/queryStats/timeline?startTime=2022-04-01T10:49:16Z&endTime=2023-04-06T10:49:16Z&timefield=@timestamp&query=source%20test_windows|search%20event.code.keyword ==4776

Example response:

{
"fields": [{
"@timestamp": "2022-04-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-05-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-06-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-07-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-08-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-09-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-10-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-11-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2022-12-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2023-01-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2023-02-01T00:00:00.000Z",
"count": 0
}, {
"@timestamp": "2023-03-01T00:00:00.000Z",
"count": 304885
}, {
"@timestamp": "2023-04-01T00:00:00.000Z",
"count": 97115
}
],
"total": 402000
}

Returns the number of unique field values.

GET _sme/queryStats/sidebar

Params

NameDescription
startTimeStart time of the query
endTimeEnd time of the query
timefieldName of the time field
queryquery string using URL encode

Example request:

GET _sme/queryStats/sidebar?startTime=2022-02-03T10:49:16Z&endTime=2023-02-07T10:49:16Z&timefield=@timestamp&query=source%20tweets*

Example response:

[
{
"mymv": {
"unique_values": 2,
"type": "number"
}
}, {
"num": {
"unique_values": 13,
"type": "number"
}
}, {
"nickname": {
"unique_values": 5,
"type": "string"
}
}, {
"null_num2": {
"unique_values": 1,
"type": "number"
}
}, {
"null_num": {
"unique_values": 4,
"type": "number"
}
}, {
"Мак адрес": {
"unique_values": 2,
"type": "string"
}
}, {
"message": {
"type": "text"
}
}, {
"mvfield.qwe": {
"unique_values": 2,
"type": "number"
}
}, {
"mvfield.xdd.inner": {
"unique_values": 1,
"type": "number"
}
}, {
"boolfield": {
"unique_values": 1,
"type": "boolean"
}
}, {
"@timestamp": {
"unique_values": 5801,
"type": "string"
}
}, {
"message": {
"unique_values": 5,
"type": "string"
}
}, {
"mvfield.zxc": {
"unique_values": 3,
"type": "string"
}
}, {
"message2": {
"unique_values": 2,
"type": "string"
}
}
]

Example request with search:

source tweets | search message = "hello world"
GET _sme/queryStats/sidebar?startTime=2022-02-03T10:49:16Z&endTime=2023-02-07T10:49:16Z&timefield=@timestamp&query=source%20tweets2%20%7c%20search%20message%20%3d%20%22hello%20world%22

Example response:

[
{
"@timestamp": 5650
}, {
"message": 1
}, {
"num": 11
}, {
"nickname": 1
}
]

Field

Returns field statistics: the number of unique values, the number of documents containing the field, the field type, and up to 20 most frequent values along with the number of documents containing each value and its percentage relative to the total document count.

GET _sme/queryStats/field

Params

NameDescription
startTimeStart time of the query
endTimeEnd time of the query
timefieldName of the time field
queryquery string using URL encode
fieldNameName of the field to compute statistics for

Example request for a numeric field:

GET _sme/queryStats/field?startTime=2022-02-03T10:49:16Z&endTime=2023-02-07T10:49:16Z&timefield=@timestamp&fieldName=num&query=source%20tweets2

Example response:

{
"num": {
"unique_values": 11,
"values": [
{
"count": 1023,
"percent": 9.82,
"value": 17
}, {
"count": 992,
"percent": 9.52,
"value": 15
}, {
"count": 963,
"percent": 9.24,
"value": 14
}, {
"count": 960,
"percent": 9.21,
"value": 10
}, {
"count": 959,
"percent": 9.2,
"value": 11
}, {
"count": 941,
"percent": 9.03,
"value": 12
}, {
"count": 928,
"percent": 8.91,
"value": 13
}, {
"count": 919,
"percent": 8.82,
"value": 20
}, {
"count": 915,
"percent": 8.78,
"value": 16
}, {
"count": 914,
"percent": 8.77,
"value": 19
}, {
"count": 902,
"percent": 8.66,
"value": 18
}
],
"count": 10416,
"type": "number"
}
}

Example request for a keyword field:

GET _sme/queryStats/field?startTime=2022-02-03T10:49:16Z&endTime=2023-02-07T10:49:16Z&timefield=@timestamp&fieldName=message&query=source%20tweets*

Example response:

{
"message": {
"unique_values": 5,
"values": [
{
"count": 10415,
"percent": 99.84,
"value": "hello world"
}, {
"count": 8,
"percent": 0.08,
"value": "hello, user"
}, {
"count": 2,
"percent": 0.02,
"value": "hello from tweets2"
}, {
"count": 1,
"percent": 0.01,
"value": "4"
}, {
"count": 1,
"percent": 0.01,
"value": "hello, wolrd"
}
],
"count": 10427,
"type": "string"
}
}