API-query

API-query is a mechanism for executing queries to the internal data storage of Search Anywhere Framework, operating based on Domain-Specific Language (DSL) and allowing you to retrieve, filter, and aggregate data in the form of Search Anywhere Framework Data Storage documents.

The API-query functionality can be used in different ways, for example, through curl requests or from the Search Anywhere Framework interface in the Developer Console (Main Menu - System Parameters - Developer Console). This article provides examples using the latter approach.

Query Structure

API-query requests are built according to a unified structure that includes the following attributes:

• query — the main search query section that defines document selection criteria
• Query Type — specifies the search format, for example: match, term, range, bool, and other DSL operators
• Field — the name of the document field by which the query is executed
• Search Value — the value processed in the query
• Combination Logic — additional constructs, such as must and must_not, used to compose query logic conditions
• Accuracy Parameters — matching settings such as fuzziness, operator, or boost that clarify search behavior

The query can be supplemented with clarifying parameters for processed data, such as size or from.

Below is the main template used in most cases:

GET <index>/_search
{
  "query": {
    "<query_type>": {
      "<field>": "<value>"
    }
  },
  "size": <number_of_documents>,
  "from": <pagination_offset>
}

Query example:

GET test_node_stats/_search
{
  "query": {
    "term": {
      "event_type": "alert"
    }
  },
  "size": 2
}

Example output

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 5,
      "relation": "eq"
    },
    "max_score": 0.24116206,
    "hits": [
      {
        "_index": "test_node_stats",
        "_id": "1",
        "_score": 0.24116206,
        "_source": {
          "event_type": "alert",
          "severity": "high",
          "host": "sm-node-01",
          "timestamp": "2025-12-01T10:00:00Z",
          "message": "CPU usage is above threshold"
        }
      },
      {
        "_index": "test_node_stats",
        "_id": "2",
        "_score": 0.24116206,
        "_source": {
          "event_type": "alert",
          "severity": "medium",
          "host": "sm-node-02",
          "timestamp": "2025-12-01T10:05:00Z",
          "message": "Memory usage warning"
        }
      }
    ]
  }
}

Common Usage Scenarios

Filtering by multiple conditions (bool query):

GET test_node_stats/_search
{
  "query": {
    "bool": {
      "must": [
        { "term": { "event_type": "alert" } },
        { "term": { "severity": "high" } }
      ]
    }
  }
}

Example output

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 1.2707815,
    "hits": [
      {
        "_index": "test_node_stats",
        "_id": "1",
        "_score": 1.2707815,
        "_source": {
          "event_type": "alert",
          "severity": "high",
          "host": "sm-node-01",
          "timestamp": "2025-12-01T10:00:00Z",
          "message": "CPU usage is above threshold"
        }
      },
      {
        "_index": "test_node_stats",
        "_id": "3",
        "_score": 1.2707815,
        "_source": {
          "event_type": "alert",
          "severity": "high",
          "host": "sm-node-03",
          "timestamp": "2025-12-01T10:10:00Z",
          "message": "Disk space is low"
        }
      }
    ]
  }
}

Data aggregation:

GET test_node_stats/_search
{
  "size": 0,
  "aggs": {
    "by_severity": {
      "terms": {
        "field": "severity"
      }
    }
  }
}

Example output

{
  "took": 6,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 6,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "by_severity": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "high",
          "doc_count": 2
        },
        {
          "key": "low",
          "doc_count": 2
        },
        {
          "key": "critical",
          "doc_count": 1
        },
        {
          "key": "medium",
          "doc_count": 1
        }
      ]
    }
  }
}

Aggregation with time filtering:

GET test_node_stats/_search
{
  "size": 0,
  "query": {
    "range": {
      "timestamp": {
        "gte": "2025-12-01T00:00:00Z",
        "lte": "2025-12-01T23:59:59Z"
      }
    }
  },
  "aggs": {
    "alerts_count": {
      "terms": {
        "field": "event_type"
      }
    }
  }
}

Example output

{
  "took": 10,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 6,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "alerts_count": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "alert",
          "doc_count": 5
        },
        {
          "key": "metric",
          "doc_count": 1
        }
      ]
    }
  }
}

Pagination

The size and from parameters, mentioned in the main query template, are used for paginated data retrieval.

• size — the number of documents per page
• from — the number of documents to skip before returning results

First page example:

GET test_node_stats/_search
{
  "query": {
    "term": {
      "event_type": "alert"
    }
  },
  "size": 2,
  "from": 0
}

Example output

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 5,
      "relation": "eq"
    },
    "max_score": 0.24116206,
    "hits": [
      {
        "_index": "test_node_stats",
        "_id": "1",
        "_score": 0.24116206,
        "_source": {
          "event_type": "alert",
          "severity": "high",
          "host": "sm-node-01",
          "timestamp": "2025-12-01T10:00:00Z",
          "message": "CPU usage is above threshold"
        }
      },
      {
        "_index": "test_node_stats",
        "_id": "2",
        "_score": 0.24116206,
        "_source": {
          "event_type": "alert",
          "severity": "medium",
          "host": "sm-node-02",
          "timestamp": "2025-12-01T10:05:00Z",
          "message": "Memory usage warning"
        }
      }
    ]
  }
}

Second page example:

GET test_node_stats/_search
{
  "query": {
    "term": {
      "event_type": "alert"
    }
  },
  "size": 2,
  "from": 2
}

Example output

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 5,
      "relation": "eq"
    },
    "max_score": 0.24116206,
    "hits": [
      {
        "_index": "test_node_stats",
        "_id": "3",
        "_score": 0.24116206,
        "_source": {
          "event_type": "alert",
          "severity": "high",
          "host": "sm-node-03",
          "timestamp": "2025-12-01T10:10:00Z",
          "message": "Disk space is low"
        }
      },
      {
        "_index": "test_node_stats",
        "_id": "5",
        "_score": 0.24116206,
        "_source": {
          "event_type": "alert",
          "severity": "low",
          "host": "sm-node-04",
          "timestamp": "2025-12-01T10:20:00Z",
          "message": "Service response time increased"
        }
      }
    ]
  }
}

To ensure that results on different pages don't change order between requests, it's recommended to set sorting:

GET test_node_stats/_search
{
  "query": {
    "term": {
      "event_type": "alert"
    }
  },
  "sort": [
    { "timestamp": { "order": "asc" } }
  ],
  "size": 2,
  "from": 2
}

Example output

{
  "took": 9,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 5,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [
      {
        "_index": "test_node_stats",
        "_id": "3",
        "_score": null,
        "_source": {
          "event_type": "alert",
          "severity": "high",
          "host": "sm-node-03",
          "timestamp": "2025-12-01T10:10:00Z",
          "message": "Disk space is low"
        },
        "sort": [
          1764583800000
        ]
      },
      {
        "_index": "test_node_stats",
        "_id": "5",
        "_score": null,
        "_source": {
          "event_type": "alert",
          "severity": "low",
          "host": "sm-node-04",
          "timestamp": "2025-12-01T10:20:00Z",
          "message": "Service response time increased"
        },
        "sort": [
          1764584400000
        ]
      }
    ]
  }
}