Docs / PowerBI & OData

#PowerBI & OData

Helm exposes a read-only OData v4 feed over your tenant's entities, purpose-built for BI tools — PowerBI's "Get Data → OData feed" in particular. Every active entity type you can read becomes an entity set (e.g. "Vessel Certificate" ↔ Vessel_Certificate), and relationship rules surface as navigation properties PowerBI follows to build a relational model.

#Why OData?

  • Query folding — PowerBI translates filters and sorts into OData query options before hitting the server, so refreshes only pull the rows a report actually needs instead of the whole table.
  • Discoverable relationships — the feed's metadata document tells PowerBI how your entity types relate, so multi-table reports don't require manual joins.
  • It's the same authenticated, tenant-isolated API surface as everything else in Helm — no separate data-export pipeline to maintain.

#Connect PowerBI

  1. In PowerBI: Get Data → OData feed, and set the URL to https://api.helm.bridge-labs.com/entity/odata (see Auth & API Gateway for the staging host).
  2. When prompted, choose Basic authentication:
    • User name — the token's client_id
    • Password — the token's secret (helm_tk_…)
  3. Pick the entity sets to import. Join tables for relationships (e.g. VesselToVesselCertificate) are listed too — include one whenever you need to relate two entity types in your model. PowerBI discovers the relationships itself from the feed's metadata document.

From there, filter, sort, merge, and visualize as usual — see the PowerBI docs for report-building help.

#Provisioning a token

Mint a Personal Access Token and, for a BI integration, scope it down with a least-privilege policy rather than handing over your full permissions — see Provisioning for minting a token and Provisioning for binding a read-only policy to it. Grant read on each entity type (and any relationship rule used by $expand) you want PowerBI to see.

The token is revocable at any time (DELETE /access/api-tokens/{tokenId}) without touching the policy or its grants.

#Supported query options

PowerBI Import mode drives the feed with:

  • $filter — eq ne gt ge lt le, and or not, parentheses, contains/startswith/endswith, and null/true/false/ISO-datetime literals. Only indexed attributes (see Entities & Data Model) and entity-level fields (id, name, created_at, updated_at) are filterable — filtering an un-indexed attribute returns 400.
  • $orderby — the same indexed/entity-level fields.
  • $select, $top, $skip, $count.
  • $expand — a relationship rule's related entities nest inline in the response.
  • Server-driven paging via @odata.nextLink — PowerBI follows it automatically on refresh, so you don't need to configure page size.

$apply (server-side aggregation) isn't supported yet — PowerBI's Import mode aggregates locally, so bring the data in with $filter/$orderby/$top and aggregate in the report.

#Gotchas

#Relationship cardinality

The feed's metadata tells PowerBI which columns relate two entity types, but not whether the relationship is one-to-one, one-to-many, or many-to-many — PowerBI infers it from the data it sees on first import. If the initial data happens to have at most one related row per row, PowerBI may guess one-to-one; a later refresh that sees multiple related rows then errors on duplicates. Fix it by editing the relationship's cardinality in PowerBI's model view.

#Ambiguous (circular) relationships

If two entity types are related through more than one relationship rule (e.g. a "Vessel" relates to "User" via both an owner rule and an administrator rule), PowerBI may report an ambiguous-relationship error when you build a visualization. Deactivate whichever relationship isn't relevant to that report — see PowerBI's relationship troubleshooting guide.