Skip to main content

Connect a BI or reporting tool

The goal is that your existing analysts keep their existing tools. A reporting or BI tool connects over a protocol it already speaks, and the read it performs passes through the same governed query plan as any other read, the same row filters and column masks apply whether the caller is a BI tool or an agent. There is no second, unpoliced door to the data.

This guide covers the three externally-connectable query surfaces and how to point a tool at each. For the model behind them, see Reporting & BI tool support.

The surfaces and their ports​

All external query traffic terminates on the node service (the single deny-by-default front door) which proxies to the data engine. Collectively these external query faces are External Data Access. The ports below are the shipped defaults; an operator may rebind or disable any of them (see the Ports & protocols reference).

Figure: the connect surfaces and where they resolve. The two live query surfaces (green) (the PostgreSQL wire protocol and Arrow Flight SQL) resolve through one governed plan and return a filtered result carrying its classification and lineage; Flight is a real served pyarrow.flight gateway, proven against a stock client. Delta Sharing (green) serves both its recipient and its admin surface, with the security plane enforced on the served files. The Iceberg REST catalog (amber, dotted) serves registry-backed catalog metadata, not a live table load. See the cautions below.

Table equivalent

SurfaceExternal port(s)ProtocolAuth postureStatus
PostgreSQL wire9950Postgres wire, in-band SSL on one portPer-database credential → directory entity → grants; require_tls off by defaultLive: the workhorse for Power BI, Tableau, DBeaver, psql, any ODBC/JDBC tool
Arrow Flight SQL59950 clear · 59951 TLS (off by default)gRPC / Arrow columnarBasic handshake → minted short-lived bearer tokenLive: high-throughput columnar pulls, multi-cell endpoint fan-out; round-trip proven against a stock pyarrow.flight client
Iceberg REST catalog/api/v1/iceberg/v1 on 8080 (8443 when TLS enabled)Iceberg RESTHTTP Basic or Bearer over TLS → policy enforcedCatalog reads only: registry-backed reads; writes are in-memory, non-persistent
Delta Sharing/delta-sharing on the data service; admin at /v1/data/delta-sharing/admin, proxied to the console by the nodeDelta Sharing RESTBearer recipient token, resolved to a governed grantLive: recipient reads are security-plane enforced (table authorization, row filters pushed into the predicate, column masks, org and node scope, metered). The Net Potential Gain gate is not installed on this path
Compatibility comes from the protocol

The platform serves standard protocols, so a tool connects because it already speaks PostgreSQL wire, Arrow Flight SQL, Delta Sharing or GraphQL, not because a per-tool integration was written for it. That is the durable kind of compatibility: it does not need a certification matrix to stay true.

Worth knowing when testing: a connector reporting healthy proves the handshake, not an end-to-end data transport. Validate with a real query.

Prerequisites​

  • A running cell reachable on the network from the tool. See Bring up a node if you do not have one yet.
  • A per-database credential for the SQL surfaces. This is a real identity, it resolves through a directory entity to real grants, so the login you use carries exactly the permissions that identity has, and no more. Mint a data credential shows how to issue one over the public API for a workspace or a clean room.
  • The cell's hostname or address, and the port for the surface you are using.
  • For TLS, the cell's CA certificate if the host does not already trust it.

Connect over the PostgreSQL wire (the workhorse)​

The PostgreSQL-wire gateway is the broadest path: standard ODBC and JDBC drivers connect over it, so most BI tools need no proprietary driver. The gateway listens on 9950 and negotiates SSL in-band on the same port (the standard Postgres SSLRequest handshake), so you do not use a separate TLS port.

Verify the surface with psql first​

Prove the connection with a plain client before wiring a BI tool to it:

psql "host=CELL_HOST port=9950 dbname=YOUR_DB user=YOUR_USER sslmode=require"

sslmode=require exercises the in-band SSL negotiation. If the cell is configured with require_tls, a non-TLS attempt is refused. A successful psql prompt means the wire, the credential, and TLS all work, the BI tool will use the same four facts.

Point Power BI at it​

Power BI Desktop connects over its built-in PostgreSQL database connector:

  1. Get data → PostgreSQL database.
  2. Server: CELL_HOST:9950, include the port after a colon.
  3. Database: your database name.
  4. Choose Import or DirectQuery. DirectQuery keeps every query resolving live through the governed plan (recommended where policy must apply per query); Import pulls a governed snapshot once.
  5. Under the connection's credentials, choose Database and enter the per-database username and password; enable encryption so the client requests SSL.

Tableau, DBeaver, Metabase, and other tools follow the same shape: choose their PostgreSQL source type, use host CELL_HOST, port 9950, your database, credential, and require SSL.

Every Postgres login is a real identity

The credential is not a shared service account behind the wire, it resolves through a directory entity to that identity's actual grants. Two analysts with different clearances connecting with their own credentials see different rows and masked columns from the same query, because the policy is compiled into the plan, not layered onto the tool.

Connect over Arrow Flight SQL (columnar)​

