Skip to content

Latest commit

 

History

History
384 lines (327 loc) · 13.4 KB

queries.mdx

File metadata and controls

384 lines (327 loc) · 13.4 KB
Raw
title description meta_tags namespace permalink menu_namespace meta_tag_robots_no_index
Queries GraphQL API
Queries are the starting point to begin consulting information as you use a query to request information from a database.
graphql, api, azion, query
documentation_graphql_queries
/documentation/devtools/graphql-api/queries/
graphqlMenu
false

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.

:::tip See all GraphQL API limits to make sure your query is valid. :::

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.

:::tip You can also use the Top X query feature with the Real-Time Events GraphQL API. It helps to visualize how resources and tools are being used and provide a more detailed analysis of certain conditions that are either more or less commonly used. For example, you can query for “Top 10 Hosts” or “Top 10 Status Codes”.

Find out more on How to select Top X queries with GraphQL API. :::

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

import ContributorList from '~/components/ContributorList.astro'

Contributors Contributor