# Nexus Adapter Reference

> Canonical, public-safe reference of Nexus data adapters/connectors — auth, read/write/discover and pushdown capabilities, supported UQL filter operators, credential field names, and operational quirks — for human and AI/LLM consumers.
> Source: https://stingraytechnologysolutions.com/adapters.html · JSON: https://stingraytechnologysolutions.com/adapters.json

## NetSuite (REST / SuiteQL)  `netsuite-rest`

- **Category:** erp
- **Auth:** OAuth 1.0a Token-Based Authentication (TBA, HMAC-SHA256) OR OAuth 2.0 client_credentials — selected per connection
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with, $expr
- **Credentials:** auth_method, account_id, consumer_key, consumer_secret, token_id, token_secret
- **Notes:** NetSuite ERP over the REST platform: SuiteQL for ad-hoc reads and the Record API for create/update/delete. Best for read-heavy SuiteQL reporting plus targeted record writes.
- **Quirks:**
  - Two surfaces in one adapter: SuiteQL (the /query/v1/suiteql endpoint, full SQL-style read) and the Record API (/record/v1/<collection>, per-record CRUD). The query container selects the surface: NETSUITE/empty → SuiteQL, RECORD → Record API.
  - SuiteQL has no prepared-statement support, so filter values are inlined into the query text — treat report/query authoring as a trusted surface.
  - TBA realm is derived from the account ID, uppercased with hyphens converted to underscores.
  - OAuth 2.0 access tokens are cached and refreshed ~60 seconds before expiry.
  - Field-level schema discovery is intentionally shallow (returns collections/record types; per-field lists are deferred).
  - Requests use the SuiteQL 'Prefer: transient' header and paginate via SuiteQL offset/limit.

## NetSuite (SuiteAnalytics Connect)  `netsuite-connect`

- **Category:** erp
- **Auth:** OAuth 1.0a TBA (HMAC-SHA256) presented as a signed JDBC connection password
- **Capabilities:** read, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with, $expr
- **Credentials:** account_id, consumer_key, consumer_secret, token_id, token_secret
- **Notes:** NetSuite analytics via SuiteAnalytics Connect over JDBC — read-only but with full analytical SQL pushdown. Pair with NetSuite REST when writes are required.
- **Quirks:**
  - Read-only. Use this mode for heavy analytical SQL; use REST/SuiteQL when you also need to write.
  - Connects over JDBC through a local driver sidecar (requires the JDBC sidecar to be enabled in the deployment).
  - Host normalization: the JDBC URL uses the hyphen form of the host while the account realm inside CustomProperties(AccountID=...) uses the underscore form — they intentionally differ.
  - The JDBC password is a composite TBA-signed token (realm, consumer key, token id, nonce, timestamp, signature, HMAC-SHA256).
  - Supports a much richer SQL feature set than SuiteQL (windows, CTEs, lateral joins, regex/JSON), making it the stronger reporting/analytics path.

## Monday.com  `monday`

- **Category:** saas
- **Auth:** API token (sent as a raw Authorization header value, no Bearer prefix)
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $contains, $not_contains, $starts_with, $ends_with, $empty, $not_empty, $between
- **Credentials:** api_key, api_version
- **Notes:** Monday.com work-management boards over GraphQL with read and write. Filtering pushes down to ItemsQuery; aggregation is performed in the query engine.
- **Quirks:**
  - Talks GraphQL to api.monday.com/v2; filters become a parameterized ItemsQuery, so values flow through GraphQL variables (no string interpolation).
  - The query container is the board ID and the collection is an optional group ID (honored as a group filter).
  - Insert/update/delete are supported; there is no merge/upsert.
  - Writes map record keys to Monday column IDs and skip non-writable column types.
  - Operator set differs from the SQL adapters: it adds $not_contains and $not_empty and does not support $in/$nin/$like/$expr.
  - Known current limits: cursor pagination across very large boards, subitems, and per-call complexity/rate-limit budgeting are not yet handled.

## Microsoft SQL Server  `mssql`

