Documentation / Getting Started

Core Concepts

Precise definitions of every Nexus building block — bridge and connection, adapter and connector, UQL, report, pipeline, workspace, Site, skill, RBAC roles and grants and execution roles, and the MCP server — and how they fit together.

Nexus by Stingray is a per-tenant data platform that runs inside your own Azure subscription. One deployment serves one organization, fully isolated from every other. This page is the glossary and hub: it defines each building block precisely and links to its deep guide. Read it once and the rest of the documentation reads cleanly.

The shape of a Nexus deployment

Nexus connects to the systems you already run through bridges, lets you discover and query across them with UQL, and gives you things you author on top: reports, pipelines, Sites, and skills. Everything you author is version-controlled, RBAC-gated, and reachable over REST or the built-in MCP server — with the same permission checks and the same audit trail whether the caller is a person, an application, or an AI agent.

Bridge (connection)

A bridge is a named, configured connection to one data source — for example (mssql, "production") or (netsuite, "prod"). "Connection" and "bridge" refer to the same thing. A bridge exists because its secrets exist in your Key Vault; credentials are never inlined into a report or pipeline. Bridges have two scopes:

Service bridge — owned by the tenant and managed by admins; usable by anyone whose RBAC permits the report or pipeline that references it.
User bridge — owned by a single user and usable only by that user, so a person can connect with their own credentials without an admin ever seeing them.

Credential resolution is server-side and identity-bound: the resolver only ever returns secrets for the authenticated identity, and it fails closed. See Connections & Bridges and Secrets.

Use it when: you need Nexus to read from or write to a real system.

Adapter (connector)

An adapter — also called a connector — is the code that teaches Nexus how to talk to a class of source. Adapters ship as signed bundles: each carries a signed manifest plus an attestation and transparency-log entry, is dual-signed (ES256) by two separate Key Vaults, and is verified fail-closed before it loads. A bridge is an instance of an adapter with your endpoints and credentials.

Nexus ships native adapters for SQL databases (PostgreSQL, MySQL, SQL Server), NetSuite, QuickBooks Online, and Monday. For anything without a native adapter, two generic connectors cover the long tail: a generic HTTP/REST connector (author build_request/parse_response scripts with OAuth2/auth resolution and SSRF-checked egress) for any REST API, and a generic JDBC connector for any database with a JDBC driver. Each adapter declares its capabilities — which operators and pushdown it supports — so the query engine knows what to push down versus finish in-engine. See the Connectors Overview and Capability Matrix.

Workspace

The workspace is a baked-in, per-tenant PostgreSQL scratch database you use to stage, join, and aggregate intermediate results. It has no credentials to manage and its own managed identity, and it is structurally isolated from Nexus's operational tables — it lives in a separate database reached by a separate identity, so UQL run against the workspace literally cannot reach the platform's own tables. Reach it from a pipeline via ctx.workspace or query it like any other bridge. See Internal Workspace.

Use it when: you need a place to stage or combine data that isn't one of your source systems — without standing up a warehouse.

UQL — discover and query

UQL (Unified Query Language) is how you explore and read across bridges with consistent semantics. The pattern is always: list your bridges, discover a source's schema (its collections and fields) so you never guess names, then query. The engine hands your WHERE to the adapter as a hint and re-applies it in memory unless the adapter declares full pushdown and every operator is pushable; LIMIT/OFFSET are pushed only when it's safe, and unsupported group-by or aggregation is evaluated in-engine (a clean, bounded fallback — never silently wrong). This means results are always correct; only where the work runs varies by adapter. See UQL Introduction and the Operators Reference.

Use it when: you want an ad-hoc look at what a source holds, or to shape a query before saving it as a report.

Report

A report is a saved, parameterized query defined in JSON — supporting joins, group-by, aggregations, and named parameters. Reports push filtering and aggregation down to the source wherever the adapter supports it, so heavy work runs on the database rather than in memory, and fall back to in-engine evaluation otherwise. Save a report once, then run it on demand — from the UI, an application, or an AI agent — with different parameters each time. See Reports.

Use it when: a query is worth keeping, sharing, or running repeatedly with different inputs.

