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.

·4 min read·18 views·NetSuite 2026.2·View Oracle Docs

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:

ConcernDocumentation to consult
Supported selection syntaxData Store Query Object
Update operators, rules, and limitsData Store Update Object
Supported property names for inserted documentsData 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:

SituationDocumented behaviorPractical response
Separate API callsEach 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 deleteManySelected 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_UNKNOWNChanges might have been saved.Do not retry automatically. Check whether the intended changes occurred before deciding to retry.
DATA_STORE_COMMITTED_RESULT_UNAVAILABLEChanges 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:

javascript
1// Add additional code
2...
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 code

Cursor.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 retry DATA_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?
The Collection and Cursor objects are documented for SuiteScript 2.1 server scripts and are available starting in NetSuite 2026.2. The article does not identify them as client-script objects.
Do multiple N/dataStore collection writes commit as one transaction with the surrounding script or record?
No. Each API call saves its changes independently of the surrounding record or script transaction, so a later failure does not roll back an earlier call. Within a single insertMany, updateMany, or deleteMany call, the selected changes save or roll back together, with no partial-success results.
Should I retry a collection write after DATA_STORE_OUTCOME_UNKNOWN or DATA_STORE_COMMITTED_RESULT_UNAVAILABLE?
Do not retry either error automatically. For DATA_STORE_OUTCOME_UNKNOWN, changes might have been saved, so check whether they occurred before deciding what to do. DATA_STORE_COMMITTED_RESULT_UNAVAILABLE means the changes were saved but the result could not be returned, so do not retry the operation.
How many documents can a dataStore cursor retrieve at a time, and when does it fetch another group?
Cursor retrieval groups contain up to 100 documents, with a combined document-body size of up to 10 MB per group; these are not limits on the total results. The cursor retrieves another group when iteration requests a result beyond the current group, and iterations that require retrieval can take longer, especially for larger documents.

Weekly Update History (1)

SuiteScriptadded

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 Docs
Source: N/dataStore Objects and Members — Oracle NetSuite Help Center. This article was generated from official Oracle documentation and enriched with additional context and best practices.

Was this article helpful?

More in SuiteScript

View all SuiteScript articles →

Also from NetSuite 2026.2

View all NetSuite 2026.2 changes →