- **Category:** database
- **Auth:** Username / password (ODBC); TLS validated by default
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with, $expr
- **Credentials:** host, port, username, password, database, tls_mode
- **Notes:** Microsoft SQL Server over ODBC with full read/write/discover and SQL pushdown for filtering and aggregation.
- **Quirks:**
  - T-SQL dialect: identifiers quoted with [ ], paging uses OFFSET ... FETCH, upserts use T-SQL MERGE.
  - OFFSET/FETCH paging requires an ORDER BY; when a limit is set without an explicit order, a deterministic ORDER BY is injected automatically.
  - Discovery enumerates user databases (skips system databases) and reads column metadata from INFORMATION_SCHEMA, including identity/computed flags.
  - TLS certificate validation is on by default; disabling validation or encryption is an explicit, named opt-out.
  - Connects via ODBC (default: ODBC Driver 18 for SQL Server); a pre-assembled connection string can be supplied instead of discrete fields.
  - Identifier quoting is charset-validated; raw SQL expressions ($expr, select expressions) remain a trusted-author surface.

## MySQL  `mysql`

- **Category:** database
- **Auth:** Username / password; TLS cert/hostname validated when ssl_mode is 'required'
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with, $expr
- **Credentials:** host, port, username, password, database, charset, ssl_mode
- **Notes:** MySQL over a native async driver with full read/write/discover and SQL filter + aggregation pushdown.
- **Quirks:**
  - MySQL dialect: backtick identifier quoting, LIMIT/OFFSET paging, and INSERT ... ON DUPLICATE KEY UPDATE for upserts.
  - Discovery reads INFORMATION_SCHEMA and filters out system schemas (information_schema, mysql, performance_schema, sys).
  - TLS: ssl_mode 'required' validates the certificate and hostname; weaker modes do not validate.
  - Connects with a native async MySQL driver wrapped to the common SQL adapter surface.

## PostgreSQL  `postgres`

- **Category:** database
- **Auth:** Username / password; TLS required by default (sslmode=require)
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with, $expr
- **Credentials:** host, port, username, password, database
- **Notes:** PostgreSQL with full read/write/discover and SQL pushdown. The same adapter class also powers the internal workspace store (see internal-postgres-workspace).
- **Quirks:**
  - PostgreSQL dialect: double-quote identifier quoting, LIMIT/OFFSET paging, and INSERT ... ON CONFLICT (...) DO UPDATE / DO NOTHING for upserts.
  - Discovery reads information_schema and filters out pg_catalog/information_schema system schemas.
  - TLS is required by default (sslmode=require).
  - Connects via a synchronous Postgres driver (psycopg2-style %s parameter binding).

## Internal Postgres Workspace  `internal-postgres-workspace`

