Create and manage NRQL macros

Before you create a macro, review the macro permissions and the naming and expression rules below. A macro that doesn't follow these rules fails validation when you try to save it.

Macro rules and limitations

Important

Macros are visible to all users in your organization. Don't include sensitive or account-specific information when you create or update a macro.

Macro expressions must follow these rules:

Must be a valid NRQL expression or list of expressions
Must be 3,000 characters or less
Must be an expression, not a clause. For example, count(*) is valid, but SELECT count(*) isn't valid.
Must be a subquery wrapped in parentheses, not a standalone query. For example, (FROM Transaction SELECT uniques(userId)) is valid, but FROM Transaction SELECT uniques(userId) isn't valid.
Must return specific attributes, not an attribute list containing *
Valid expression examples:
count(*)
(1, 2, 3)
(FROM Transaction SELECT uniques(userId))

NRQL macros have the following limitations:

Alerts: Macros aren't supported in alert conditions.
Autocomplete: The query builder doesn't suggest macros or use macro expressions to refine suggestions.
Template variables: You can't use template variables within macros.
Nested macros: Macros can't be nested. A macro's expression can't contain a reference to another macro.
Region-specific: Macros are region-specific and can only be used within your organization's primary region.
Time clauses: Clauses related to time, including TIMESERIES, PREDICT, BY, USING, SINCE, UNTIL, and COMPARE WITH, don't support macros.

Access macros

In the New Relic platform, go to Administration > NRQL Macros. From this page, you can view, create, edit, and delete macros.

Create a macro

From the NRQL Macros page, create a macro by providing a unique name and an expression. Follow the naming and expression rules. Don't prefix the name with the $ character. For example, to save a WHERE clause condition, enter appName = 'ProductionApp' AND environment = 'prod' without the WHERE keyword.

After you create a macro, it appears in the NRQL Macros list. You can use it in any NRQL query throughout New Relic.

You can also create, update, and query macros programmatically using the NerdGraph API. Before creating or updating macros, review the naming rules, expression rules, and limitations.

To get started, go to the NerdGraph API explorer. If you need help using the NerdGraph API explorer, refer to the NerdGraph API explorer tutorial.

Use the entityManagementCreateNrqlMacro mutation:

mutation CreateMacro($name: String!, $expression: String!, $orgId: ID!) {
  entityManagementCreateNrqlMacro(
    nrqlMacroEntity: {
      expression: $expression
      name: $name
      scope: { type: ORGANIZATION, id: $orgId }
    }
  ) {
    entity {
      id
      name
      expression
    }
  }
}

Example variables:

{
  "name": "prod_filter",
  "expression": "(appName = 'ProductionApp' AND environment = 'prod')",
  "orgId": "your-organization-id"
}

To find your organization ID, refer to Find your organization or macro ID.

Use a macro in a query

To use a macro in your NRQL queries, type $ followed by the macro name in the query builder. For example, suppose you have a macro named prod_filter with the expression appName = 'ProductionApp' AND environment = 'prod'. You can use it in a query like this:

SELECT count(*) FROM Transaction WHERE $prod_filter SINCE 1 hour ago

When the query executes, New Relic replaces the macro with its expression:

SELECT count(*) FROM Transaction WHERE appName = 'ProductionApp' AND environment = 'prod' SINCE 1 hour ago

Tip

Wrap macro names containing special characters in backticks at query time. For example: $`my#Macro`.

Important

Macros are inlined prior to execution, which affects binary operator precedence. For example, a macro named five defined as 1 + 4 and used as $five * 3 evaluates to 13, not 15, because the expression becomes 1 + 4 * 3. To avoid this, wrap the expression in parentheses when you define the macro, as in (1 + 4), or wrap the macro in parentheses when you use it, as in ($five) * 3. Either approach correctly evaluates to 15.

The following examples show macros solving common query problems:

A query with multiple conditions, like this one, can be difficult to read and maintain:

SELECT * FROM Log WHERE entityGuid = '...' AND appId NOT IN (...) AND ...

Save the conditions after WHERE as a macro named macro1, and the query simplifies to:

SELECT * FROM Log WHERE $macro1

Dashboards with many widgets often share repeated query logic. For example, most widgets in a dashboard might use:

SELECT count(*) FROM Transaction WHERE http.statusCode NOT IN (400, 404)

If you save the WHERE condition as a macro named macro2, each widget's query looks like:

SELECT count(*) FROM Transaction WHERE $macro2

To exclude a test app from every widget, update the macro2 expression once, from http.statusCode NOT IN (400, 404) to http.statusCode NOT IN (400, 404) AND appId NOT IN (12345). Every widget that uses $macro2 reflects the change, and you don't have to edit each widget individually.

Data from different agents doesn't always use the same attribute name for the same concept. A host name, for example, can be ingested as host.name, hostName, or host_name depending on the source.

Save a macro named host_alias with the expression:

(host.name OR hostName OR host_name)

Then reference it in your queries:

FROM Log SELECT $host_alias

If another alias, such as host-name, comes up later, update the host_alias macro once and every query that uses it picks up the change.

Manage macros

Edit a macro

From the NRQL Macros page, select the macro and update its expression, following the expression rules.

You can also update a macro's expression programmatically using NerdGraph. Review the expression rules before you update it.

Use the entityManagementUpdateNrqlMacro mutation.

mutation UpdateMacro($expression: String!, $macroId: ID!) {
  entityManagementUpdateNrqlMacro(
    id: $macroId
    nrqlMacroEntity: { expression: $expression }
  ) {
    entity {
      id
      name
      expression
    }
  }
}

Example variables:

{
  "expression": "(appName = 'ProductionApp' AND environment = 'prod' AND region = 'us-east-1')",
  "macroId": "your-macro-id"
}

To find a macro's ID, refer to Find your organization or macro ID.

Important

When you edit a macro, all queries using that macro automatically use the updated version. Review your changes to make sure they don't break existing queries. Due to caching, there may be a slight delay before the update takes effect. You can't update a macro's name after creation. If you need to change the name, delete the macro and create a new one.

Find your organization or macro ID

query GetMacros($cursor: String) {
  actor {
    entityManagement {
      entitySearch(query: "type = 'NRQL_MACRO'", cursor: $cursor) {
        entities {
          ... on EntityManagementNrqlMacroEntity {
            id
            name
            expression
          }
        }
        nextCursor
      }
    }
  }
}

NRQL macros

Learn what NRQL macros are, what you can do with them, and who can use them.

NRQL reference

Explore NRQL syntax, clauses, and functions.

Macro rules and limitations

Important

Naming rules

Expression rules

Limitations

Access macros

Create a macro

Use a macro in a query

Tip

Important

Example: Simplify a query

Example: Update multiple dashboard widgets from one place

Example: Solve the attribute alias problem

Manage macros

Edit a macro

Important

Find your organization or macro ID

Find your organization ID

List all macros and their IDs

NRQL macros

NRQL reference

Create and manage NRQL macros

Macro rules and limitations .css-21sua1{background:none;border:none;width:0;padding:0;}

Important

Expression rules

Limitations

Access macros

Create a macro

Use a macro in a query

Tip

Important

Example: Simplify a query

Example: Update multiple dashboard widgets from one place

Example: Solve the attribute alias problem

Manage macros

Edit a macro

Important

Find your organization or macro ID

Find your organization ID

List all macros and their IDs

Related topics

NRQL macros

NRQL reference

Macro rules and limitations