For high-throughput, columnar pulls, the Arrow Flight SQL gateway serves the same governed engine over gRPC/Arrow. It is a real pyarrow.flight server with a real Arrow Flight auth handler:

  • 59950: clear (for a trusted intra-network segment).
  • 59951. TLS: enabled when server certificates are configured.

Point an Arrow Flight SQL client at grpc://CELL_HOST:59950 (or grpc+tls://CELL_HOST:59951). Authenticate with the basic handshake to mint a short-lived bearer token, run SQL, and read the result as Arrow record batches. Those batches carry the same governance as the SQL wire, column masking is applied on the served stream, so an unauthorized column is masked in the bytes the client receives, not filtered client-side. The surface is a second reach into one engine, not a second policy.

Multi-cell fan-out and failover. GetFlightInfo returns one Flight endpoint per live cell, so a client that follows the endpoints pulls from every cell that holds a slice of the result, a native multi-cell read, not a single-cell proxy. The endpoint set is re-planned against current cell membership, so as cells join or leave (elastic expand / contract) a subsequent GetFlightInfo reflects the live fleet rather than a stale list. The gateway also registers itself for catalog/fabric discovery so the surface is findable across the fleet.

Configured through Config Policy. Arrow Flight SQL is the first service governed by the unified config plane (data.flight_sql, operator-only): an operator enables and tunes it as a signed, topology-scoped config document, the same way the nine administrative sections are authored.

Iceberg REST catalog: catalog reads​

The Iceberg REST catalog is reachable externally through the node proxy at /api/v1/iceberg/v1/... on the public HTTP port (8080, or 8443 when TLS is enabled). It authenticates with HTTP Basic or Authorization: Bearer <token> over TLS, and every list/load is policy-enforced (a forbidden table returns 404 rather than revealing its existence). Iceberg-native tools (Spark, Trino, and similar) can read the standard catalog endpoints, config, namespaces, and tables.

Reads are registry-backed; writes are not persisted

The catalog read endpoints return real, registry-backed metadata. The write paths (create / drop / rename) are in-memory only. They do not persist to the lakehouse. Treat this surface as a catalog-read integration, not a read-write catalog. For a governed table read into a BI tool, use the PostgreSQL wire or Arrow Flight SQL surfaces above.

Delta Sharing: served, with one gate not installed​

Delta Sharing is a full, spec-compliant protocol server (shares, schemas, tables, versioned metadata, and token-scoped file access), and the served files are security-plane enforced: a share is a governed grant, not a raw file handout. A recipient read carries table authorization, row filters pushed into the query predicate, column masks, organization and node scope, and metering.

Two surfaces are served. The recipient surface is what an external Delta Sharing client speaks to. The admin surface (shares, recipients, grants) sits under its own route prefix and is what the console reaches, through the node's public admin surface.

One boundary is worth stating exactly, because it is a deliberate omission rather than missing work: the Net Potential Gain gate is not installed on the Delta Sharing server path. The decision auditor is, so a federation grant or revoke lands on the durable audit chain, but the gate that refuses elsewhere in the platform does not evaluate this path. A deployment that needs sharing decisions to pass that gate should treat it as a requirement to raise, not as something already enforced here. Where the node has no identity on disk, the admin surface still serves but its grants and revokes are recorded without a witness, which the service logs at startup.

Native BI artifact generation (outbound)​

Beyond a tool reading from the platform, the platform can generate native BI configuration, semantic models for tabular BI, dashboards, and best-practice analysis, and push it to a reporting tool. That outbound path is a governed chokepoint: a publish, refresh, or export is deny-by-default and fail-closed, must clear the Net Potential Gain gate, and its egress is checked against the binding's destination before any byte leaves. These surfaces appear under the catalog's Connections and Endpoints.

Verify it worked​

#CheckWhy this one
1The tool connectsProves the wire and the credential, nothing more
2A real query returns rowsA healthy connection is a handshake. Only a query proves the data path
3The rows are policy-filteredConnect as a less-privileged user and confirm you see less, not an error
4Activity is attributedThe query shows against the entity behind the credential

Step 2 is the one that matters. A connector reporting healthy proves the handshake, not an end-to-end transport, and a catalog returning success on a metadata call has not loaded a table.

Troubleshoot​

SymptomLikely causeCheck
Connection refused on 9950Gateway not exposed or reboundConfirm the node's external SQL port; see ports reference
TLS handshake failsrequire_tls on, client not requesting SSLSet sslmode=require / enable encryption in the tool
Login rejectedCredential not a valid directory entity, or no grantsConfirm the per-database credential and its grants
Rows/columns missing vs. a colleagueWorking as designedThe governed plan applies your identity's row filters and masks
Iceberg tool "loads" nothingMetadata-only surfaceUse the SQL or Flight SQL surface for a live read

Across the deployment matrix​

  • Single-cell, a tool connects to the cell over the wire; the read is governed on that cell.
  • Multi-cell: the same protocols reach any cell; federation gives a tool one view over a catalog that spans cells.
  • Sovereign / air-gapped, the protocol servers run on the cell with no vendor control plane in the path; a tool on the same isolated network connects normally.
  • Cloud-enabled, the same protocols reach cloud-hosted tools.