Flax documentation

Guides and reference for Flax: connecting a warehouse, modelling, dashboards, sheets, automation, the REST API and MCP.

Getting started

  • What is Flax? — A warehouse-native BI platform — a git-backed semantic layer, exploration, spreadsheet modelling, dashboards, and an AI assistant, all governed as code.
  • Quickstart for analysts — A 10-minute path from signing in to a saved chart on a dashboard — connect a warehouse, explore the model, and visualize the result.
  • Quickstart for viewers — For people who consume dashboards — find shared content, filter and cross-filter, drill down, comment, and subscribe to deliveries.
  • Quickstart for admins — Set up an organization end to end — invite members, configure teams and roles, apply data entitlements and RLS, and turn on SSO and MFA.
  • Quickstart for developers — The programmatic path — create a service account and API token, run a query over REST, and connect an agent to Flax over MCP.
  • Core concepts — The vocabulary used throughout the Flax docs — connection, project, semantic model, explore, sheet, workbook, chart, dashboard, action, and more.
  • Demo sandbox — Try Flax with no login at /demo — it runs entirely in your browser on DuckDB-WASM, and nothing you do is saved to any server.

Connecting data

  • Connecting data — How Flax connects to the data warehouse you already own, the warehouses it supports, and where you manage connections and credentials.
  • Connect Postgres — Set up a PostgreSQL connection — required fields, TLS mode, and least-privilege credentials for a read-only analytics role.
  • Connect Snowflake — Set up a Snowflake connection with key-pair authentication — required account fields and a least-privilege warehouse role.
  • Connect Databricks — Set up a Databricks SQL warehouse connection — the workspace host, HTTP path, and a personal access token.
  • Connect BigQuery — Set up a Google BigQuery connection with a service-account key — the project and a least-privilege data-viewer role.
  • CSV uploads — Upload a file and query it in Explore without connecting a warehouse — supported formats and how uploaded data becomes a queryable source.
  • Ingest a dbt project — Point Flax at your dbt project in git so your existing dbt models become Flax's semantic model, ingested from the compiled manifest.
  • Caching & performance — How Flax keeps queries fast — connection pooling, a per-tenant result cache, and the tiered source cache, plus when a query hits cache versus your warehouse.
  • Connection security — How Flax protects warehouse credentials — an encrypted secrets key-ring with rotation, and an SSRF egress guard that vets every outbound connection.

Modeling

  • Modeling overview — How Flax's dbt-compatible, git-backed semantic model turns raw warehouse tables into governed, reusable metrics
  • Dimensions and measures — Define the attributes you group and filter by, and the aggregations you measure, in dbt-compatible YAML
  • Relationships and joins — Declare joins between models so a single query can span orders, customers, and more
  • Semantic YAML reference — Every field the Flax semantic layer supports, from model and column metadata to the flax extension
  • SQL compilation — How Flax compiles the semantic model to dialect-correct SQL, pushes work to the warehouse, and uses embedded DuckDB when needed
  • Row-access filters — Restrict which rows a user can see using semantic-layer access filters enforced in compiled SQL and by Postgres row-level security
  • Lineage — Trace how models and fields depend on sources and on each other with the lineage view
  • Write-back — Edit the semantic model from the UI and open a governed GitHub pull request instead of mutating production directly

Querying & exploring

  • Querying & exploring — The Explore page is Flax's point-and-click query builder — pick dimensions and measures and Flax compiles dialect-correct SQL that runs in your own warehouse.
  • Building queries — Pick dimensions and measures, add filters, sorts, and a limit, and watch results update as Flax recompiles and re-runs the query in your warehouse.
  • The SQL runner — A governed, read-only SQL surface for writing SQL by hand — SELECT-only, entitlement-gated, off by default, and fully audited.
  • Drill-down — Click a mark for a menu of actions on that value — see the rows behind it, drill into a finer dimension, or open it as a sheet.
  • Query detail — Inspect any query — view the exact dialect-correct SQL Flax compiled and the raw result rows returned by your warehouse.
  • View in sheet — Open the data behind any chart in a live, governed sheet — the seamless handoff from a dashboard to local verification and deeper analysis.

Sheets

  • Sheets — Spreadsheet modelling built on a governed query result — a familiar A1 grid with formulas, formats, multi-tab workbooks, and real-time collaboration.
  • Formulas and functions — The Flax formula language — cell and range references, operators, error values, and a reference of the built-in functions grouped by category.
  • Workbooks and tabs — Organize related work across multiple tabs in one workbook and reference cells on other tabs with Excel-style qualified references.
  • Editing — Spreadsheet editing parity — number and date formats, sort and filter, find and replace, insert and delete rows and columns, and per-user undo/redo.
  • Import and export — Export a sheet to CSV or Excel, paste data in from the clipboard, and understand how governed data enters a sheet.
  • Collaboration — Real-time multiplayer editing — live presence, edits that sync as they happen, per-user undo, and named version history you can restore.

