What Metabase customization involves
Customization in this section means changing how Metabase models data, defines questions and metrics, and presents results on top of the data sources you have already connected. It does not mean installing Metabase, connecting databases or setting up permissions, which are covered elsewhere on this page. The work sits in the content layer: models, metrics, saved questions with custom SQL or native queries, dashboard layout, branding, custom maps and scripted configuration that moves between environments.
Teams usually start customizing for a small set of reasons. Analysts repeat the same joins and filters in every question. Two dashboards report revenue or active customers with different definitions. Leadership asks for logos, colors and wording that match other internal tools. Regional teams need geographic maps with their own boundaries. Engineers want the same collections, models and settings applied to a staging and a production instance without clicking through each one by hand. Each trigger points to a specific object: a model for shared joins, a metric for agreed definitions, a branding setting, a custom map, or the REST API and serialization for repeatable setup.
Many organizations build this in-house, because the people who understand the business definitions are usually inside the company. A partner is worth considering for a design review of the model and metric layer before many questions depend on it, or for a defined build with written deliverables. Before any design starts, confirm which features your paid plan covers. Some capabilities in this area, including SSO-related options and parts of permissions and auditing, depend on Pro or Enterprise, so a design that assumes them on Open Source or Starter will need rework.
What the work includes
Each package ends in a named deliverable that your team can review, version and hand over. Scope them in writing before build starts, and confirm which features your Metabase edition supports.
Models and governed datasets
We design models that define the joins, column names, descriptions and visibility that analysts query. The deliverable is a documented model catalog with owners, refresh expectations and the source tables behind each model. Check that sensitive columns are hidden at the model layer and that owners can name what each model is for.
Metric dictionary and definitions
Metrics encode a business calculation once, so dashboards and questions agree on it. The deliverable is a metric dictionary listing the aggregation, filters, time dimension, owner and approval status for each metric. Have finance or the metric owner sign off each definition against an agreed source before publishing.
Native SQL questions with parameters
Native questions cover logic that the query builder cannot express, and parameters let users filter them safely. The deliverable is a tested set of native questions with documented parameters and expected outputs. Run them under a read-only database role, review how each parameter is bound, and test against known results.
Branding and instance presentation
Branding covers the instance name, logo, colors, landing content and any email or login text your organization wants to standardize. The deliverable is a documented set of presentation settings and a checklist for changes. Confirm which branding options your plan exposes, since some presentation controls depend on the edition.
Custom maps and regional boundaries
Custom maps let questions plot data against your own regions, such as sales territories or service areas. The deliverable is a set of validated GeoJSON files with the map configuration and a note on each region key. Check that region keys match the values in your data, and confirm how the map is served inside your network.
REST API scripts and configuration export
API scripts handle repeatable tasks such as provisioning users and collections or pulling scheduled report data. The deliverable is a runbook for API use with tested scripts, token handling rules and version pinning. Confirm whether your edition supports serialized configuration export, and if it does, keep exports in version control with a review step.
What drives cost and duration
Each row names one factor that moves customization effort on a self-hosted Metabase, why it matters, and how to keep it manageable.
| Driver | Why it moves effort | How to keep it down |
|---|---|---|
| Number and complexity of source databases | Each connected database adds sync schedules, field type mapping, credentials and models that must be tested separately. Joins across heterogeneous sources need more validation than single-warehouse setups. | Start with the warehouse that serves most questions. Confirm which source systems must be connected at launch and defer the rest to a later phase. |
| Models and metrics that must agree across teams | Shared models and metrics need ownership, naming rules and reconciliation against finance or operational reports. Disagreement between teams usually costs more time than the build itself. | Agree a short list of certified metrics with named owners before building. Limit the first release to the metrics that appear in executive or regulatory reporting. |
| Volume of native SQL to maintain | Native questions and custom SQL run outside the semantic layer, so every schema change can break them. Each one needs a named owner, a test case and a review when the source changes. | Move repeated logic into models. Keep native SQL for cases the visual query builder cannot express, and record the owner and source tables for each query. |
| Branding and custom map requirements | Themes, logos and custom map files are small in isolation but must be re-checked after each upgrade and copied to every environment. Map regions also need data that matches the geography used in your questions. | Limit branding to the settings the application exposes and keep assets in version control. Ask the team to confirm the map file format and source before design starts. |
| Number of environments that need the same configuration | Collections, permissions, models, settings and custom assets must match across development, test and production. Manual copies drift quickly, and every drift becomes a support question. | Export configuration through serialization or the REST API where your edition supports it, and script the promotion steps. Confirm which settings serialize in your version. |
| Edition and permissions-dependent designs | Row-level and column-level permissions, SSO and auditing are Pro or Enterprise features according to Metabase's pricing page. A design that depends on them cannot be built on Open Source or Starter, and retrofitting a plan change adds licensing and testing work. | Decide the edition before designing permissions. Ask Metabase to confirm current plan inclusions, and list which requirements the chosen edition cannot meet. |
| Upgrade cadence that tests each customization | Every upgrade re-tests models, native SQL, themes, API scripts and permission rules. Custom work that was not documented or automated is re-verified by hand. Metabase 64 is an LTS release with end of life on 1 December 2027, per Metabase's version support page. | Keep a regression checklist for each customization. Automate API checks where possible, and plan upgrade windows around the LTS and non-LTS support dates on Metabase's version support page. |
Project phases and outputs
The sequence moves from understanding your existing Metabase content to a tested, documented customization that your team can maintain after handover.
Discover the data model and existing questions
DeployOpen reviews the connected databases, current saved questions, dashboards, collections and any existing models, with your analysts and data owners. The output is an inventory of the content in scope, the tables and fields it depends on, and the gaps the customization must close. The step is complete when the inventory has been reviewed and signed off by your team.
Confirm editions and features against current pricing
Before design starts, DeployOpen checks each requested feature against the current Metabase pricing page and documentation, including which capabilities need Pro or Enterprise. The output is a feature matrix listing each requirement, the edition that supports it, and the source checked on the date of review. Your procurement or licensing owner confirms the matrix before any build work begins.
Design models and metric definitions with owners
Working with named business owners, DeployOpen defines the models, metrics, filters and naming conventions that the questions and dashboards will rely on. Each metric gets a written definition, a source table, and an accountable owner. The output is a design document that your owners approve, and the step closes when every metric in scope has a signed definition.
Build native questions, branding, maps and API scripts
DeployOpen builds the native questions and SQL queries, applies branding settings, configures custom maps where needed, and writes any REST API scripts agreed in scope. Changes are tracked in version control where practical, and the output is the set of built artifacts with a build log that maps each item to its design entry. The step is complete when each artifact matches its approved design.
Test in a non-production instance
All customizations are deployed to a non-production Metabase instance connected to test data, then checked against the agreed definitions, permissions and rendering on the target browsers. The output is a test record listing each case, the expected result, the actual result and the owner who accepted it. Production deployment waits until your team accepts the test record.
Hand over with a maintenance plan
DeployOpen transfers the customized content and scripts to your team, with documentation of models, metrics, serialization or export steps, and the process for upgrades and changes. The handover includes a maintenance plan that names owners for each customized item and the review cadence. The step is complete when your team has run a walkthrough and accepted the documentation and plan in writing.
What stays in-house and what goes to a partner
This table compares each part of Metabase customization by the skills it needs and who typically owns it after handover, so you can split the work between your team and a partner.
| Work area | Skills it needs | Who typically owns it after handover |
|---|---|---|
| Metric definitions and business logic | Business domain knowledge, SQL and data modeling, agreement on definitions with finance or operations leads | In-house. Business owners approve each metric and keep definitions current as the business changes. |
| Data modeling and SQL tuning | SQL, data modeling, query plan reading, knowledge of your source databases and their indexes | Shared. A partner often builds models and tunes slow native questions, and your data team maintains them. |
| API scripting and configuration export | REST API and JSON, scripting in a language your team already runs, serialization and version control practice | Often outsourced at first when no one in-house has the skill, then moved in-house once scripts are documented and stored in Git. |
| Branding and custom map work | Front-end skills, design assets and brand guidelines, familiarity with the Metabase theme and map configuration | Depends on design resources. Partners usually build the first version, and in-house design or front-end staff own later changes. |
| Source build changes (if required) | Clojure or Java familiarity and a working knowledge of the Metabase build, plus a plan to rebuild on each upgrade | Avoid where possible. If a source build is needed, the team that maintains it owns the rebuild and upgrade work. |
| Plan and permissions validation | Understanding of collections, data permissions and the features each Metabase plan includes, plus test accounts for each group | Shared. Your security or BI lead signs off the results, and a partner can run the test matrix before go-live. |
| Upgrade regression checks for customizations | REST API and JSON, test scripts, knowledge of which customizations depend on which Metabase features | Shared at first. Your team should own the checklist, and a partner can run it during each planned upgrade. |
| Documentation and handover | Technical writing, knowledge of the custom SQL, scripts and branding assets delivered | In-house after handover. Ask the partner for a written record of every customization and where it is stored. |
What usually goes wrong
Most Metabase customization problems come from a small set of decisions made early and not revisited. The cards below name each failure point and the check that prevents it.
Metric definitions that diverge
A metric defined in a model may be recalculated differently in a native question or a dashboard filter, so two reports show different numbers for the same measure. Before go-live, list each governed metric, record where it is defined, and compare results from a model-based question and a native SQL question on the same test data.
Native SQL that breaks on schema change
Native questions reference tables and columns directly, so a renamed column or dropped table fails silently in some dashboards and loudly in others. Assign an owner to each native question, keep SQL in version control where possible, and rerun the collection's questions against a test database after every schema change.
Features missing from the chosen edition
Some customizations depend on capabilities that exist only in paid plans, such as SSO, row and column level permissions, or auditing. Confirm each required feature against the current pricing and plan documentation before design starts, because building on Open Source and then needing Pro or Enterprise changes the architecture.
Scripts with hard-coded IDs
API scripts that reference question, dashboard, collection or database IDs work in one instance and fail in another, because IDs differ between environments. Look up objects by name or a stored mapping at run time, and store environment-specific values in configuration rather than in the script body.
Configuration drift between environments
Settings changed by hand in production, such as permissions, branding, or embedding options, gradually diverge from development and staging. Export configuration through serialization or the API on a schedule, compare exports between environments, and require changes to go through the same review path as code.
Customizations not retested after upgrades
A custom query, script, or embedding setup may behave differently after a Metabase version change, and an upgrade does not confirm that your customizations still work. Check the release notes and version support status before planning an upgrade, keep a test instance on the target version, and run a fixed set of customization checks there before touching production.
How the work changes by starting point
A new Metabase with no saved content is mostly a design exercise. The work centers on defining the collection structure, the permission groups, and the first set of models and metrics before anyone builds dashboards.
- Design collections and permission groups before anyone saves a question, so ownership is clear from the start.
- Build a small set of governed models and metrics that the first dashboards depend on.
- Decide the application database early. Metabase ships with an embedded H2 database for demos and recommends PostgreSQL for production, so confirm that choice against the current installation docs.
- Confirm which identity method your plan supports (see the people and groups docs for your version) before you add users.
- Agree on a naming convention and a starter dashboard set that the first users will copy.
An instance that has grown through individual saved questions needs consolidation before new customization begins. The work is an inventory, a triage of duplicates and stale content, and a rebuild of the most-used questions as governed models and metrics.
- Inventory saved questions by usage and owner, then retire or archive those with no recent viewers.
- Group near-duplicate questions and replace them with one model or metric that the owners agree on.
- Move shared logic into models so dashboards stop repeating the same SQL or joins.
- Review collection permissions after each move, because content that was private may now sit in a shared location.
- Confirm in the docs for your version how archiving, moving, and bulk changes behave, and whether any of them need the API.
A team arriving from another BI tool often expects its metric definitions to carry over unchanged. In practice, the work is a translation exercise, and the scope depends on how much of the logic lives in the old tool rather than in the warehouse.
- Catalog each metric and record where its definition lives: the warehouse, the old tool's semantic layer, or individual reports.
- Recreate shared definitions as Metabase metrics and models, then check them against figures the business already trusts.
- Plan for differences in filter behavior, time zones, and null handling, and test them with the same source data.
- Map the old tool's row-level security to Metabase permissions. Confirm which row and column controls your plan includes, since the pricing page limits them to the Pro and Enterprise plans.
- Migration of reports and dashboards is a separate piece of work, so agree on scope before estimating.
When Metabase runs in development, test, and production, the main risk is configuration drift. The work shifts toward repeatable configuration, so that questions, models, collections, and settings can be promoted without manual rebuilding in each environment.
- Decide what is versioned and promoted. Content such as models and metrics usually needs a different process than infrastructure settings.
- Confirm in the serialization documentation for your version what it exports, what it imports, and which plan it requires.
- Keep environment-specific values, such as database connections and credentials, outside the promoted content.
- Script API calls where a change must repeat across environments. Confirm the API endpoints and authentication method for your version first.
- Test the upgrade path in a non-production environment before any production change, using the upgrade docs for your version.
In an air-gapped or tightly restricted network, customization is limited by what the instance can reach. Features that call outside services, such as external map tiles or API access from other systems, need explicit approval and often a different design.
- List every outbound dependency the customization uses, including map tile sources, plugins, and any external font or script loads.
- Plan for internal alternatives where external map tiles are unavailable. Confirm which map tile sources the docs for your version allow you to configure.
- Agree who may use the REST API, from which hosts, and with which credentials, and document the approval.
- Plan how content and configuration move in and out of the network under your change process, since the instance cannot fetch them directly.
- Confirm the application database and update path for your environment, because upgrades and documentation access may both need an internal copy.
What you need to provide
Start by naming an owner for every metric and dataset you plan to customize. A metric in Metabase is shared logic that many questions and dashboards depend on, so one accountable person must approve its wording, its source tables and its change requests. Give the implementation team read access to each source database along with a schema document that describes tables, keys and fields in plain language. Without that document, models and native SQL questions must be reverse engineered, and the build waits on owners who may be busy elsewhere.
Provide a current inventory of saved questions and dashboards, with usage, collection placement and a list of items to retire. This sets the scope of the rebuild and prevents duplicate models. Confirm the Metabase version and edition in writing before design starts. Long-term support releases are supported for 14 months, so the version you choose sets your upgrade calendar. SSO and row and column permissions depend on the edition, which changes the permissions design. Also supply a non-production instance connected to copies of the source databases so changes can be reviewed before users see them.
Supply branding assets such as logo files, color values and any licensed fonts, plus written approval rules that name who signs off on look-and-feel changes and on new models or metrics before they go live. For custom maps, decide which map data you will use, such as region boundaries or GeoJSON files, and who owns its license terms. The source determines whether you can host the file and show it to external viewers. Confirm these licensing decisions with your legal team before the design assumes public data can be embedded or redistributed.
Define an API service account policy before any build calls the Metabase REST API. State which account types are allowed, who approves them, where credentials are stored, how they are rotated and which permission group each account belongs to. Automated provisioning, scripted dashboard updates and serialization tests cannot be validated until these approvals exist. If any decision in this list is missing at kickoff, the affected work moves later in the plan, and the schedule is re-baselined in writing before the team continues.
Frequently asked questions
What does a Metabase customization project cost, and what drives the price?
The price follows from the written scope, and DeployOpen does not publish a price list. The main drivers are the number of models, metrics and native questions to build, how many data sources and permission rules are involved, whether custom branding or custom maps are included, and whether the work includes REST API integration or serialization. Licensing is a separate line item. Metabase's pricing page lists Starter at $100 per month or $90 per month billed yearly with 5 users included, and Pro at $575 per month or $517.50 per month billed yearly with 10 users included. Ask the quote to separate the one-time build fee from any recurring support fee.
How long does a Metabase customization take to complete?
Duration depends on scope, not on a fixed period. Timing is driven by how many models, metrics and custom SQL questions must be designed and reviewed, how many people must approve them, how many data sources need access, and whether any feature depends on a plan your organization has not yet bought. Engagements are fixed-scope, so the timeline is agreed in writing before work starts. Ask for the milestones, what your team must review at each one, and what happens if a dependency such as a database account or identity provider is delayed.
Can our internal team customize Metabase without an implementation partner?
Yes, a team with SQL skills, a Metabase administrator and a named owner for data definitions can handle much of this in-house. The harder areas are permission design, safe use of custom SQL against production databases, embedding and branding changes that touch the application, and keeping customizations working through upgrades. Check whether you can run a staging instance, document metric definitions and carry out a major upgrade with a verified backup and a rollback plan. A partner is most useful where those skills are missing or where a deadline depends on them.
What do we need to provide before a Metabase customization project starts?
Expect to provide named business owners for each metric and dataset, read-only database accounts for each source, a staging environment that mirrors production, and access to the existing Metabase instance and its application database. You also need an agreed list of users, groups and collections, and a decision on how people sign in, such as Google sign-in, LDAP, or an SSO method that requires Pro or Enterprise. Confirm the access model, the reviewers and the approver for go-live in the written scope.
Do Metabase customizations survive upgrades to new versions?
Customizations kept in the application database, such as models, metrics, collections and permissions, are carried through upgrades, because Metabase runs its application database migrations automatically during an upgrade. Custom JAR changes, modified frontend code and custom embedding code must be retested against each release. Metabase LTS versions are supported for 14 months, and non-LTS versions usually reach end of life after 2 months, so plan a release-by-release path. Back up the application database before every upgrade and confirm the rollback method in advance.
Which Metabase customization features need a paid plan?
Customizations that depend on identity or governance need Pro or Enterprise. According to Metabase's pricing page, SSO, row and column level permissions, multi-tenant data segregation and usage analytics and auditing are included only in Pro and Enterprise. Advanced LDAP group and attribute sync, JWT, OIDC, SAML and SCIM provisioning also require Pro or Enterprise, while Google sign-in and LDAP work on Open Source and Starter. All SSO-based embedding requires Pro or Enterprise, and guest embedding authentication works on every plan. The pricing page lists Enterprise by quote starting at $20,000 per year.
How DeployOpen delivers Metabase customization
DeployOpen scopes Metabase customization in writing before any build starts, then builds and tests each change inside infrastructure you control. Engagements are fixed-scope, and ongoing support is available as a retainer.
How we scope
- Inventory the models, metrics, native questions and branding changes the written scope covers, and name each one.
- Confirm which customizations work on your current edition, since SSO, row and column permissions and auditing need Pro or Enterprise.
- Agree the data sources, database credentials and REST API or serialization use in writing before work starts.
How we build
- Build models and metrics against a staging copy of the application database and the connected data sources.
- Test custom SQL and native questions for correct results, permissions and performance before they reach collections.
- Apply branding, custom map and API changes through version-controlled configuration where the chosen Metabase version supports it.
How we hand over
- Deliver a document that lists each model, metric, question, setting and API integration, with its owner and purpose.
- Walk your administrators through how to add, change and retire models and metrics without breaking saved questions.
- Provide serialization exports or configuration records so your team can review changes and restore a known state.
How we support
- Offer ongoing support, upgrades and testing of custom content as a retainer, scoped separately from the build.
- Retest models, metrics and API integrations against each Metabase upgrade before they move to production.
- Confirm with your team which support window, response expectations and change process apply to your environment.