- **Category:** internal
- **Auth:** Azure Managed Identity (token-minted per connection; no stored password)
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with, $expr
- **Credentials:** —
- **Notes:** A built-in per-tenant Postgres workspace for staging, intermediate results, and pipeline scratch data — zero credential setup, structurally isolated from platform internals.
- **Quirks:**
  - A built-in, per-tenant scratch/staging database exposed as the 'workspace' bridge — no credentials to configure; it ships with the platform.
  - It is a SEPARATE database from the platform's operational tables, and a workspace query connection is pinned to that database. Because PostgreSQL cannot query across databases on one connection, a workspace query structurally cannot read or modify platform internals.
  - Access uses a least-privilege, non-admin managed identity scoped only to the workspace database.
  - Table create/add-column/drop are gated by a workspace-manage admin permission; table and column names are validated against a strict identifier pattern and a type allowlist.
  - Reads without an explicit limit default to 1000 rows; each statement is bounded by a 30-second timeout.
  - Cross-database joins (workspace data joined to another bridge's database in one SQL query) are not possible — combine results in a pipeline or report instead.

## QuickBooks Online  `quickbooks-online`

- **Category:** erp
- **Auth:** OAuth 2.0 with a rotating refresh token
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with, $expr
- **Credentials:** client_id, client_secret, refresh_token, realm_id, environment
- **Notes:** QuickBooks Online accounting data over the v3 REST API with read, write, and discover. Filtering pushes down to the QBO query language; aggregation is done in the engine. (Newer adapter; verify availability in your deployment.)
- **Quirks:**
  - Targets the QuickBooks Online Accounting API v3 query endpoint; read filters render into the QBO query language and the literal query rides in the URL.
  - QBO uses ORDERBY as a single word (not ORDER BY) and STARTPOSITION/MAXRESULTS for paging — the adapter emits these forms automatically.
  - QBO literals differ from standard SQL (booleans render as true/false, single quotes are backslash-escaped), so it does not reuse the generic SQL inliner.
  - OAuth refresh-token rotation: the token endpoint requires form-encoded bodies, access tokens are cached until ~60s before expiry, and a 401 triggers a single refresh-and-retry. Refreshes are serialized so concurrent calls don't collide.
  - Writes: insert posts the full object; update is a sparse update (SyncToken auto-fetched when not provided); delete uses Id+SyncToken.
  - Name-list entities (Customers, Items, Accounts, Vendors) are not hard-deletable — they are deactivated via Active=false; CompanyInfo/Preferences are read-only.
  - Has both production and sandbox base URLs; a minor-version parameter is sent with queries.

## Stripe (preview)  `stripe`

- **Category:** saas
- **Auth:** API secret key (Bearer)
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with
- **Credentials:** secret_key
- **Notes:** PREVIEW connector for Stripe billing/payments data over the Stripe REST API. Read plus per-collection writes; no pushdown yet (filter, order, and aggregation run in the query engine). Treat as evaluation-grade until it reaches 1.0.
- **Quirks:**
  - PREVIEW / pre-1.0 (0.1.0): evaluation-grade, not production-hardened; collection coverage is still evolving. Pin behavior in tests before depending on it.
  - Declares where=False and order=False, so the engine reads rows from the Stripe REST API and applies filtering, ordering, and aggregation in memory (bounded by the post-process row budget).
  - Writes are gated per collection: some Stripe objects are read-only or can only be cancelled/voided rather than hard-deleted.
  - No merge/upsert.

## Generic JDBC  `jdbc-generic`

- **Category:** generic
- **Auth:** Username / password (per the JDBC connection URL); driver JAR uploaded to the bridge
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** $eq, $ne, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin, $between, $empty, $contains, $starts_with, $ends_with, $expr
- **Credentials:** driver_class, connection_url, username, password
- **Notes:** Configurable JDBC connector for any database with a JDBC driver — supply the driver class, connection URL, and driver JAR. Full read/write/discover and SQL filter + aggregation pushdown. Same substrate that powers NetSuite SuiteAnalytics Connect; requires the JDBC sidecar.
- **Quirks:**
  - Generic path to any JDBC-speaking database (Oracle, Db2, Snowflake, Databricks, MariaDB, Redshift, and more): supply driver_class, connection_url, and upload the vendor JDBC driver JAR.
  - Pushes a full analytical SQL surface down to the source: WHERE, ORDER BY, GROUP BY, aggregates, DISTINCT, HAVING, joins, and select expressions.
  - merge/upsert is not assumed uniformly because merge syntax differs by dialect; express upserts as update-then-insert where unsupported.
  - Requires the JDBC driver sidecar to be enabled in the deployment (same sidecar used by NetSuite SuiteAnalytics Connect).
  - $expr passes a raw SQL fragment through — a trusted-author surface.

## Generic HTTP/REST  `http-rest-generic`

- **Category:** generic
- **Auth:** Bridge-resolved: OAuth 2.0 client-credentials, bearer/static token, or API-key header — credentials held in Key Vault
- **Capabilities:** read, write, discover, pushdown-filter, pushdown-aggregation
- **Pushdown operators:** author-declared subset (whatever build_request translates into the target API's query parameters)
- **Credentials:** base_url, auth_config
- **Notes:** Generic HTTP/REST connector substrate for integrating any REST or GraphQL API without a native adapter. Author build_request/parse_response scripts (sandbox-compiled); OAuth2/auth-header resolution via the bridge; SSRF-checked egress. The supported way to reach an arbitrary API through the same UQL surface, capability model, and RBAC as a native connector.
- **Quirks:**
  - First-class connector substrate for arbitrary REST/GraphQL APIs: author sandbox-compiled build_request and parse_response scripts to map UQL queries to HTTP requests and responses to rows.
  - Authentication is resolved through the bridge (OAuth2 client-credentials tokens are fetched, cached, and refreshed); scripts read resolved values, never raw secrets.
  - Scripts run under the pipeline sandbox (import allowlist, no filesystem, no raw sockets) and can only egress through the governed SSRF-checked, allowlisted HTTP client.
  - Declare only the pushdown you actually implement; anything not pushed down is applied in-engine over returned rows (bounded by the row budget).
  - Distinct from and more capable than a pipeline's ad-hoc ctx.http calls: a reusable, credentialed, RBAC-scoped, UQL-queryable data source.