Documentation / Connectors

NetSuite (SuiteAnalytics Connect)

Run heavy analytical SQL against NetSuite via SuiteAnalytics Connect over JDBC — read-only, with full server-side pushdown including window functions, CTEs, lateral joins, HAVING, set operations, and regex and JSON functions.

NetSuite (SuiteAnalytics Connect) is the high-fidelity analytical path into NetSuite (bundle version 2.0.8, sharing the NetSuite bundle with the REST adapter). It connects over JDBC to Oracle's SuiteAnalytics Connect service and exposes a rich SQL surface that far exceeds the REST SuiteQL endpoint. Use it when you need window functions, CTEs, HAVING, complex joins, or analytical aggregations — and you do not need to write back to NetSuite.

This page is for data and platform engineers configuring a Nexus bridge to NetSuite for reporting and analytics. It covers when to choose Connect over REST, authentication, the exact pushdown surface, the JDBC sidecar requirement, and the limits you should plan around. For the general shape of JDBC connectivity in Nexus, see Generic JDBC — SuiteAnalytics Connect is a NetSuite-specific, credential-derived instance of that same JDBC substrate.

When to use this adapter

Scenario	Adapter to use
Heavy analytical SQL: windows, CTEs, lateral joins, `HAVING`, set ops	SuiteAnalytics Connect (this adapter)
Mixed reads and writes, or simple structured queries	NetSuite (REST / SuiteQL)
Creating, updating, deleting, or merging NetSuite records	NetSuite (REST / SuiteQL)

SuiteAnalytics Connect is read-only. If your workflow requires writing back to NetSuite, pair this adapter with the NetSuite REST adapter: Connect for reporting, REST for record operations. Because both use the same credentials, this is a routing decision, not a second integration.

Authentication

The adapter authenticates with OAuth 1.0a Token-Based Authentication (TBA). You supply five credential values when configuring the bridge; all five are stored in your tenant's Azure Key Vault.

Secret field	Description
`account_id`	Your NetSuite account identifier
`consumer_key`	Integration record consumer key
`consumer_secret`	Integration record consumer secret
`token_id`	Access token ID
`token_secret`	Access token secret

The adapter derives a TBA-signed JDBC password from these values at query time. The signed credential is computed per connection and is never logged or persisted outside the request lifecycle — Nexus stores only the five source secrets, not the derived password. See Secrets for how credential material is held and rotated.

SQL pushdown capabilities

SuiteAnalytics Connect supports a substantially richer SQL feature set than the SuiteQL REST surface, and the adapter pushes the full query down to NetSuite rather than fetching rows and filtering in the engine. Because Connect declares full pushdown across these dimensions and its operators are pushable, the Nexus engine does not re-apply your WHERE or re-aggregate in memory — the work runs on the Connect server.

Feature	Supported
`WHERE` filters (`$eq`, `$gt`, `$lt`, `$like`, `$in`, `$between`, and more)	Yes
`GROUP BY`, `ORDER BY`, `HAVING`, `DISTINCT`	Yes
Aggregations: `SUM`, `COUNT`, `AVG`, `MIN`, `MAX`, `STDDEV`, `VARIANCE`, `MEDIAN`, `PERCENTILE_CONT`, `LISTAGG`	Yes
Window functions (`ROW_NUMBER`, `RANK`, `FIRST_VALUE`, `LAST_VALUE`, …)	Yes
Common table expressions (CTEs / `WITH`)	Yes
Lateral joins	Yes
Subqueries	Yes
`CASE` expressions	Yes
Regex functions	Yes
JSON functions	Yes
Set operations: `UNION`, `UNION ALL`, `INTERSECT`, `MINUS`	Yes
Writes (insert / update / delete / merge)	No

Supported filter operators

$eq $ne $gt $gte $lt $lte $like $in $not_in $between $empty $contains $starts_with $ends_with $expr

$expr passes a raw SQL fragment directly into the WHERE clause and is intended for expressions the structured operator set cannot represent. It is a trusted-author surface — treat report and pipeline authorship accordingly, and bound it with execution roles.

Example: ranking customers by open balance

This query uses a window function to rank customers by outstanding balance within each currency bucket — not expressible via the SuiteQL REST endpoint.

async def run(ctx):
    rows = await ctx.adapters["netsuite-connect"].read(
        container="CONNECT",
        collection="transaction",
        select_expressions=[
            "entity",
            "currency",
            "SUM(foreignamount) AS total_open",
            "RANK() OVER (PARTITION BY currency ORDER BY SUM(foreignamount) DESC) AS balance_rank",
        ],
        where={"type": {"$eq": "Invoice"}, "status": {"$eq": "open"}},
        group_by=["entity", "currency"],
    )
    return ctx.result(rows=rows)

The equivalent as a raw CTE-based query in a saved report, passed through $expr:

WITH open_invoices AS (
    SELECT entity, currency, SUM(foreignamount) AS total_open
    FROM transaction
    WHERE type = 'Invoice' AND status = 'open'
    GROUP BY entity, currency
)
SELECT entity, currency, total_open,
       RANK() OVER (PARTITION BY currency ORDER BY total_open DESC) AS balance_rank
FROM open_invoices
ORDER BY currency, balance_rank

Because Connect is read-only, a full read-plus-write workflow lands the Connect result in the built-in workspace or writes back through the REST adapter — Connect itself never mutates NetSuite.

Infrastructure requirement: the JDBC sidecar

SuiteAnalytics Connect communicates over JDBC. Nexus routes JDBC traffic through a driver sidecar — a co-deployed process that handles the driver protocol on localhost. The sidecar is an opt-in component that is not started by default:

If the sidecar is not running, Nexus will not load this adapter (fail-closed), and the bridge is simply unavailable.
The NetSuite REST adapter (HTTPS, no sidecar) remains available regardless, so a deployment without the sidecar still has a working NetSuite path for reads and writes.
Enabling the sidecar is a deployment-configuration change made by your operator. See Generic JDBC for the shared sidecar and driver model.

Schema discovery

Discovery for SuiteAnalytics Connect returns the CONNECT container. Field-level metadata is provided by the companion NetSuite REST adapter, which has access to the same account and produces a unified schema view. In practice you can reference any table the Connect SQL surface exposes — the standard NetSuite record types plus any custom record types your account exposes.

Limits & behavior notes

Read-only, always. There is no write path on this adapter. Writability is not a per-collection gate here — the entire surface is read-only by design.
Sidecar is a hard dependency. No sidecar means no adapter. Plan deployments that rely on Connect to enable it explicitly.
Governance is NetSuite's. SuiteAnalytics Connect concurrency limits and per-account seat/session governance are enforced by NetSuite/Oracle, not Nexus. Very large extractions are still subject to those service limits.
Long queries are bounded by the run timeout. An analytical query inside a pipeline is bounded by the per-run wall-clock timeout; size heavy jobs accordingly or stage intermediate results in the workspace.
Credentials are shared with REST. The same five TBA secrets drive both adapters. Rotating them rotates both surfaces at once.

Choosing between Connect and REST SuiteQL

The REST SuiteQL adapter is the right default for most read/write workflows. Choose SuiteAnalytics Connect when:

You need window functions, CTEs, lateral joins, HAVING, or analytical aggregations.
You are building a reporting or analytics pipeline that does not write back to NetSuite.
Query performance matters and you want the full SQL optimizer available on the Connect surface.

Both adapters use the same TBA credentials and can be active on the same bridge simultaneously, so route read-heavy analytical queries to Connect and record operations to REST without duplicating your credential setup.