Superset Tags vs Folders

The baseline user interface of Apache Superset is designed around a flat, table-centric index built to manage a small number of assets. While this layout is adequate for small deployments, it degrades significantly when an organization scales to fifty or more dashboards, and becomes unusable at hundreds of assets. In large enterprise environments, the lack of structured hierarchy forces users to navigate via endless scrolling or rely on search queries.

To bypass this limitation, organizations have spent years using custom naming conventions and database workarounds. Although the open-source community attempted to resolve dashboard categorization by introducing a metadata tagging system, the implementation has been hindered by database schema bugs, export-import issues, and UX hurdles.

The Drafted fork, documented at /superset/dashboards-list-page, addresses this gap by rebuilding the dashboard list experience around curated folder hierarchies, multi-brand scoping, and precise lifecycle governance. The broader Superset hub covers packages, related features, and how we ship the fork in production.

The Scale Pathology: Why Flat Lists Fail at Fifty Dashboards

When an Apache Superset deployment grows beyond fifty dashboards, the default flat list model turns into a major discovery bottleneck. Because the native interface lists all accessible dashboards in a single, unnested table, user navigation shifts from logical browsing to targeted search. This shift introduces several technical and organizational challenges.

The primary issue is the transition from discovery to search. Users cannot find related dashboards unless they already know the exact titles or metadata terms. For business users and non-technical stakeholders, this "pull" model is inefficient.

Furthermore, the lack of a visual folder map leads analytical teams to inadvertently create duplicate dashboards for slightly modified use cases. This behavior produces orphaned assets, outdated reports, and a general decline in data trust across the organization.

This flat-list design is also inconsistent with other parts of the platform. While the core project introduced the DATASET_FOLDERS feature flag to group metrics and columns in the chart builder, the top-level dashboard interface was left in a flat state. This mismatch forces users to organize upstream datasets hierarchically while navigating downstream dashboards in an unstructured list.

Chronology of an Unresolved Community Request (2017–2026)

The demand for a structured folder or project hierarchy in Apache Superset is one of the most persistent, unresolved requests in the project's history.

This timeline highlights a clear divide between community needs and the project's development direction. As early as December 2017, GitHub issue #3821 introduced the debate between tags and folders. While some contributors advocated for nested directories to mirror other BI platforms like Metabase, the initial consensus favored a tagging model. This choice was driven by the database flexibility of many-to-many relationships.

By January 2022, issue #18005 and discussion #18546 introduced proposals for a "Project" or "Namespace" container within Superset, drawing comparisons to Kibana spaces or Metabase collections. Contributors argued that folders provide a structured path of discovery, allowing users to browse team-specific directories without prior knowledge of existing tags. Despite strong community support, core maintainers prioritized the development of a tagging system, arguing that folders were too restrictive and represented a matter of opinion.

When the tagging system was officially merged under the TAGGING_SYSTEM feature flag in early 2024, core maintainers closed outstanding folder requests, such as issue #19398. They asserted that the new tagging feature sufficiently addressed asset categorization.

However, the demand for physical folders remained high. In December 2025, discussion #36810 highlighted that flat lists with tags remained difficult to navigate at scale, arguing that folders are necessary for clean permission boundaries and scalability. This was followed by discussion #37940 in February 2026, confirming that enterprise users still rely on title-prefix hacks to organize assets.

Dataset Folders in Superset 6.x Not the Same as Dashboard Folders

Superset 6.x shipped a folder editor for datasets behind the DATASET_FOLDERS feature flag. The February 2026 community update added drag-and-drop folder management in the dataset list a meaningful improvement for chart builders browsing metrics and columns in a hierarchy instead of a flat table.

It does not resolve the dashboard organization problem this article addresses. The dashboard and chart list views remain flat tables. Discussions like #37940 show teams still asking for dashboard folders specifically; many operators enable DATASET_FOLDERS, see folders in one part of the UI, and assume the problem is solved everywhere.

