NerdGraph tutorial: Run NRQL queries asynchronously

You can use NerdGraph to run NRQL queries. In addition, you can also use NerdGraph to run an asynchronous NRQL query. Asynchronous queries run in the background, and you can make follow-up requests to retrieve query results or the query status. This type of query avoids a query being interrupted by issues like browser timeouts or HTTP connection timeouts. It's especially useful for running queries that may take a long time to complete.

Requirements

If you have Data Plus, you can run asynchronous queries with a 10-minute max duration using either NerdGraph or the query builder UI.

For more on query limits, see Query limits.

Asynchronous query example

Here's an example of an asynchronous query NerdGraph call. The async: true is what makes the query asynchronous. This query will return results if it completes within the default timeout of 5 seconds; otherwise it will return queryProgress data for use in follow-up queries to the nrqlQueryProgress field.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      nrql(query: "SELECT * FROM Transaction", async: true) {
        results
        queryProgress {
          queryId
          completed
          retryAfter
          retryDeadline
          resultExpiration
        }
      }
    }
  }
}

Getting the results or status of an async query

If your query exceeds the default timeout, it will return a query ID. You can take that ID and run a second query to get the query results, if it's finished, or else the status of that query.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      nrqlQueryProgress(queryId: "YOUR_QUERY_ID") {
        results
        queryProgress {
          queryId
          completed
          retryAfter
          retryDeadline
          resultExpiration
        }
      }
    }
  }
}

Some important details about this query:

• The queryId comes from the queryProgress data returned by the original asynchronous query.
• The account argument must match the account argument from the original query.
• This query will return results if asynchronous execution has completed; otherwise it will return queryProgress data.
• The query can be repeated verbatim until results or an error are returned.

Cancel an async query

You can cancel an asynchronous query by using the nrqlCancelQuery mutation. This mutation takes the queryId of the query you want to cancel. It will either return an ACCEPTED status, or REJECTED status with a reason for rejection.

mutation {
  nrqlCancelQuery(queryId: "YOUR_QUERY_ID") {
    queryId
    requestStatus
    rejectionReason
  }
}