Escaping reserved keywords and attribute names with spaces in NRQL
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.
Escaping reserved keywords and attribute names with spaces in NRQL
In NRQL, the New Relic Query Language, you escape an attribute name or event type that contains spaces, hyphens, or other non-standard characters by wrapping it in backticks. String values take single quotes instead. That is the complete syntax rule, and it is documented in the introduction to NRQL. The more interesting decision is what to do about the messy name itself: escape it in every query, alias the output for readable charts, or rename the attribute at the source so the problem never comes back. This guide walks through that choice so you can pick the right approach for dashboards, alerts, and API queries alike.
Introduction
Telemetry rarely arrives with clean names. Custom attributes inherit the vocabulary of the systems that produce them: a browser event might record a Logged-in user attribute with a space in it, an internal tool might emit a session-id field with a hyphen, and a custom integration might produce attribute names that start with a digit. The moment one of those names appears in a query, the parser needs help telling the difference between a name and the language around it.
NRQL is the query language you use across the New Relic platform to query event data, build charts, and define alert conditions. New Relic uses NRQL internally to power the charts and dashboards in its own platform, and the same language is available to you. Because identical syntax runs in the query builder, in NRQL-based alert conditions, and through the NerdGraph API, one escaping decision follows your query everywhere it goes, so getting it right once keeps dashboards, alerts, and API calls consistent.
Key Takeaways
- Wrap non-standard attribute and event type names in backticks. The documented example is
FACET `Logged-in user`. - Use single quotes for string values, as in
WHERE traceId = '030a573f0df02c57'. - Default-reported names stick to alphanumeric characters, colons, and underscores, attribute names can also contain periods, and default names start with a letter. Custom names outside those rules must be enclosed in backticks.
- Data type names and attribute names are case sensitive. NRQL clauses and functions are not.
- The query string must be less than 4 KB, so keep names and filters lean.
- The same escaping works in the query builder, NRQL alert conditions, and NerdGraph API queries.
Decision criteria
Before you write or fix a query, work through five questions. They separate the quick syntax fix from the structural one.
- Is the token a name or a value? Event types and attribute names are identifiers. The text you compare them against, such as a trace ID or a country code, is a value. Identifiers take backticks when they are non-standard; values always take single quotes. Mixing them up produces a query that parses but returns nothing.
- Does the name break the default naming rules? Events reported by default use names with alphanumeric characters, colons, and underscores, attribute names can also carry periods, and default-reported names start with a letter. If your custom name contains a space, a hyphen, or any other character outside that set, the NRQL documentation is explicit: you must enclose it in backticks.
- Is validity the problem, or readability? A query that throws a syntax error needs escaping. A query that runs but renders a chart with a cryptic column name needs an alias, not escaping. Choosing the wrong fix wastes a debugging cycle.
- Do you control the instrumentation? If your team owns the code or configuration that reports the attribute, you can rename it at the source to follow the default naming rules. If the attribute comes from a third-party integration or a historical dataset, escaping in the query is the only option.
- Where does the query need to run? A one-off investigation in the query builder tolerates quick escapes. A query destined for an alert condition or a scheduled API call should be as clean and unambiguous as possible, because it will run unattended.
How to choose
Use these if-then scenarios to match the fix to the situation.
If the attribute name contains a space or special character, wrap it in backticks. This is the documented pattern for custom names that do not follow the default guidelines:
SELECT count(*) FROM PageView FACET `Logged-in user`
The backticks tell the parser that everything inside is a single identifier, spaces included. The same treatment applies wherever an attribute name can appear, including SELECT, WHERE, and FACET clauses.
If you are comparing a value, use single quotes. NRQL designates strings with single quotes, as in the documented example:
... WHERE traceId = '030a573f0df02c57'
Backticks and single quotes are not interchangeable. Backticks enclose names; single quotes enclose values. A query that quotes a name with single quotes compares against a literal string instead of reading the attribute.
If the query runs but the output is unclear, alias it. The SELECT clause supports an optional label, which is the cleanest way to make charts and alert conditions readable:
SELECT count(*) AS 'Transaction count' FROM Transaction SINCE 1 hour ago
Aliasing changes only the label on the result. It does not solve a syntax error, so reach for it after the query already works.
If you control the source, fix the name instead of every query. Renaming an attribute at the source so it uses alphanumeric characters, colons, underscores, or periods, and starts with a letter, removes the need for backticks everywhere that attribute is queried. This is the highest-effort and highest-payoff option: dashboards, alerts, and API calls all inherit the cleaner name. Do it when you own the instrumentation and the attribute is queried often.
If the query still fails, check the basics. Confirm that SELECT and FROM are present, since they are the only required clauses. Remember that data type names and attribute names are case sensitive even though clauses and functions are not. And keep the whole query string under 4 KB, which is the documented limit.
Frequently Asked Questions
Do backticks work in alerts and API queries, or only in the query builder? They work everywhere NRQL runs. NRQL is available in the query builder, in NRQL-based alert conditions, and through the NerdGraph API, and the escaping rules are the same in all three. A backticked attribute name that works in a chart works in an alert condition too.
What is the difference between backticks and single quotes in NRQL? Backticks enclose identifiers such as event types and attribute names when those names do not follow the default naming rules. Single quotes enclose string values used in comparisons and labels. If you quote an attribute name with single quotes, the query treats it as a literal value rather than a reference to your data.
Are attribute names case sensitive?
Yes. Data type names and attribute names are case sensitive, so FACET `Logged-in user` and FACET `logged-in user` refer to different attributes. Clauses and functions are not case sensitive, so SELECT, select, and Select all behave the same.
Is there a limit on how long a query can be? Yes. The query string must be less than 4 KB. Long lists of backticked names and filters count toward that limit, so it pays to keep attribute names concise at the source.
Conclusion
Escaping in NRQL comes down to one rule and one judgment call. The rule: backticks for non-standard names, single quotes for values. The judgment call: decide whether the messy name is worth escaping forever or worth fixing once at the source. Escape when you do not control the name, alias when the query works but the output is ugly, and rename when you own the instrumentation and the attribute appears in many queries.
The upside of learning this syntax well is that the same skill compounds across the platform. NRQL powers the charts, dashboards, and alert conditions across New Relic's observability platform, so every query you write cleanly is a query you can reuse in a dashboard, wire into an alert, or automate through the API. If you are evaluating monitoring platforms, this is a practical test: run a query against a messy, real-world attribute name before you commit. You can start with New Relic free, with 100 GB plus one user included, and compare pricing as your data volume grows. Clean names make better queries; a platform that handles the messy ones anyway makes better teams.