N/dataStore Objects and Cursors in NetSuite 2026.2
NetSuite 2026.2 documents SuiteScript 2.1 collections and asynchronous cursors, including write transaction boundaries, retry rules, and retrieval groups.
NetSuite 2026.2 introduces N/dataStore collection and cursor objects for SuiteScript 2.1 server scripts. Collections support document insertion, retrieval, updates, and deletion, while asynchronous cursors retrieve query results in groups. Developers need to account for independent commits, specific retry restrictions, and retrieval boundaries when designing document-processing scripts.
Which N/dataStore Objects Are Documented?
The object reference lists dataStore.Collection, dataStore.Cursor, dataStore.Datastore, dataStore.Document, and dataStore.DocumentMetadata. It also lists six result objects: dataStore.DeleteResult, dataStore.FindOneResult, dataStore.FindResult, dataStore.InsertManyResult, dataStore.InsertOneResult, and dataStore.UpdateResult.
This article focuses on Collection and Cursor behavior. The object listing alone does not establish the properties of each result object; do not infer result structures from their names.
How Do Collections Select and Change Documents?
A dataStore.Collection represents documents within a data store. Obtain one through either dataStore.getCollection(id) or Datastore.getCollection(id), then use its methods to insert, retrieve, update, or delete documents. Collection and Cursor both support server scripts and are available since 2026.2.
Pass a query object to the corresponding collection method to select documents for retrieval, updates, or deletion. The relevant documentation separates three concerns:
| Concern | Documentation to consult |
|---|---|
| Supported selection syntax | Data Store Query Object |
| Update operators, rules, and limits | Data Store Update Object |
| Supported property names for inserted documents | Data Store Query Rules |
Check these requirements before designing document properties or translating an existing query. Collection availability does not, by itself, establish which query syntax or update operators are supported.
What Happens When a Write Fails?
Collection writes have transaction boundaries that matter when coordinating document changes with record processing:
| Situation | Documented behavior | Practical response |
|---|---|---|
| Separate API calls | Each call saves changes independently of the surrounding record or script transaction. A later failure does not roll back an earlier call. | Do not treat a sequence of calls as one transaction. |
insertMany, updateMany, or deleteMany | Selected changes within that call save or roll back together; no partial-success results are returned. | Keep per-call atomicity distinct from cross-call behavior. |
DATA_STORE_OUTCOME_UNKNOWN | Changes might have been saved. | Do not retry automatically. Check whether the intended changes occurred before deciding to retry. |
DATA_STORE_COMMITTED_RESULT_UNAVAILABLE | Changes were saved, but the result could not be returned. | Do not retry the operation. |
A failed response therefore does not always mean that no changes occurred. Error handling must distinguish an uncertain outcome from a saved change whose result is unavailable.
Retry warning: Repeating an update containing $inc can apply the increment twice. Automatically replaying failed requests can therefore change the document again rather than merely recover a missing response.
How Does Asynchronous Cursor Retrieval Work?
Collection.find(query) provides a dataStore.Cursor, an asynchronous iterator used with for await...of. Each yielded value is a dataStore.FindResult object.
Internally, results are retrieved in groups of up to 100 documents, with a combined document-body size of up to 10 MB per group. These are retrieval-group limits, not a stated total-result limit.
The cursor retrieves another group when iteration requests a result beyond the current group. Iterations requiring retrieval—especially with larger documents—can take longer. Account for those boundaries when reviewing SuiteScript execution time limits; do not assume every iteration has equal cost.
Cursor Syntax Example
This syntax illustration is not a complete executable script:
1// Add additional code2...3 4const collection = dataStore.getCollection('checkpoints');5const cursor = await collection.find({ status: 'pending' });6 7for await (const result of cursor) {8 const document = result.document;9 const documentId = document._id;10}11 12...13// Add additional codeCursor.next() returns a Promise for the next iterator result. Cursor.return() also returns a Promise and explicitly closes the cursor, ending iteration.
Who This Affects
- SuiteScript developers: Design server-side collection operations around independent commits, documented retry restrictions, and asynchronous iteration.
- Administrators and deployment owners: Include write-failure handling and larger-result iteration in SuiteScript deployment testing. The Collection and Cursor references do not establish setup navigation or permission requirements.
Key Takeaways
- Collection and Cursor are SuiteScript 2.1 server-script objects available since NetSuite 2026.2.
- Each bulk write call saves or rolls back its selected changes together; separate calls do not form one transaction.
- Check changes before retrying
DATA_STORE_OUTCOME_UNKNOWN; do not retryDATA_STORE_COMMITTED_RESULT_UNAVAILABLE. - Cursor retrieval groups contain up to 100 documents and up to 10 MB of combined document bodies.
Frequently Asked Questions (4)
Are N/dataStore Collection and Cursor objects available in client scripts or only server scripts?
Do multiple N/dataStore collection writes commit as one transaction with the surrounding script or record?
Should I retry a collection write after DATA_STORE_OUTCOME_UNKNOWN or DATA_STORE_COMMITTED_RESULT_UNAVAILABLE?
How many documents can a dataStore cursor retrieve at a time, and when does it fetch another group?
Weekly Update History (1)
Added the N/dataStore Module documentation, which describes how to store, retrieve, update, and delete internal application data as JSON documents without requiring custom records.
View Oracle DocsWas this article helpful?
More in SuiteScript
- Common SuiteScript Errors and Solutions for NetSuite
Common NetSuite script errors include INVALID_SCRIPT_DEPLOYMENT_ID and SSS_AUTHORIZATION_HEADER_NOT_ALLOWED. Learn effective solutions.
- SuiteScript 2.x Sublist Values: Standard and Dynamic Mode
Use setSublistValue in standard mode; select a line, set its current value and commit it in dynamic mode. Choose the API from the record's mode.
- SuiteScript 2.1 Enhancements and API Updates in NetSuite
SuiteScript 2.1 enables execution of 2.0 scripts and supports PATCH method for enhanced API capabilities.
- SuiteScript Record.setValue: Body Fields, Types and Errors
Set NetSuite body fields with Record.setValue, matching field IDs and value types and checking common API errors.
Also from NetSuite 2026.2
- Bank Matching and Reconciliation Enhancements in NetSuite 2026.2
Bank matching and reconciliation pages in NetSuite 2026.2 receive critical UI enhancements for improved transaction management.
- System Notes Enhancement for Reconciliation in NetSuite 2026.2
System notes enhancement tracks GL transaction events in NetSuite 2026.2, improving reconciliation auditing and review.
- SuiteCloud CLI License Acceptance for Automation
Set SUITECLOUD_CLI_ACCEPT_LICENSE=true to suppress the SuiteCloud CLI license prompt during scripted npm installation.
- NetSuite Next: Readiness, Preview, and Ask Oracle
Eligible administrators can request a NetSuite Next preview, set up Ask Oracle, and prepare data, roles, customizations, and navigation.