Pipeline

A pipeline is sandboxed automation written as a Python module — not a DSL and not a visual flow. Each pipeline exports async def run(ctx) and receives a typed context object:

async def run(ctx):
    rows = await ctx.adapters.sales.query(
        "SELECT * FROM orders WHERE status = 'open'"
    )
    await ctx.workspace.upsert("open_orders", rows)
    ctx.logger.info(f"staged {len(rows)} open orders")

ctx exposes ctx.adapters, ctx.secrets, ctx.http (allowlisted, SSRF-checked), ctx.workspace, ctx.variables, ctx.files, ctx.logger, and ctx.nexus (child runs). Pipeline code is compiled under a sandbox with an import allowlist — exec/eval, file I/O, and unrestricted network are stripped at the AST level. Runs execute on a durable queue with per-run timeouts, row-count constraints, cron scheduling, and full run history including the complete traceback on failure. Authoring a pipeline is a code-execution action and is RBAC-gated accordingly. See Pipelines Overview, the Pipeline SDK, and Reliability & Operations.

Use it when: you need scheduled or multi-step logic — moving data between systems, calling an API, transforming and staging results.

Site

A Site is a web page Nexus hosts at /sites/{slug}/. Site pages call the Nexus API as the viewing user, so what each visitor sees is bounded by their own RBAC permissions; the user's token is never exposed to page code, and Sites set a strict content-security policy that limits where a Site's JavaScript can talk. See Sites Overview.

Use it when: you want a lightweight dashboard or internal page backed by live Nexus data, without standing up a separate web app.

Skill

A skill is a markdown playbook an AI agent can pull on demand to learn how to do something in your Nexus instance. Some skills are first-party, image-baked guides that ship with the product; others are playbooks your own team authors. Skills are versioned like any other authored artifact. See Skills.

Use it when: you want to capture and reuse a procedure for agents working over the MCP.

RBAC — roles, grants, and execution roles

Access throughout Nexus is governed by role-based access control with resource:action permissions. Three terms matter:

Role — a named set of permissions. Every tenant has the built-in roles Reader and Admin, and you can define custom roles for anything in between. Roles apply to both users and application principals.
Grant — a per-resource scoped assignment: it ties a role (or specific permissions) to a specific pipeline, report, bridge, file, Site, or tool, for a specific user or app. Grants are how you say "this app may run this report and nothing else."
Execution role — a curated role you pin to a pipeline or report so it runs with exactly that authority, without granting the invoking user any standing elevation. The elevated authority exists only for the duration of that run, and only for that artifact.

Admin edit-locks protect authored artifacts from concurrent edits, and service-bridge vs. user-bridge credential isolation means one user's credentials can never resolve for another user. See Roles & RBAC and Execution Roles.

The MCP server

Nexus exposes a built-in Model Context Protocol (MCP) server that mirrors its REST surface. An AI assistant connects to your instance and uses the same capabilities — discover schemas, run queries and reports, author and run pipelines, build Sites, manage configuration — all subject to the same RBAC and audit. The MCP session is identity-bound: the agent acts strictly within the connecting identity's permissions, never more. See MCP Server and Connecting AI Agents.

Use it when: you want an agent or external tool to operate Nexus programmatically.

One entity surface, one version history

The authored kinds — pipeline, report, Site, and skill — share one unified set of verbs keyed by kind and id, over both REST and MCP:

Verb	Does
`list`	list entities of a kind
`get`	read the live version or any past revision
`save`	create or update (validates and auto-versions)
`validate`	check without saving
`delete`	remove (recorded as a deletion)
`history` / `diff` / `restore`	review history, compare revisions, roll back

Every save is a commit in a per-tenant, version-controlled git repository (stored on Azure Files) — you can read history, diff revisions, and restore any version, so nothing authored is ever lost. Writes are multi-replica-safe via an advisory lock; reads are lock-free. See Version Control.

How it all fits

A typical flow: add a bridge, discover its schema, save a report or write a pipeline to shape the data, stage intermediate results in the workspace, optionally surface it through a Site, and drive any of it from an agent through the MCP server — with RBAC and audit governing every step and version control recording every change.