N/search vs N/query in SuiteScript 2.1 — When to Use Which

If you have worked with NetSuite for more than a few weeks, you have probably wondered which data access module to reach for: the trusted N/search or the newer, SQL-flavored N/query. Both are first-class citizens in SuiteScript 2.1, and both can read the same underlying data — but they are optimized for very different scenarios. This post breaks down how each one works, when to choose one over the other, and the patterns we see in real-world NetSuite implementations.

A Quick Refresher on N/search

N/search is the SuiteScript wrapper around classic NetSuite saved searches. You define filters and columns, run the search, and iterate over results. It is record-oriented and tightly tied to the saved-search engine that powers the NetSuite UI. Joins, summaries, formula columns, and result highlighting all work the same way they do for an end user building a saved search in the browser.

A Quick Refresher on N/query and SuiteQL

N/query exposes SuiteQL — a read-only SQL dialect over NetSuite’s data model. Instead of building filters and columns object-by-object, you write SQL: SELECT, FROM, JOIN, WHERE, GROUP BY, ORDER BY, and subqueries. N/query supports both a builder API (query.create) and raw SuiteQL via query.runSuiteQL. Behind the scenes it talks directly to the underlying database tables, which often makes it dramatically faster than equivalent saved searches — especially for analytical workloads.

Performance: Why N/query Often Wins

For large datasets, SuiteQL typically outperforms saved searches by a wide margin. It supports server-side aggregation, window functions, and complex joins without forcing you to chain multiple searches. Pagination via query.runSuiteQLPaged lets you stream millions of rows efficiently, and governance cost is generally lower per row returned. If your script is timing out on a saved search, rewriting the query in SuiteQL is often the single biggest win.

When to Use N/search

• You need to reuse a saved search that a business user already maintains.
• You rely on UI features such as result highlighting, audience permissions, or scheduled email distribution.
• You are calling search.load by ID from a script.
• Your code needs to mirror standard NetSuite behavior — inactive-record filtering, role-based restrictions, or formula columns exactly as users see them.

When to Use N/query

• You are pulling large datasets or doing analytics that involves grouping, aggregation, or window functions.
• You need joins across many tables that would be awkward in a saved search.
• You need access to data not exposed in the saved-search UI — system tables, audit logs, or hidden relationships.
• You are building ETL pipelines, AI prompt context, or integration payloads where SQL is the natural fit.

Side-by-Side Example

N/search version — fetching open sales orders:

const search = require('N/search');

const s = search.create({
    type: 'salesorder',
    filters: [
        ['mainline', 'is', 'T'], 'AND',
        ['status', 'anyof', 'SalesOrd:B']
    ],
    columns: ['tranid', 'entity', 'total']
});

s.run().each((r) => {
    log.debug('SO', r.getValue('tranid'));
    return true;
});

N/query (SuiteQL) version — same result, written as SQL:

const query = require('N/query');

const rs = query.runSuiteQL({
    query: `
        SELECT tranid, entity, foreigntotal
        FROM transaction
        WHERE type = 'SalesOrd'
          AND status = 'B'
    `
});

rs.asMappedResults().forEach((r) => log.debug('SO', r.tranid));

Governance and Limits

Both modules consume governance units, but they bill differently. search.run().each uses 10 units plus per-page costs; runSuiteQL and runSuiteQLPaged use 10 units per call for the call itself, with paging costs added. For long-running jobs, prefer Map/Reduce scripts and pass SuiteQL or search objects through getInputData. Always benchmark in your own account — the real-world difference depends heavily on data volume, joins, and indexes.

Decision Cheat Sheet

• Use N/search for: existing saved searches, UI parity, role-aware results, scheduled email exports, and quick scripts where developer familiarity matters.
• Use N/query for: large datasets, complex joins, analytics, AI prompt context, integration payloads, and anywhere you would naturally write SQL.
• When in doubt: prototype both and measure execution time and governance — your data will tell you the right answer.

Conclusion

N/search and N/query are not competitors — they are complementary tools. A mature SuiteScript 2.1 codebase usually uses both: saved searches for business-user-defined logic, and SuiteQL for performance-critical, analytical, or integration-heavy work. Learn both well, and you will be able to pick the right tool every time. In future posts on The NetSuite Pro, we will dive deeper into SuiteQL joins, window functions, and patterns for combining N/query results with the N/record module to build powerful automations.