---
title: NRQL macros
source: https://docs.newrelic.com/docs/nrql/nrql-macros/nrql-macros-overview
---

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](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/introduction-query-builder/) and in dashboards.

## What you can do with macros [#macros-features]

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 [#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](https://docs.newrelic.com/docs/nrql/get-started/introduction-nrql-how-nrql-works/), since a macro's expression is a NRQL expression.

## Macro permissions [#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 [#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 [#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 [#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** | `nrql_macros.create.macro` `nrql_macros.read.macro` `nrql_macros.update.macro` `nrql_macros.delete.macro` | Create, read, update, and delete any macro in the organization |
| **Organization read only**                                 | `nrql_macros.read.macro`                                                                                  | Read any macro in the organization                             |

## Next steps [#next-steps]

To create, use, or manage macros, refer to [Create and manage macros](https://docs.newrelic.com/docs/nrql/nrql-macros/create-manage-nrql-macros/).