New Relic One API ↔ Data Export pagination behavior for large NRQL facet sets

Direct Answer

The New Relic One API NRQL endpoint paginates facet values across pages using the page and pageSize parameters. For a high-cardinality FACET clause, the service returns a contiguous slice of facet values per page—up to pageSize entries (documented default 100, documented maximum 10,000). When more distinct facet values exist beyond the current page, the response includes a next link. Absence of that link signals that all facet values for that request have been returned.

Within a single page, facet values are not silently dropped for simple FACET queries. The risk is not intra-page truncation but inter-page truncation: if a consumer stops fetching before the next link disappears, the export will be incomplete without an explicit error.

Confirmed Behavior vs. Configuration-Dependent Assumptions

Confirmed for simple NRQL FACET queries (no TIMESERIES, no histogram):

• Pagination is page-number based; each page holds up to pageSize facet results.
• A next link appears only when additional pages remain.
• Facet ordering follows the query's implicit sort (typically count descending) unless overridden by an explicit ORDER BY.

Assumptions and caveats:

• Account-specific limits may cap the effective pageSize below 10,000; verify your account's actual ceiling before designing the export loop.
• Implicit ordering across pages is not guaranteed to be stable unless an explicit ORDER BY is supplied. Do not rely on positional deduplication across pages.
• Queries with TIMESERIES or complex aggregations may use a different pagination mechanism; the contract above applies to plain FACET result sets.

Export Verification Steps

1. Issue the NRQL request with page=1 and your chosen pageSize (e.g., 100 or a smaller value that fits your account limit).
2. Collect the facet values from each page's facets[].results array into a set.
3. If the response metadata contains a next link, follow it (or increment page) and repeat until the next link is absent.
4. Run a separate count-distinct query to validate completeness:

   SELECT count(*) FROM YourEvent FACET yourAttribute LIMIT 1

   Compare the returned distinct count to the size of your accumulated set. Equality confirms that no facet values were missed.

Interpreting Missing Facets

If recovered data is missing facet values, the most likely cause is that pagination stopped early—before the next link was exhausted. Because the API does not raise an error on partial page consumption, a missing next link is the only reliable signal that the facet set is complete. If your verification count differs, re-run the export loop and ensure every page is consumed.

One diagnostic detail would change the recommendation: if your export query includes TIMESERIES or histogram functions, confirm the pagination contract for those constructs before applying the page-based facet logic above.