This split makes the tags-versus-folders debate harder to read. Maintainers can point to "folders exist now" while dashboard consumers still scroll through hundreds of assets or rely on prefix hacks. Until dashboard hierarchy ships upstream, the gap our fork targets curated folder trees with RBAC on the dashboards list remains open.

Why the Maintainers Bet on Tags: An Architectural Analysis

The core disagreement between the open-source maintainers and enterprise administrators stems from a fundamental difference in discovery models: pull-based exploration (tags) versus push-based navigation (folders).

The Usability Limits of Tagging Systems

Tags rely on a "pull" discovery model. To locate a dashboard, a user must search for a specific tag, such as Finance or Q4_Revenue. This assumes the user knows the tag exists and that publishers applied it consistently.

In practice, tagging systems suffer from low adoption and naming fragmentation, such as concurrent tags for:

finance
finances
financial

Tags also fail to reduce initial clutter. When a user opens the dashboard list, they are still presented with a massive list of assets.

The Polymorphic Foreign Key Bug

Beyond usability challenges, the official TAGGING_SYSTEM feature flag has introduced significant technical and database issues for production deployments.

A major issue in Superset's tagging architecture is the database design of the tagged_object table. The table uses an object_id column intended to dynamically reference multiple entity types, including dashboards, charts, and saved queries. However, the database schema was incorrectly implemented with multiple simultaneous foreign key constraints pointing to:

• dashboards.id
• slices.id
• saved_query.id

Standard relational databases, such as PostgreSQL, cannot enforce polymorphic foreign keys in this manner. As a result, when the TAGGING_SYSTEM flag is enabled, for example in version 4.1.3, creating a new dashboard fails with a foreign key constraint violation. The database expects the dashboard's ID to exist in the slices table, blocking dashboard creation entirely. To resolve this, administrators must manually execute database migrations to drop these invalid constraints.

Database Error: ForeignKeyViolation
 
INSERT INTO tagged_object (object_id, object_type, tag_id)...
   ├── Constraint expects object_id to exist in slices.id
   │   due to incorrect FK definition
   └── Transaction aborts because object_id actually references dashboards.id

Export and Import Limitations

A key requirement for enterprise BI is the promotion of assets across environments, such as deploying dashboards from Development to Production staging. For years, the tagging system did not support export or import operations.

While proposals were introduced to export custom tags via a separate tags.yaml file in the export ZIP, managing metadata across environments remains a manual, error-prone process.

Curated Hierarchies: The Drafted Architecture

To resolve these enterprise discovery issues, the Drafted fork implements curated folder hierarchies, multi-brand scoping, and advanced lifecycle states.

This solution is documented at /superset/dashboards-list-page, which details how Drafted replaces the flat-list paradigm with a scalable architecture.

├── MODE SWITCHER: (Scopes entire view)
└── CURATED FOLDER TREE
     ├── Folder: Marketing (4)
     ├── Folder: Finance (12)
     └── Folder: Operations (2)

The Drafted architecture is built around three core components.

1. Curated Folder Tree Sidebar

Instead of displaying a flat list, the Drafted UI features a persistent left-hand sidebar containing a custom-configured folder map. Each folder displays the exact number of dashboards nested within it, providing immediate visibility into asset volume.

Folders are arranged in a stable, predictable order configured by administrators, preventing navigation paths from shifting unpredictably. Upon landing, users see the top-level directories rather than a cluttered list of hundreds of dashboards, facilitating a structured search process.

2. Multi-Brand Scoping: The Mode Switcher

For large organizations operating multiple products, brands, or regional divisions, global folders can still become cluttered. Drafted addresses this with a top-level MODE switcher.

Selecting a brand, such as BRAND-1 or BRAND-2, scopes the entire interface, including the folder tree, active filters, and the asset list, to that business unit. Analysts only see the assets and folders relevant to their designated brand, eliminating noise from unrelated areas of the business.

