Queries GraphQL API

Queries are the starting point to begin consulting information as you use a query to request information from a database. The GraphQL API relies on queries to fetch values and send the requested data as a response with a similar format in a JSON file.

The use of queries enables requesting and fetching specific data. This means you can get a response to your request even with a small query if you don’t want to see data that isn’t essential at that moment. Using queries also means you get faster responses, as the GraphQL API doesn’t need to fetch unnecessary amount of data.

By using queries, your requests and responses also become more organized. Due to GraphQL’s ability to adapt, you can make several calls to the API and still receive only the data you requested in an organized JSON result.

You can use queries for two types of data:

Raw, using the Real-Time Events GraphQL API.
Aggregated, using the Real-Time Metrics GraphQL API.

For each type of data, you’ll query with different GraphQL datasets.

Raw data

Raw data exhibit your event records without any further processing. They provide detailed information and are helpful when performing deep-dive investigations.

Here’s an example of a raw Real-Time Events GraphQL query:

query HttpQuery {
  httpEvents(
    limit: 10,
    filter: {
      tsRange: {begin:"2023-02-14T10:10:10", end:"2023-02-15T10:10:10"}
    }
    orderBy: [ts_ASC]
  )
  {
    ts
    remoteAddress
    requestUri
    stacktrace
  }
}

And the response to the query:

{
  "data": {
    "httpEvents": [
      {
        "ts": "2023-08-08T10:10:10Z",
        "remoteAddress": "xx.xx.xxx.xxx",
        "requestUri": "/hello.index/verify",
        "stacktrace": "-"
      },
      {
        "ts": "2023-08-08T10:10:10Z",
        "remoteAddress": "yyy.y.yyy.yyyy",
        "requestUri": "/hello.index/welcome",
        "stacktrace": "-"
      },
      {
        "ts": "2023-08-08T10:10:10Z",
        "remoteAddress": "zzz.zzz.zz.zz",
        "requestUri": "/api/verify=pPrt%20",
        "stacktrace": "-"
      },
      {
        "ts": "2023-08-08T10:10:10Z",
        "remoteAddress": "xyz.xy.zxy.zxy",
        "requestUri": "/helloaspx.index/search",
        "stacktrace": "-"
      },
      {
        "ts": "2023-08-08T10:10:10Z",
        "remoteAddress": "zyx.z.yxz.yxz",
        "requestUri": "/hello.css/analysis",
        "stacktrace": "-"
      }
    ]
  }
}

To query raw data, it’s mandatory to inform:

A time range interval for all datasets, using either tsRange or tsGt + tsLt.
Which consulted data should be exhibited. On the presented example, the ts, remoteAddress, requestUri, and stacktrace fields were used.

Aggregated data

Aggregated data are a type of structured data that have been clustered. They go through modifications to allow a better analytic processing seeking a segmented analysis, making it easier to visualize even great amount of data over a larger period of time.

Here’s an example of an aggregated Real-Time Metrics GraphQL query:

query HttpQuery {
  httpMetrics(
    limit: 10,
    filter: {
      tsRange: {begin:"2022-03-21T10:10:10", end:"2023-09-08T10:10:10"}
    }
    aggregate: {sum: requestTime}
    groupBy: [ts]
    orderBy: [ts_ASC]
  )
  {
    ts
    sum
  }
}

And the response to the query:

{
    "data": {
        "httpMetrics": [
            {
                "ts": "2022-11-29T00:00:00Z",
                "sum": 0.529
            },
            {
                "ts": "2022-11-30T00:00:00Z",
                "sum": 0.044
            },
            {
                "ts": "2023-04-11T00:00:00Z",
                "sum": 50.728
            },
            {
                "ts": "2023-04-13T00:00:00Z",
                "sum": 1.683
            },
            {
                "ts": "2023-04-21T00:00:00Z",
                "sum": 0.341
            },
            {
                "ts": "2023-05-22T00:00:00Z",
                "sum": 346.432
            },
            {
                "ts": "2023-06-05T00:00:00Z",
                "sum": 23.934
            },
            {
                "ts": "2023-06-06T00:00:00Z",
                "sum": 64.223
            },
            {
                "ts": "2023-06-07T00:00:00Z",
                "sum": 12.818
            },
            {
                "ts": "2023-06-09T00:00:00Z",
                "sum": 4.073
            }
        ]
    }
}

To query aggregated data, it’s mandatory to inform:

A time range interval for all datasets, using either tsRange or tsGt + tsLt.
The fields whose information you want to group, using groupBy.
Which consulted data should be shown. On the presented example, the ts and sum fields were used, in which sum represents the response of the requestTime aggregation.

There are also a few options that you must inform through the aggregate field in your query:

