Query NetSuite with SuiteAnalytics Connect

When to use this

You want SQL over NetSuite's records: transaction, customer, item, the NetSuite2.com data source that SuiteAnalytics Connect exposes, rather than the REST record API. NetSuite ships a JDBC driver for it. This article sets it up as a JDBC source so an agent or a scheduled job queries it under a concurrency limit, with the login held by swarmvia.

For REST under a limit see Proxy NetSuite; for queued writes see Async NetSuite writes.

Setup

1. Get the driver

In NetSuite: Setup → Analytics → Connect Driver Download, JDBC tab. Download the driver for Linux (the runtime is Linux x86-64) and keep the jar from the bundle, NQjc.jar. NetSuite does not publish it to Maven Central.

Drivers → Upload a jar, name it NetSuite Connect. swarmvia confirms it declares com.netsuite.jdbc.openaccess.OpenAccessDriver.

2. Pick a role

Connect as a role with the SuiteAnalytics Connect permission and read access to the records you mean to query. Role 57, Data Warehouse Integrator, is the role NetSuite created for exactly this; a custom role is better when you want less. The role's record and field permissions are the boundary. NetSuite does not enforce a read-only connection; the driver reports readOnly: false on Test connection, and that is expected.

3. Create the source

Sources → New source → JDBC data source → NetSuite SuiteAnalytics Connect.

Placeholder	Where it comes from
Connect host	The Connect Driver page: `{account}.connect.api.netsuite.com`
Account ID	Setup → Company → Company Information, e.g. `1234567` or `1234567_SB1`
Role ID	The role from step 2

The preset writes the URL:

jdbc:ns://1234567.connect.api.netsuite.com:1708;ServerDataSource=NetSuite2.com;Encrypted=1;NegotiateSSLClose=false;CustomProperties=(AccountID=1234567;RoleID=57)

4. Create the credential

Two ways in; both are a jdbc_login credential.

Password (token-based authentication is not what the JDBC driver uses): the public property user (the login email) on the source and the secret property password on the credential. If the account enforces two-factor authentication for the role, use OAuth 2.0 instead.

OAuth 2.0 client credentials: register an integration record in NetSuite with the client credentials (machine-to-machine) flow and a certificate. On the credential, choose OAuth 2.0 client credentials, token URL https://{account}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token, your client id, the private key, scope suite_analytics, and the token property OAuth2Token. swarmvia mints the token and hands it to the driver on every connection.

5. Test and query

Test connection should report product NetSuite. Then:

curl https://netsuite.swarmvia.cloud \
  -H "X-Swarmvia-Key: $SWARMVIA_KEY" \
  -H "content-type: application/json" \
  -d '{"queries":[{"sql":"SELECT id, tranid, trandate, foreigntotal FROM transaction WHERE type = ? AND trandate >= ? FETCH FIRST 50 ROWS ONLY","params":["SalesOrd","2026-01-01"]}]}'

Placeholders are ?. NetSuite2.com speaks an Oracle-flavoured SQL: FETCH FIRST n ROWS ONLY for limits, BUILTIN.DF() for display values.

Tips

NetSuite counts every Connect query against the account's concurrency governance. Set the source's concurrency limit low (2 to 4) so a burst of agents never trips it.
source_schema lists NetSuite2.com's thousands of tables. Scope it by schema and table rather than listing everything into an agent's context.
Long analytical queries belong in jobs: send waitMs: 0 or Prefer: respond-async and poll, or let the source promote them.