Features GraphQL API

GraphQL features consist of datasets, filtering, sorting, and pagination. The features provide easy access to your data, and using and combining the available features creates more personalized and specific queries to request the exact information you need.

The next sections will detail each available feature of GraphQL and how to use them.

Datasets

Azion GraphQL API uses defined datasets to indicate what requests you can run through queries and fetches data from Real-Time Metrics and Real-Time Events. They consist of organized tables informing your data.

Find each available dataset and what they request next.

Real-Time Metrics GraphQL API

Real-Time Events GraphQL API

Billing GraphQL API

Accounting GraphQL API

You can request both the raw model, using the Events datasets, and the aggregated model, using the Metrics datasets.

Filtering

With filtering parameters, responses returned by your queries can be more accurate to your set of data. You can use filtering with any available field in the dataset you’re consulting.

As requesting complex or a large amount of data can cause responses to get noisy and complicate its use, filtering queries helps with getting exact and direct data from your requests. For example, if you’re using the following query to request httpMetrics:

query HttpQuery {
  httpMetrics(
    limit: 10
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
    }
  )
  {
    ts
    geolocCountryName
  }
}

You can filter the query by requesting data specific to the geolocCountryName field:

query HttpQuery {
  httpMetrics(
    limit: 10
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
      geolocCountryName: "Brazil"
    }
  )
  {
    ts
    geolocCountryName
  }
}

You can feel free to update your request to use a field of your interest within the fields of the dataset you’re consulting.

You can also filter using multiple AND and OR parameters. Make sure you define all the fields you’re filtering for inside the parameter, like in the following example:

query totalImagesProcessedRequests {
  imagesProcessedMetrics(
    aggregate: {sum: requests}
    limit: 100
    filter: {
      tsRange: {begin:"2023-03-20T19:52:00", end:"2023-03-20T20:52:00"}
      or: {
          status:304
          statusRange: {begin: 200, end: 299}
      }
    }
    groupBy:[ts]
    orderBy:[ts_ASC]
  )
  {
    ts
    sum
  }
}

Sorting

The sorting feature lets you organize and sort the received data of a dataset according to the event’s order. For example, if you’re receiving the host field data as a response to your API request, you can sort the data to receive it in:

• An ascending order (ASC)
• A descending order (DESC)

Whenever you use the orderBy property, you must add either the ASC or the DESC specification.

For example, to use the ascending order sorting feature, you need to add orderBy in your query and the field you want to sort + ASC:

{
    orderBy: [host_ASC]
}

To sort the data according to a descending order (DESC), you need to add the field you want to sort + DESC:

{
    orderBy: [ts_DESC]
}

Say you’re using this query with DESC:

query SumBytesSentByHost {
  httpMetrics(
    limit: 1000
    filter: {
      tsRange: {begin:"2023-01-01T17:03:00", end:"2023-06-01T18:05:00"}
    }
    aggregate: {sum: bytesSent}
    groupBy: [host]
    orderBy: [sum_DESC]
  )
  {
    host
    sum
  }
}

You’ll get a response similar to this:

{
    "data": {
        "httpMetrics": [
            {
                "host": "g1sdetynmxe0ao.map.azionedge.net",
                "sum": 606226
            },
            {
                "host": "uaykhefjdk9or.map.azionedge.net",
                "sum": 583059
            },
            {
                "host": "wz0ywpod397zk.map.azionedge.net",
                "sum": 567633
            },
            {
                "host": "zi1435nbhec7.map.azionedge.net",
                "sum": 96002
            }
        ]
    }
}

And if you’re using this query with ASC:

query AvgRequesTimeByHost {
  httpMetrics(
    limit: 1000
    filter: {
      tsRange: {begin:"2023-01-01T17:03:00", end:"2023-06-01T18:05:00"}
    }
    aggregate: {avg:requestTime}
    groupBy: [ts, host]
    orderBy: [avg_ASC]
  )
  {
    ts
    host
    avg
  }
}

You’ll get a response similar to this:

{
    "data": {
        "httpMetrics": [
            {
                "ts": "2023-04-21T00:00:00Z",
                "host": "zipo145nbhc7.map.azionedge.net",
                "avg": 0.04871428571428572
            },
            {
                "ts": "2023-04-13T00:00:00Z",
                "host": "g1snmxepa0ao.map.azionedge.net",
                "avg": 0.561
            },
            {
                "ts": "2023-04-11T00:00:00Z",
                "host": "g1syinmxe2ao.map.azionedge.net",
                "avg": 4.101833333333333
            },
            {
                "ts": "2023-04-11T00:00:00Z",
                "host": "wz1yd307zk.map.azionedge.net",
                "avg": 8.705666666666668
            },
            {
                "ts": "2023-05-22T00:00:00Z",
                "host": "uaifjdk6or.map.azionedge.net",
                "avg": 31.493818181818185
            }
        ]
    }
}

Pagination

Pagination is a feature designed to help you decide where you want your results to begin from and how many results you want to see. Currently, Azion GraphQL API uses offset and limit pagination to provide the feature.

Using pagination can be useful when you get a large number of data in response to your API request. You can use the feature by setting offsets and limits. This way, the API knows it needs to return data within the specific range you’ve set.

The offsets parameter sets the number of records you want to skip in your data response, and the limits parameter sets the number of results you want to receive.

See the following example on how to set offset and limit parameters:

query HttpQuery {
  httpMetrics(
    offset: 15
    limit: 30
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
    }
  )
  {
    ts
    requestMethod
  }
}

The offset is set for 15, meaning your response will start with the 16th result, and the limit is set for 30, meaning your response will give you a total of 30 results. In this case, you’ll receive a response from the 16th result until the 45th result.

Resampling

Available for:

The Resample feature allows you to resample your data to display a smaller amount of data points being exhibited on charts. It works according to the rule you pass in the function field.

You can use it to complement the limit you add to your query, as the default data points in charts may not be the ideal number for your analysis.

The query must contain the function field and its properties as well as have the groupBy field containing the ts variable.

By specifying sum, you’ll receive a total sum of the data points in that interval. By specifying mean, you’ll receive a calculation of sum + division.

See an example:

query httpRequestCount {
  httpMetrics(
    limit: 10000,
    resample: {
      function: sum
      points: 100
    }
    filter: {
      tsRange: {
        begin:"2023-08-16T20:17:00", end:"2023-09-17T21:16:00"
      }
    },
    groupBy: [ts]
    orderBy: [ts_ASC]
  )
  {
    ts
     dataTransferredIn
    dataTransferredOut
    dataTransferredTotal
  }
}

Say your original query result, without resampling, returned 1,456 logs. Since you queried for a resample of 100 points, the calculation the API does is 1,456 // 100 = 14,56 minutes interval. Since the API only uses integers (whole numbers), it’ll round up the result to an interval of 14 minutes between each point returned.

However, the API doesn’t discard the remaining 0,56 minutes. It keeps adding them until the number becomes an integer and them sums it to the original requested points.

In the example used, it returned the original 100 requested points plus the reamaining 4 points, resulting in a total of 104 points for the resampled query.