Validate a SuiteScript export using query.runSuiteQLPaged by proving deterministic ordering, adequate page capacity and complete destination acceptance. The method's ability to return pages does not establish that the selected population fits its limits or that every returned row reached the final file.
This guide is specifically about the N/query paged-query route in SuiteScript. REST record-collection pagination, REST SuiteQL requests and Connect extraction have different contracts. Incremental change detection between runs is also a separate design problem; the focus here is completing one defined paged result.
Record the query text or version, parameters, selected account environment, execution role, intended grain and page size. Define what constitutes one output row and which source fields uniquely identify it.
Keep this definition unchanged during the run. A restart that uses a revised query but reuses the old page checkpoint is continuing a different population. Treat a query or parameter change as a new run unless an explicit recovery design proves otherwise.
Specify the result schema independently. The method has constraints around retrieving column metadata from arbitrary string queries. If the implementation relies on column definitions, assess the documented SuiteQL object route and retain the expected output mapping rather than assuming the paged result supplies every label the exporter needs.
The query definition must provide a unique, unambiguous sort order with explicit precedence. Sorting by transaction date alone is insufficient when many rows share that date. Sorting by transaction ID alone is insufficient for an output containing several lines per transaction.
Choose tie-breakers that establish uniqueness for the actual result. For a line-level extract, that can require the parent identity and supported line identity; an accounting output may also require book and other accounting-grain identifiers. Confirm the key through the accessible schema and sample results.
Test tied values deliberately. Place several records at a page boundary with the same leading sort field. The expected outcome is that each intended identity appears once. Random-looking order on a small sample is not proof of a stable contract.
Do not describe sorting as a transactionally frozen snapshot. If source records can change while the query is read, define a consistency strategy and an independent comparison appropriate to the report's purpose.
The documented page size ranges from 5 to 1,000, with a default of 50. The method documents a maximum of 1,000 pages. Without SuiteAnalytics Connect enabled, it also documents a maximum of 100,000 results across pages.
The documentation removes that result-count ceiling when Connect is enabled, while still stating the method's page maximum. Treat both statements as planning constraints; do not translate “no result limit” into an unlimited single invocation. Verify the applicable release and execution behavior before accepting a large export.
Larger pages can reduce the number of page fetches, but the script still has governance, runtime, memory and output constraints. Test the complete exporter rather than selecting the largest page size by habit.
Assume a fixed population of 80,400 rows. At the default page size of 50, the expected number of pages is 1,608. That exceeds the documented 1,000-page maximum even though the row population is below 100,000.
At a page size of 500, the same population requires 161 pages: 160 full pages containing 80,000 rows and a final page containing 400. Under the stated row and page limits, that configuration fits the documented capacity. It still needs runtime, identity and destination tests.
Now increase the population to 120,400 rows in an account without Connect enabled. A 500-row page size would imply 241 pages, but the 100,000-result ceiling remains a separate blocker. Increasing page size alone cannot solve it.
The design needs an approved alternative, such as disjoint bounded query partitions or a suitable extraction route. Each partition must retain its own complete definition and reconciliation. These figures are hypothetical capacity calculations, not a benchmark or an executed NetSuite test.
| Scenario | Expected evidence | What it detects |
|---|---|---|
| Empty result | Completed run with zero accepted identities | Incorrect empty-output handling |
| Exactly one full page | Correct count and termination | Off-by-one traversal |
| One row beyond a full page | Second page contains the final identity | Missing last page |
| Tied leading sort values | Every unique result key appears once | Ambiguous sorting |
| Population near a cap | Explicit capacity assessment | Silent truncation risk |
| Interrupted destination write | Safe replay or controlled restart | Checkpoint advancing too early |
| Permission-limited field | Defined failure or missing-data outcome | Incomplete successful output |
Include a final partial page and an exactly divisible population. Both are necessary because logic that stops on a short page can behave differently from logic using the returned page structure.
Maintain distinct counts for source rows read, destination rows accepted and unresolved rows. If a page contains 500 rows but the exporter rejects three during serialization, page traversal is complete while the deliverable remains incomplete.
Retain stable identities for comparison. A received count of 80,400 could still contain one duplicate and one omission. Compare the identity set or an appropriate controlled representation in addition to the row count.
Advance a checkpoint only after the work it represents is durable. Test failure after writing rows but before committing the checkpoint, and failure before rows are accepted. The restart policy should prevent both accidental omission and duplicate business facts.
If a script restarts by rerunning the query, confirm whether source changes invalidate the old positional checkpoint. A new live query is not necessarily the same result sequence as the interrupted one, even with a correct sort definition.
The metaDataProvider option controls how certain permission gaps behave. The default SUITE_QL mode fails on inaccessible fields or records; STATIC can allow execution while returning no data for the unavailable elements. Choose deliberately and test the actual execution role.
A blank result under a permissive metadata mode should not be interpreted automatically as a business null. The export needs a way to distinguish approved absence from missing visibility where the field is required for the report.
This option belongs to N/query. Do not confuse it with Connect's Static Data Model setting, which concerns schema visibility and still respects data permissions. Similar terminology does not establish identical behavior across channels.
A finished run should retain its query definition, expected schema, page size, page evidence, accepted distinct identities and reconciliation outcome. Record the selected consistency policy and any exclusions so consumers understand what the extract represents.
For financial outputs, add an independently approved amount check on the same book, currency and cutoff. For operational outputs, use the quantities or statuses that matter to the decision. Neither replaces the identity check.
Bring the failing boundary case and execution contract to CuriousRubik's NetSuite integration services when designing or repairing a SuiteScript reporting export. A completed file should be supported by evidence of coverage, not just the absence of a script error.
No. This guide covers the SuiteScript N/query method. REST record collections, REST SuiteQL and Connect each require their own current interface documentation and completeness tests.
Only if it uniquely orders every output row, which is uncommon for transaction data. Add validated tie-breakers for the actual result grain and test several tied records across a page boundary.
Yes. At 50 rows per page, a population requiring more than 1,000 pages exceeds the documented page maximum. Check expected pages as well as the applicable result-count ceiling.
Do not assume that. The documentation removes the separate 100,000-result ceiling with Connect enabled but also states a 1,000-page maximum for the method. Plan against both statements and validate the selected configuration.
Use the fixed query definition, page evidence, accepted distinct identities, unresolved-row count and an independent control total where appropriate. A successful script execution or matching raw row count alone is insufficient.