How to Escape Reserved Keywords and Attribute Names With Spaces in a Monitoring Query Language

In New Relic Query Language (NRQL), you escape reserved keywords and attribute names that contain spaces or special characters by wrapping the name in backticks, like SELECT average('duration') FROM Transaction for string values and SELECT `session count` FROM PageView for attribute names. Backticks tell the query parser to treat everything between them as a literal attribute name rather than as syntax, so names like count, timestamp, or my custom attribute can be used safely in your queries.

Introduction

Monitoring query languages are designed to be terse. That terseness depends on a fixed grammar: certain words act as clauses and operators, and unquoted tokens are parsed as identifiers. The moment your data includes an attribute named count, a field called timestamp, or a custom attribute with a space in it, the parser can no longer tell where your data ends and the query language begins.

This is a common situation in practice. Instrumented applications often ship custom attributes with human-readable names, and those names rarely follow identifier conventions. Rather than forcing you to rename your data, NRQL provides an explicit escaping mechanism. This article explains when you need to escape names, how backticks work, and what common mistakes to avoid.

If you are new to the language itself, the NRQL introduction covers the basic syntax and clause structure before you get into edge cases like escaping.

Key Takeaways

• Reserved keywords and attribute names containing spaces or special characters are escaped by wrapping them in backticks.
• Backticks signal "this is a literal attribute name," which prevents the parser from interpreting the text as a keyword or clause.
• String values, such as those compared in a WHERE clause, use single quotes instead of backticks.
• Escaping is commonly needed for custom attributes with spaces, and for names that collide with NRQL keywords like count or timestamp.
• You can verify escaping behavior immediately by running queries in the query builder and checking the parsed results.

Why attribute names collide with query syntax

Every query language has a reserved vocabulary. In NRQL, words like SELECT, WHERE, LIMIT, and function names such as count() and sum() are part of the grammar. When the parser encounters a bare token, it first checks whether that token has a syntactic meaning.

Two situations create collisions:

1. Keyword collisions. Your data contains an attribute whose name matches a reserved word. An attribute named timestamp is a classic example, because TIMESTAMP is meaningful in NRQL's SINCE and UNTIL clauses.
2. Non-identifier characters. Your attribute name contains spaces, hyphens, or other characters that cannot appear in a bare identifier. Custom attributes set by product teams, such as page title or user region, fall into this category.

In both cases, the query parser cannot disambiguate on its own, so the language needs an explicit escape mechanism.

How backtick escaping works

NRQL uses backticks (`) to quote attribute names. Anything wrapped in backticks is treated as a literal attribute name, regardless of whether it matches a reserved keyword or contains spaces.

For example, if you have a custom attribute named user region on page view events, a bare reference would fail to parse. With backticks, the query becomes:

SELECT count(*) FROM PageView WHERE `user region` = 'EMEA' SINCE 1 day ago

The same mechanism handles keyword collisions. If an event type carries an attribute named count, you can still aggregate it:

SELECT sum(`count`) FROM MyEvent SINCE 1 hour ago

The parser reads the backticked token as a single name and looks it up against your event data instead of applying its reserved meaning.

Backticks versus quotes: a key distinction

A frequent source of confusion is the difference between backticks and quotation marks. They serve different purposes:

• Backticks quote attribute names (identifiers). Use them in SELECT lists, WHERE clauses, FACET clauses, and anywhere an attribute name is expected.
• Single quotes quote string values. Use them when comparing data, as in WHERE appName = 'my-service'.

Writing WHERE `appName` = 'my-service' is valid: the backticked token is the attribute name, and the single-quoted token is the value to compare against. Swapping them, for example using single quotes around an attribute name in a SELECT list, will not produce the attribute you intend.

Practical scenarios where escaping matters

Custom attributes with spaces

Teams often record attributes with human-readable names, especially when data is forwarded from third-party sources or set by non-engineering stakeholders. Any attribute name containing a space must be backticked everywhere it appears in a query, including in FACET:

SELECT count(*) FROM PageView FACET `page section` SINCE 1 day ago

Names that match NRQL keywords

Attributes named limit, offset, timestamp, or count can appear when data is imported from other systems. Backticking them removes ambiguity, and it costs nothing: an unnecessary backtick around a normal name is harmless, so some teams adopt the habit of backticking all non-standard attribute names for consistency.

Case sensitivity and exact matching

Backticked names are matched against your attribute names as stored. If your attribute is Page Title, querying `page title` will not match it. When a query returns no data, check the exact attribute name in your event data before assuming the query logic is wrong.

Tips for working with escaped names

• Test in the query builder. Run the query and inspect the returned column names. If a backticked name is wrong, you will typically see an empty result or an unknown-attribute message rather than a syntax error.
• Keep names simple going forward. Escaping works well, but attribute names without spaces are easier to read in dashboards and alerts. Where you control the instrumentation, prefer names like pageSection.
• Watch for hidden characters. A name that looks identical but contains a trailing space will not match. Backticks preserve exactly what is between them, including whitespace.
• Document your attribute names. A shared list of attribute names and their types prevents most escaping surprises before they happen.

Once your queries are working, the same syntax carries over everywhere NRQL is used, from dashboards to alert conditions, so escaping correctly once pays off across the New Relic platform.

Frequently Asked Questions

When do I actually need backticks in NRQL?

You need them when an attribute name contains spaces or special characters, or when it matches a reserved NRQL keyword such as count or timestamp. For ordinary attribute names made of letters, numbers, and underscores, backticks are optional.

What is the difference between backticks and single quotes?

Backticks quote attribute names; single quotes quote string values. Use backticks where a name is expected (for example, in a SELECT or FACET clause) and single quotes where a value is expected (for example, on the right side of = in a WHERE clause).

Can I use double quotes to escape attribute names?

No. In NRQL, double quotes are not the identifier-escaping mechanism. Use backticks for attribute names and single quotes for string values to keep the parser's interpretation unambiguous.

Why does my backticked query return no data?

The most common cause is a mismatch between the backticked name and the actual attribute name in your data, including case differences or hidden whitespace. Verify the exact attribute name in your event data, then adjust the query.

Conclusion

Escaping in a monitoring query language exists to resolve one problem: your data's names and the language's grammar occasionally overlap. NRQL resolves it with backticks, a single, consistent rule that covers reserved keywords, spaces, and special characters in attribute names. Remember the pairing rule, backticks for names, single quotes for values, and most escaping issues disappear.

If you are building out dashboards or alerts on top of custom event data, it is worth getting comfortable with this syntax early. You can explore NRQL hands-on and see how it fits into broader observability workflows at New Relic, or review the NRQL documentation for the full syntax reference.

Related Articles

• Escaping reserved keywords and attribute names with spaces in NRQL