Version: 5.0

Sidebar and Timeline API

SME Query Parameters

Name	Type	Description	Default value
`calculateStats`	boolean	Flag to calculate statistics and timeline.	false
`sidebarHandler`	string	Handler 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
`timelineHandler`	string	Handler 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

Name	Description
`query`	The 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

Name	Description
`startTime`	Query start time
`endTime`	Query end time
`timefield`	Name of the time field
`query`	`query` 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

Name	Description
`startTime`	Start time of the query
`endTime`	End time of the query
`timefield`	Name of the time field
`query`	`query` 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"
    }
  }, {
    "Mac address": {
      "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

Name	Description
`startTime`	Start time of the query
`endTime`	End time of the query
`timefield`	Name of the time field
`query`	`query` string using URL encode
`fieldName`	Name of the field for calculating statistics

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"
  }
}

SME Query Parameters​

Validate​

Params​

Timeline​

Params​

Sidebar​

Params​

Field​

Params​

SME Query Parameters

Validate

Params

Timeline

Params

Sidebar

Params

Field

Params