3. Rich Card Grid Interface

Opening a folder in the sidebar transforms the right-hand panel into a card-based grid tailored for metadata discovery. Each card serves as an informative metadata record containing:

• Contextual breadcrumbs: A clear path displayed at the top of the folder grid keeps users oriented within the organizational structure.
• Direct descriptions: The dashboard's description is displayed directly on the card, allowing users to understand the asset's purpose without opening it.
• Status chips: Dashboards feature clear lifecycle tags, indicating whether they are in Published, Draft, Maintenance, or Deprecated states.
• Responsible owner badge: The card displays a single, accountable maintainer next to the status chip. This clarifies ownership, showing users who to contact if a dashboard or its underlying data breaks.
• On-hover actions: Users can edit properties, view descriptions, and favorite assets directly from the folder grid.

Security Boundaries and Role-Based Folder Governance

Organizing dashboards into folders is closely tied to access control and data governance. In large organizations, restricting access is essential for maintaining data security.

The Limits of Stock Superset Permissions

In standard Apache Superset, dashboard access is managed in one of two ways.

Dataset-Based Access

Access is tied to database permissions. If a user has access to a dataset, they can view all published dashboards built on that data.

Dashboard-Level Role-Based Access Control (DASHBOARD_RBAC)

When the DASHBOARD_RBAC feature flag is enabled, administrators can assign specific roles to individual dashboards. This restricts visibility to users with matching roles.

While DASHBOARD_RBAC provides granular control, managing permissions individually for hundreds of dashboards is highly inefficient. Furthermore, custom roles often encounter permission issues. If a custom role lacks explicit dataset or database access permissions, API calls return empty datasets.

This frequently leads administrators to grant broad access overrides, such as the all_database_access permission. While this resolves empty API responses, it bypasses granular security and grants unrestricted write privileges across all databases.

Folder-Level Permissions in Drafted

The Drafted fork addresses these challenges by aligning folder hierarchies with the organization's team-and-role model.

• Inherited security policies: Permissions can be applied at the folder level, allowing dashboards to automatically inherit the security policies of their parent directory.
• Clean RBAC mapping: This eliminates the need to manually configure permissions for individual dashboards or grant broad database access overrides.
• Role-based workspaces: Marketing analysts only see the /Marketing folder and its associated dashboards, while financial data remains restricted to authorized users within the /Finance folder.

Architectural Comparison Matrix

Strategic Deployment Framework

For BI architects managing large-scale Apache Superset deployments, choosing between flat tables, tagging systems, and curated folders is critical for long-term usability and governance.

Is deployment scale > 50 dashboards?
                    ├── No  ──> Use Stock Superset Flat Table
                    └── Yes ──> Are there multiple teams or brands?
                                     ├── No  ──> Use Folders (Single Scope)
                                     └── Yes ──> Use Drafted Fork (Multi-Brand + Folders)

Based on this analysis, organizations should implement the following strategy.

Retire Title Prefix Hacks

Organizations should transition away from simulated folders, such as prefixing titles with brackets or colons. These workarounds increase maintenance overhead and do not provide clean permission boundaries.

Assess the Risks of the Native Tagging System

If enabling the native TAGGING_SYSTEM flag, database administrators must inspect the database schema to verify that invalid polymorphic foreign key constraints on the tagged_object table have been dropped.

Adopt Curated Hierarchies for Multi-Department Environments

When managing a single BI instance for multiple departments or brands, deploying a folder-based architecture like the Drafted fork is highly recommended. This introduces clean business scoping, reduces noise, and enforces data trust across the enterprise.

Related on this site

• Our Apache Superset fork — packages, pricing, and the full feature map
• Dashboards list page feature — the folder UX this post describes
• Superset Growth package — where dashboard UX improvements typically land
• How we work

Also on X

A shorter, sharper take in article form: x.com/RtKazakov.