How to write and run SuiteQL queries in NetSuite

Run a SuiteQL query

1. 1Enable SuiteAnalytics Workbook (Setup > Company > Enable Features > Analytics) if the query tool is not visible.
2. 2Go to Analytics > SuiteQL Query Tool (or search for the SuiteQL Query Tool bundle 665142 if not installed) to query interactively.
3. 3Write a standard SELECT against a NetSuite table, e.g. SELECT id, tranid, trandate FROM transaction WHERE type = 'SalesOrd' AND trandate >= TO_DATE('2026-01-01','YYYY-MM-DD').
4. 4Join to related tables with the actual join column, not the saved search dot-notation, e.g. JOIN transactionline ON transactionline.transaction = transaction.id.
5. 5For scripted use, call query.runSuiteQL({ query: sql, params: [] }) from N/query and iterate .asMappedResults() or .results.
6. 6For REST/external tools, POST the SQL text as JSON to /services/rest/query/v1/suiteql with header Prefer: transient (or paginate via the Content-Type: application/vnd.oracle.resource+json header) using OAuth 1.0 TBA or OAuth 2.0.
7. 7Paginate large result sets with LIMIT and OFFSET or the REST endpoint's built-in offset parameter - SuiteQL does not auto-page in the query tool UI beyond the default limit.
8. 8Watch governance: N/query counts against SuiteScript usage units, and the query tool UI caps result rows (commonly 4,000-5,000) even if more rows match.

Running SuiteQL from a SuiteScript with N/query

var query.runSuiteQL is called like:
var sql = 'SELECT id, tranid FROM transaction WHERE type = ? AND trandate >= ?';
var results = query.runSuiteQL({ query: sql, params: ['SalesOrd', '1/1/2026'] }).asMappedResults();

When to use SuiteQL over a saved search

Common pitfalls

• !Assuming SELECT * works uniformly - most tables require explicit column lists, and custom fields must be named individually.
• !Confusing saved search field IDs with SuiteQL column names; they are not interchangeable across the two systems.
• !Not paginating large result sets, hitting the query tool's row cap or REST default limit and assuming that is the full dataset.
• !Concatenating user input into SQL strings instead of using bind parameters with N/query.
• !Running heavy SuiteQL joins synchronously in a user event script and hitting governance or timeout limits.
• !Forgetting the Prefer: transient header on REST calls, leaving orphaned saved query records behind.