Holistics best practices

Holistics works best when your team treats it as a governed analytics product, not just a place to build charts. This guide brings the most important habits into one page, with links to the detailed docs when you need setup steps or feature-specific examples.

Use this as a review checklist when you start a new Holistics project, clean up an existing workspace, or prepare a dashboard and dataset for broader rollout.

At a glance

The table below is the shortest version of this guide. Start with the area that is causing friction for your team, then follow the linked docs for the details.

Area	Best practice	Read more
Semantic layer	Keep business logic in reusable models, relationships, fields, and metrics instead of recreating it in each report.	Design models, Naming conventions
Project structure	Organize AML files so analysts can find the right model, dataset, or dashboard without tribal knowledge.	Organize AML project, Project structure
Datasets	Design datasets around user questions, with a balance between focused self-service and flexible exploration.	Dataset best practices
Dashboards	Build dashboards around the decision users need to make, then choose layout, charts, and formatting to support that decision.	Dashboard best practices, Canvas dashboards
Performance	Reduce unnecessary work before tuning the warehouse: fewer widgets, smaller result sets, pre-aggregates, persistence, and clear join paths.	Troubleshoot slow reports, Aggregate awareness
Permissions	Combine roles, object sharing, row-level permission, column-level permission, and database controls deliberately.	Permission system, Row-level permission
Release workflow	Use Development Mode, Git, review, validation, and controlled publishing before changes reach end users.	Development and production modes, Pull request workflow
Discovery	Use tags, endorsement, archiving, and ownership conventions so users can find trusted content.	Tagging best practices, Content endorsement
AI readiness	Give Holistics AI strong semantic context, clear descriptions, and focused AI Skills.	What AI uses for context, AI Skills

Build from a governed semantic layer

Your semantic layer should be the source of truth for business definitions. If two dashboards calculate the same metric differently, users will eventually stop trusting both.

Start by keeping reusable logic in models, fields, relationships, and metrics. Use custom metrics when the logic is genuinely reusable or too complex for the exploration interface, but avoid turning every one-off report calculation into a permanent semantic object.

Good semantic-layer hygiene usually means:

• Use clear names for model files and fields, then use business-friendly labels for what end users see.
• Add descriptions to important models, fields, datasets, and metrics so analysts and AI have enough context.
• Declare reusable relationships where the same join logic is used across datasets.
• Hide technical fields, join keys, helper dimensions, and duplicated raw fields from exploration.
• Keep business definitions close to the semantic layer instead of scattering them across dashboard-specific formulas.

Related docs:

• Tips on designing models
• Model and field naming convention
• Query models
• AQL best practices

Design datasets around user questions

Datasets are the interface most users explore from. A good dataset should make the right fields obvious, protect users from confusing combinations, and still leave enough flexibility for follow-up questions.

Avoid designing every dataset as a giant catalog of everything your warehouse contains. Smaller datasets are easier for business users to trust, while larger exploratory datasets are useful for analysts who understand the data shape and tradeoffs.

When designing datasets:

• Start from the questions a team needs to answer, not from the tables available in the warehouse.
• Build focused datasets for common self-service use cases.
• Keep broader datasets for advanced exploration, and make their naming and descriptions especially clear.
• Prefer star-schema-like paths where important dimensions and measures are close together.
• Avoid exposing large raw event or log tables directly to end-user exploration.
• Watch for fan-out risks when relationship cardinality does not match the real data.
• Use row-level and column-level permission rules on the dataset when different users should see different data.

Related docs:

• Dataset best practices
• Dataset relationships
• Row-level permission
• Column-level permission

Build dashboards around decisions

A dashboard should help someone understand what changed, why it changed, and what to do next. That is a different goal from showing every available metric on one page.

Before building, decide who the dashboard is for and what decision or workflow it supports. Then use layout, filters, chart choice, and drill paths to make that workflow easy.

Strong dashboards tend to follow these patterns:

• Put the most important metrics and trends near the top.
• Separate overview dashboards from detail dashboards instead of forcing one page to do both jobs.
• Use drill-through and cross-filtering when users need to move from summary to investigation.
• Keep filters visible and understandable, especially date filters and team or region filters.
• Use number formats that match the scale of the metric, such as 5.2M instead of 5,200,000.
• Keep chart types boring when the question is simple. A clear bar, line, table, or metric sheet is often better than a clever chart.
• Add text blocks only when they explain context, caveats, owners, or links that help users act on the dashboard.

Related docs:

• Dashboard best practices
• Interact with Canvas dashboards
• Drill-through
• Cross-filtering

Keep reports fast by design

Performance is easier to protect during design than to rescue after rollout. Slow dashboards usually come from a combination of too much data, too many widgets, complex joins, expensive warehouse queries, or large result transfers.

Start with the simplest fixes: ask for less data, reduce unnecessary widgets, and make sure users are not exploring raw tables when a modeled or aggregated table would answer the question better.

Use this order when reviewing performance:

