Search API
The Search API is the primary endpoint for running queries for a specific repository or view. Using this API there are three basic methods for running queries:
This allows a filter or aggregate query to be exected with the expectation of a response with the corresponding result set. This form of query allows for the request and specified timespan to return the matching events.
A live search request returns information as a stream of data that will be updated as new events are ingested into the repository. Live queries return any immedaite results and then stream additional results after ingest, leaving the request open to stream additional data.
Query jobs allow a query to be submited and the results of the accessed without the client actively waiting for the response. Query jobs are useful if you have repetitive queries, as the results are returned when the job is polled.
For a list of the supported endpoint and methods, see the table below.
Table:
HTTP Method | URI | Description |
---|---|---|
POST | /api/v1/repositories/ | Submit a search query |
GET | /api/v1/repositories/ | Request the current query status and results |
POST | /api/v1/repositories/ | Create a query job |
DELETE | /api/v1/repositories/ | Delete a previously created query job |
The API returns the query information, but when the data is returned is determined by the type of the query being executed. The endpoint streams results as soon as they are calculated, but a basic type filter query returns the information as soon at is returned. For aggregate queries, the time of delivery changes. The following table shows the differences between these query types.
Query Type | Live Query | Standard Query |
---|---|---|
Filter | Streaming | Streaming |
Aggregate | Error — use query jobs | Streaming — result only at end |
The endpoint streams results for filter queries as they happen.
For aggregate standard queries, the result is not ready until the query has processed all events in the specified query interval. The request is blocked until the result is ready. It is at this point that LogScale sends the result back.
For aggregate live queries, this endpoint returns an error. What you want in this situation is to get a snapshot of the complete result set at certain points in time (fx every second), but the query end point does not support this behavior. Instead, you should use the query job endpoint and then poll the result when you need it. For more information on live queries, see polling query endpoint.