As a New Relic user, you may find yourself writing complex NRQL queries repeatedly across dashboards. Remembering and rewriting multiple lines of a query each time is time-consuming and prone to errors. When your data changes and queries need to be adjusted, you have to manually update each instance of that query across your organization, which becomes a significant maintenance burden.
NRQL macros solve this problem by letting you save a NRQL expression as a reusable, named shortcut. You reference a macro in a query with the $ symbol followed by its name, for example $prod_filter, and New Relic substitutes the saved expression before the query runs. You can use macros in the query builder and in dashboards.
What you can do with macros
You can use NRQL macros to:
- Create reusable expressions: Convert an expression of your NRQL query into a macro with a descriptive name, so you don't have to retype or remember the full expression each time.
- Reuse expressions across accounts: Macros are organization-level entities. Any account in your organization can use a macro without redefining it, and all users with the appropriate role can access and use all macros created within the organization.
- Update queries centrally: When you edit a macro, all queries using that macro automatically reflect the change, without you having to find and update every query individually.
Prerequisites
To use NRQL macros, you need:
- Account access: Access to an account in the organization where you want to use macros. Macros are organization-level entities, so once created, they're available across every account in your organization.
- NRQL knowledge: Basic knowledge of NRQL syntax, since a macro's expression is a NRQL expression.
Macro permissions
Before you create or use macros, it's important to understand how permissions work and who has access to your macros.
Organization association
Every macro is a resource that belongs to the organization in which it was created. This association is permanent and cannot be changed. Macros cannot be shared between different organizations. If the organization is deleted, the macro is deleted as well. If a user moves to a different organization, they will not have access to macros from their previous organization.
Current permissions model
New Relic macros use built-in roles with CRUD capabilities to control access. Macro access is organization-level only, set by an admin.
Organization-level permissions
These are granted by default system roles in the New Relic admin UI.
Role | Capabilities | What it allows |
|---|---|---|
Organization product admin or Organization manager |
| Create, read, update, and delete any macro in the organization |
Organization read only |
| Read any macro in the organization |
Next steps
To create, use, or manage macros, refer to Create and manage macros.