Visualizing data

  • Visualizing data — How Flax turns a query result into a saved chart — the role-based chart grammar and the chart editor.
  • Chart types — The chart types Flax supports and when to reach for each — bar variants, line, area, pie, waterfall, pivot, box plot, and choropleth maps.
  • Formatting & theming — Format numbers, set legends and value labels, and brand your charts with an org color theme or a per-chart palette.
  • Dashboards — Create a dashboard, arrange charts with drag-and-drop, and organize content into tabs.
  • Dashboard blocks — Annotate dashboards with markdown text blocks and organize them with section separators.
  • Interactivity — Make dashboards explorable with cross-filtering, dashboard filters and controls, and click-to-drill.
  • Exporting charts — Download charts and dashboards as PDF or PowerPoint, and render server-side PNG images for embedding — all generated on the server with no client dependencies.

Automation & AI

  • Actions — Automate Flax with trigger→effect actions — a control change, schedule, threshold, or button that fires webhooks, Slack, Discord, or email, with full run history.
  • Scheduled deliveries — Deliver a dashboard or chart on a recurring schedule to email, Slack, or a webhook — optionally only when a metric crosses an alert threshold.
  • AI assistant — The in-app assistant that answers data questions in natural language by running governed queries and proposing charts and dashboards for you to save.
  • AI settings & usage — Configure the AI assistant with your own provider key and scope, and track what the assistant has produced across your organization.
  • Agents & graphs — Scheduled LLM agents that read your dashboards, charts, sheets and datasets and report what they find — and graphs that run several of them in order, each reading what the one before it concluded.

Administration & security

  • Sharing and permissions — Share dashboards, charts, and sheets with teams and people, set org visibility, and star content you use often.
  • Comments and notifications — Discuss dashboards, charts, and sheets with threaded comments and @-mentions, and keep up with activity in your notification inbox.
  • Organization — Understand what an organization contains in Flax and manage its settings.
  • Members and invitations — Invite people to your organization by email and manage their membership, role, and seat.
  • Teams and RBAC — Group members into teams and use role-based access control to decide who can build, edit, and administer content and data.
  • Data entitlements — Grant teams access to specific data sources and understand how tenant and team isolation is enforced by Postgres row-level security.
  • User attributes — Assign key/value attributes to users and teams to drive row-access filters and personalize what each person sees.
  • SSO — Configure per-organization enterprise single sign-on with OIDC so members sign in through your identity provider.
  • Security — Protect your account with multi-factor authentication, active session management, and the password policy.
  • Audit log — Review a chronological record of security- and governance-relevant activity in your organization.
  • Billing and usage — Manage your plan and payment through Stripe and track query and row usage across your organization.
  • Privacy and GDPR — Export your personal data and delete your account to support data access, portability, and erasure rights.

Developers

  • Developers overview — The Flax programmatic surface — a REST API, an MCP server, and embedding — for building on top of your warehouse-native BI
  • Authentication — Authenticate to the Flax API with service-account tokens (flax_pat_…) carrying read and write scopes
  • OAuth for MCP clients — Flax's built-in OAuth 2.0/2.1 authorization server for MCP clients — discovery, dynamic client registration, authorize, token, and consent
  • MCP overview — The Flax Model Context Protocol server — expose your semantic layer to agents, with all access enforced by the caller's scopes and RLS
  • Local MCP server — Run the flax-mcp stdio server locally — configure it with FLAX_BASE_URL and FLAX_API_TOKEN and register it with Claude Code or a .mcp.json
  • Hosted MCP — Connect to Flax's hosted HTTP MCP endpoint at POST /mcp, authenticated with OAuth
  • MCP tools reference — Every Flax MCP tool — discovery and read tools, run_query, and the write tools for building charts, sheets, and dashboards
  • Embedding overview — Embed Flax charts and dashboards in your own apps with per-resource embed tokens, a domain allowlist, and iframe or static-PNG modes
  • Iframe embeds — Embed live Flax charts and dashboards in an iframe, framed only on allowlisted domains and scoped under row-level security
  • Static PNG embeds — Render a Flax chart or dashboard to a static PNG via GET /api/embed/image for surfaces that block iframes
  • GitHub App — The Flax GitHub App integration for dbt project ingest and semantic write-back — installation and permissions
  • Webhooks — The inbound webhooks Flax receives — GitHub events for the write-back/git flow and Stripe events for billing

API reference

  • API reference overview — The Flax programmatic REST API — base URL, authentication, content types, versioning, and the machine-readable OpenAPI spec.
  • Errors & limits — The standard error envelope, HTTP status codes, error categories, and rate-limiting behavior of the Flax API.
  • Queries API — Compile and run semantic-model queries, batch several at once, and inspect the compiled SQL — all under /api/query.
  • Sheets API — List, create, and fetch spreadsheet workbooks under /api/sheets.
  • Charts API — List, create, fetch, and update saved visualizations under /api/charts.
  • Dashboards API — List, create, fetch dashboards and set their tile layout under /api/dashboards.
  • Connections API — List and fetch warehouse connections under /api/connections. Secrets are never returned.
  • Models API — List semantic projects and the models within them under /api/projects.
  • Datasets API — Create and manage reusable, governed datasets under /api/datasets.
  • Schedules API — List, create, and delete scheduled deliveries under /api/schedules.
  • Agents API — Create, run, and manage scheduled AI agents under /api/agents.
  • Actions API — List automations and their run history, and trigger runs, under /api/actions.
  • Orgs & admin API — Manage organization members, service accounts, and embed tokens under /api/orgs/{orgId}.
  • Sharing & identity API — Share resources with grants, list teams, and identify the token under /api/grants, /api/orgs, and /api/whoami.