1. Check whether the dashboard has too many widgets or returns too many rows.
2. Check whether filters should default to a narrower date range or business area.
3. Check whether the dataset join path is longer or more complex than needed.
4. Pre-aggregate large datasets where users usually ask at a higher grain.
5. Use Aggregate Awareness for smoother exploration across different grains.
6. Persist expensive Query Models when recomputing them each time is not practical.
7. Use Job Monitoring and Performance Monitoring to identify repeated slow queries.
8. Tune the warehouse only after you know which generated SQL is causing the delay.

Related docs:

• Troubleshoot slow reports
• Performance monitoring
• Job monitoring
• Aggregate awareness

Govern access intentionally

Permissions are not one setting in Holistics. They work in layers, so your setup should be explicit about what each layer is responsible for.

Use roles for feature access, workspace and object sharing for content access, data source permission for analyst access to source systems, and data-level permissions for row and column restrictions inside datasets.

As a rule of thumb:

• Give users the lowest role that supports their real workflow.
• Use the Public workspace for shared, production-ready content.
• Use Personal workspaces for drafts, experimentation, and user-owned analysis.
• Use object-level sharing to control who can see a dashboard, folder, or dataset.
• Use row-level permission when the same dataset should return different rows by user, team, region, account, or tenant.
• Use column-level permission when sensitive fields should be hidden from some users.
• Use database passthrough authentication when warehouse-level identity and policies should remain the enforcement point.
• Test permission behavior with a real user context before rolling it out broadly.

Related docs:

• Permission system
• User roles
• Row-level permission
• Database passthrough authentication

Release changes with review

Holistics projects become production systems once other people depend on them. Treat changes to models, datasets, permissions, and shared dashboards with the same care you would give application code.

At minimum, separate development from production, commit meaningful changes, and review the impact before publishing.

A healthy release workflow includes:

• Make changes in Development Mode, not directly against production.
• Use Git branches when multiple people contribute to the same project.
• Require pull requests for changes that affect shared datasets, core metrics, permissions, or executive dashboards.
• Include screenshots or result samples when a dashboard changes.
• Validate impacted reporting items before publishing modeling changes.
• Use auto-publish only after the team has a reliable review and merge process.
• Keep rollback paths clear by using Git history and file history restore.

Related docs:

• Development Mode, Production Mode and deployment
• Version control with Git
• Pull request workflow
• Reporting validation

Make trusted content easy to find

As usage grows, the problem shifts from "Can we build this?" to "Which version should I trust?" Tags, endorsement, archiving, and ownership conventions help users find the right thing without asking the data team every time.

Do not wait until the workspace is messy before defining lifecycle rules. A small, consistent system is better than a perfect taxonomy that nobody maintains.

Start with:

• Topic tags for business areas, such as topic/sales or topic/finance.
• Status tags for lifecycle, such as status/draft, status/review, or status/active.
• Owner tags for accountability, such as owner/data-team or owner/finance.
• Issue tags for temporary warnings, such as issue/stale-data or issue/under-maintenance.
• Endorsement for dashboards, datasets, and reports that are safe for broad use.
• Archiving for outdated content instead of leaving old versions searchable.
• A regular review cadence for important shared dashboards and datasets.

Related docs:

• Tagging best practices
• Tags
• Content endorsement
• Archive content

Prepare your workspace for AI

Holistics AI is only as useful as the semantic and business context it can rely on. Strong model descriptions, clear field labels, governed metrics, and focused AI Skills make AI answers more consistent.

Think of AI readiness as an extension of analytics governance. If a human analyst would need more context to answer a question correctly, AI probably needs that context too.

For better AI results:

• Add descriptions to important datasets, models, fields, and metrics.
• Keep canonical business definitions in the semantic layer.
• Use AI Skills for repeatable analysis workflows, team-specific terminology, and output conventions.
• Keep each AI Skill focused on one job.
• Include the phrases users actually say in each skill description.
• Reference existing metrics and dashboards instead of redefining logic inside the skill.
• Test AI Skills with real user questions before rolling them out.
• Keep permissions accurate, since AI respects the user's existing access.

Related docs:

• What AI uses for context
• Semantic and reporting layers
• AI Skills
• AI user access

Review your setup regularly

Best practices only work if they survive normal team growth. Schedule lightweight reviews so the workspace stays usable as datasets, dashboards, users, and AI workflows expand.

Use this cadence as a starting point:

Cadence	What to review
Before publishing	Broken reports, changed metrics, permission impact, dashboard screenshots, and performance risk.
Monthly	Slow dashboards, unused or duplicated content, stale tags, failed schedules, and recently changed critical datasets.
Quarterly	Core metric definitions, dataset design, row-level permission rules, endorsed content, AI Skills, and ownership tags.
When teams change	User roles, group membership, data access rules, dashboard owners, schedule owners, and API access.

The goal is not process for its own sake. The goal is to keep Holistics trustworthy enough that business users can answer common questions without asking the data team to verify every number.