API SME

Search Queries

API for executing a search query in Search Anywhere Framework Language (SAFL): GET _sme.

Parameters

Name	Type	Description
query	string	SAFL query
dtStart	date-time	Start of the time range in YYYY-MM-DDThh:mm:ssZ format
dtEnd	date-time	End of the time range in YYYY-MM-DDThh:mm:ssZ format
dtFieldName	string	Name of the time field (usually @timestamp)
calculateExecutionCost	string	See Sidebar and Timeline API
calculateStats	boolean	See Sidebar and Timeline API
sidebarHandler	string	See Sidebar and Timeline API
timelineHandler	string	See Sidebar and Timeline API

If the query parameter is too long, submit the parameters in the HTTP request body in JSON format and use the POST method:

POST _sme

Request Body Parameters

Example request body for POST:

{
    "dtStart": "2022-12-15T07:00:00Z",
    "dtEnd": "2023-02-09T13:30:00Z",
    "query": "source internal_audit-* qsize=9000",
    "dtFieldName": "@timestamp"
}

---

Example of Running a Search Query

POST _sme
{
    "dtStart": "2022-12-15T07:00:00Z",
    "dtEnd": "2023-02-09T13:30:00Z",
    "query": "source internal_audit-* qsize=9000",
    "dtFieldName": "@timestamp"
}

---

Query Execution Statistics

To enable execution statistics, set calculateExecutionCost to ON.

POST /_sme
{
  "query": "source internal_audit-* qsize=100",
  "dtStart": "2026-01-01T00:00:00Z",
  "dtEnd": "2026-01-02T00:00:00Z",
  "dtFieldName": "@timestamp",
  "calculateExecutionCost": "ON"
}

The response contains the following blocks in service_data:

• execution_cost — stage durations, document counts, and nested stages
• storage_summary — summary of storage accesses
• storage_resource_usage — ClickHouse resource metrics and information about their availability
• clickhouse_telemetry_context_id — identifier for refreshing ClickHouse metrics, if refresh is available

Example execution_cost item:

{
  "duration_sec": 0.25,
  "component": "source",
  "command_query": "source internal_audit-* qsize=100",
  "input_count": 0,
  "output_count": 100,
  "processing_bytes": null,
  "internal_execution_cost": []
}

The fields depend on the stage being executed. A null value means that the metric is unavailable.

Refreshing ClickHouse Metrics

Pass the value of service_data.clickhouse_telemetry_context_id:

POST /_sme/clickhouse/telemetry
{
  "clickhouse_telemetry_context_id": "<identifier from the search response>"
}

The response contains storage_resource_usage, a warnings array, and, if available, storage_summary and clickhouse_telemetry_context_id.

Field	Purpose
storage_resource_usage.message	Explanation of the collection status
storage_resource_usage.error_code	Stable status code
warnings	Warnings detected during collection
clickhouse_telemetry_context_id	Identifier for the next refresh, if available

Code	Status
CLICKHOUSE_NOT_COLLECTED	Server-side metrics have not been collected yet
CLICKHOUSE_RECORDS_PENDING	ClickHouse log records are pending
CLICKHOUSE_TELEMETRY_INCOMPLETE	Some metrics are available
CLICKHOUSE_TELEMETRY_UNAVAILABLE	Metrics cannot be retrieved

A status code does not necessarily indicate an error. Telemetry is collected from available nodes. When collection succeeds, message and error_code are not populated. If the code is unknown, review the text in message.

An unavailable context returns HTTP 200 with an explanation in storage_resource_usage.message. If the context identifier is missing, metrics cannot be refreshed using that response.

Connection Setup

Official ClickHouse documentation:

• system.query_log table — metric fields, logging configuration, and write interval
• Granting privileges with GRANT — SELECT privileges for the log and access to remote sources, including REMOTE; syntax depends on the ClickHouse server settings

Collection requires the system.query_log log to be configured and read privileges for that log on the ClickHouse nodes in use. Access through clusterAllReplicas also requires remote read privileges. The privileges must be available to the role set used by the connection.

In the system connection, the cluster_name field specifies the ClickHouse cluster name. If it is not set, default is used. The name must match the ClickHouse configuration. An administrator configures the connection and privileges.

---

License Check

To check the license, run the following request:

GET _sme/getLicense