Identifier	Description
Count	Determines the total value of records meeting a specific condition.
Sum	Returns the sum of the entry values of a column or expression.
Max	Returns the maximum value of a determined field of a table according to the established selection criteria.
Min	Returns the minimum value of a determined field of a table according to the established selection criteria.
Avg	Calculates the arithmetic mean of a set of values in a specific field being consulted.
Rate	Used for the imagesProcessed dataset. Obtains the rate of images being processed by second while using Image Processor.

Find more information and examples in the How to query aggregated data with GraphQL API guide.

You can run a request with one of each of the available options: count, sum, max, min, avg, and rate, as long as each option is only used once and each operator aggregates only one dataset field at a time. See the following example:

aggregate: {
    count: rows,
    sum: bytesSent,
    avg: requestTime,
    max: requestLength,
    min: missedData,
    rate: requestTime
}

With the aggregated model, you’ll receive data according to a time range defined through an adaptive resolver. There are three possible intervals to fetch your results: minute, hour, and day.

Interval	Description
Minute	Used for queries in the interval of up to 3 days.
Hour	Used for queries in the interval of 3 and 60 days.
Day	Used for queries in the interval of over 60 days.

Financial data

Financial data exhibit information of two types: accounted data and billed data.

Here’s an example of a financial data Accounting GraphQL query:

query accountedData {
  accountingDetail(
    limit: 10,
    filter: {
      periodFrom: "2022-06-01",
      periodTo: "2022-06-30"
    }
  )
  {
    accounted
    clientId
    metricSlug
    periodFrom
    periodTo
  }
}

And the response to the query:

{
  "data": {
    "accountingDetail": [
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "load_balancer_data_transferred",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "load_balancer_data_transferred",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "load_balancer_data_transferred",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "load_balancer_data_transferred",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "load_balancer_data_transferred",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "load_balancer_data_transferred",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "compute_time",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 139.63,
        "clientId": "8437r",
        "metricSlug": "compute_time",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "compute_time",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      },
      {
        "accounted": 0,
        "clientId": "8437r",
        "metricSlug": "compute_time",
        "periodFrom": "2022-06-01",
        "periodTo": "2022-06-30"
      }
    ]
  }
}

To query financial data, it’s mandatory to inform:

Which consulted data should be exhibited. On the presented example, the accounted, clientId, metricSlug, periodFrom, and periodTo fields were used.

Different from a raw and an aggregated query, you’ll use the periodFrom and periodTo fields to filter a time range.

Operators

Operators are special keys that allow you to customize your query to perform from basic to more complex logical comparisons. You can use them for both the Real-Time Metrics GraphQL API and the Real-Time Events GraphQL API.

Depending on the operator you use, you’ll change the condition you’re querying for and receive different results. The following operators can be used with GraphQL:

Key	Description	GraphQL Operator
eq	Consults data that are an exact match, equal, to the specified value.	`Eq`
ne	Consults data that are different, not equal, from the specified value.	`Ne`
like	Consults data that are like the specified value, with case-sensitive values.	`Like`
ilike	Consults data that are insensitive like the specified value, with case-insensitive values.	`Ilike`
is_null	Consults data that are null or aren’t null compared to the specified value, using `true` or `false`.	`IsNull`
in	Consults data contained in a given list, in, the specified value.	`In`
not_in	Consults data that aren’t in a given list, not in, the specified value.	`NotIn`
lt	Consults data with values smaller than, less than, the specified value.	`Lt`
lte	Consults data with values smaller or equal, less than or equal, to the specified value.	`Lte`
gt	Consults data with values larger, greater than, the specified value.	`Gt`
gte	Consults data with values larger or equal, greater than or equal, to the specified value.	`Gte`
range	Consults data that are part of the range of the specified values.	`Range`

If you’re using the Like and Ilike operators, you must also pass the identifier % inside the field in the position you want to use:

Identifier position	Description	Example
End	Any string that starts with the characters.	”Braz%“
Beginning	Any string that ends with the characters.	”%ao Paulo”
End and beginning	Any string that contains the characters.	”%ttp%“

Here are a few examples of fields with an operator:

Operator	Example	Description
Eq	upstreamCacheStatusEq: “HIT”	Searches everything that matches exactly the `HIT` value in the upstreamCacheStatus field.
Ne	geolocCountryNameNe: “Brazil”	Searches everything that isn’t `Brazil` in the geolocCountryName field.
Like	hostLike: “%mysite.com%“	Searches everything for hosts with the particular `mysite.com` pattern and is case-sensitive.
Ilike	hostIlike: “%mysite.com%“	Searches everything for hosts with the particular `mysite.com` pattern and is case-insensitive.

Depending on the type of field of a dataset you’re querying for, you’ll get to use different operators:

Field type	Possible operators
String	`Eq`, `Ne`, `Like`, `Ilike`, `In`, `NotIn`, `IsNull`
Integer, Float, DateTime	`Eq`, `Lt`, `Lte`, `Gt`, `Gte`, `Ne`, `In`, `NotIn`, `IsNull`, `Range`

Discover the essential role of operators in GraphQL queries. Watch the video below: