Implementing Drill-Downs in Embedded Dashboards: Developer Guide for Customer-Facing Analytics

Drill-downs are one of the most requested features in customer-facing analytics. They let your users click on a data point — a bar, a pie slice, a table row — and instantly see the next level of detail. Instead of building dozens of pre-filtered views, you give users a single interactive dashboard that adapts to their questions.

For SaaS companies embedding analytics into their products, getting drill-downs right means fewer support tickets, higher engagement, and a genuinely self-service experience for your customers.

This is a developer-focused implementation guide. For a product overview of Databrain's Drill-Down 2.0 feature set, see the Drill-Down 2.0 feature announcement.

What Makes Drill-Downs Essential for Embedded Analytics

When you embed dashboards into your application, your users aren't data analysts. They're product managers, account executives, or operations leads who need answers fast. Drill-downs serve three critical needs:

Self-service exploration. Instead of your support team building custom reports, users click through data hierarchies on their own. A VP sees revenue by region, clicks "West", and immediately sees the country-level breakdown. This is the foundation of self-service analytics — giving users the tools to answer their own questions.

Progressive disclosure. Dashboards that show everything at once overwhelm users. Drill-downs let you start with a clean, high-level view and reveal detail only when users ask for it. This is particularly important for customer-facing analytics where your users have varying levels of data literacy.

Contextual analysis. When a user drills into "Q3 2025", every metric they see next is automatically filtered to that quarter. This context-preservation makes drill-downs far more useful than manually applying filters, and creates a genuinely interactive analytical experience.

‍

The Performance Model: One Query Per Click

The critical thing to understand as a developer is the performance model. Every drill click generates a new database query — there's no pre-fetched data or client-side filtering. The system adds a WHERE filter for the clicked value, changes the GROUP BY to the next dimension, and executes against the live database. (For full query mechanics, see the drill-down docs.)

This means:

1. Latency is additive. A 3-level drill path means 3 sequential queries over the course of a user session. If your average query takes 800ms, the third drill click still takes 800ms — it doesn't compound, but it also doesn't benefit from any prior query.
2. Data is always live. Users see real-time results at every level, not stale cache. This is the right default for customer-facing analytics where freshness matters.
3. Index strategy matters. Drill queries accumulate WHERE clauses. By level 3, you have WHERE region = 'West' AND country = 'USA' AND city = 'Portland'. Composite indexes on your drill columns make a significant difference at deeper levels.

Why Declarative Drill Configuration Matters for Embedded Products

Traditional drill-down implementations are hardcoded: the hierarchy is fixed and every level renders the same chart type. If a product manager wants to change the drill path or try a different visualization at level 2, that's a code change and a deployment.

Databrain takes a different approach. The entire drill configuration — hierarchy order, chart type, dimensions, measures, and filters at each level — is stored as a declarative configV2 object on the metric itself. This separation of configuration from code has three practical consequences for engineering teams:

1. No deployment cycles for drill changes. Your product manager reconfigures a drill path in the Databrain UI. The next time a user loads the embedded dashboard, they see the updated hierarchy. Your engineering team isn't involved.
2. Different customers can get different drill paths. Since configuration lives on the metric, you can create metric variants per customer segment — one with a geographic hierarchy for regional accounts, another with a product hierarchy for e-commerce accounts.
3. Testing drill paths doesn't require staging environments. Because configuration is UI-driven and scoped to individual metrics, PMs can experiment in a development workspace without touching production code.

‍

Example: E-Commerce Revenue Drill Path

Level What the user sees Chart Type Why this chart type

‍

Example: SaaS Customer Success Dashboard

For a B2B SaaS product, your customer success team might need a different drill path:

Level What the user sees Chart Type Why this chart type

‍

Cross-Dashboard Drill-Down: An Architectural Decision, Not Just a Toggle

Regular drill-down affects one metric. Cross-dashboard drill-down extends that click to filter every metric on the dashboard simultaneously — clicking "West" on a revenue chart also filters customer count, order volume, and support tickets to "West."

For embedded products, enabling this is an architectural decision, not just a UI toggle. Here's why:

It uses the RLS pipeline. The drill filter is injected as an additional row-level security condition. This means it stacks on top of your tenant isolation — a user can never see data outside their scope by drilling, even with cross-dashboard enabled. But it also means every metric on the dashboard gets re-queried when someone drills. On a dashboard with 12 metrics, one click triggers 12 queries. Factor this into your database capacity planning.

It requires a shared column vocabulary. The filter passes the exact column name from the drilled metric (e.g., region) to all other metrics. If a support-tickets metric calls it support_region, the filter won't match. This constraint should inform your data modeling: if you plan to use cross-dashboard drill, standardize column names across all datasets that feed the same dashboard.

It changes the UX contract. With regular drill-down, a user explores one chart in isolation. With cross-dashboard, a single click changes everything on screen. This is powerful for context-aware dashboards where every metric is related. It's disorienting on dashboards that mix unrelated KPIs. Choose based on how cohesive your dashboard's data story is.

‍

Implementation Walkthrough: React + Backend

Here's a complete implementation pattern for embedding drill-down dashboards in a React application with server-side token generation.

Backend: Token Generation (Node.js / Express)

Your backend generates a guest token scoped to the current user's tenant. Drill-down queries will respect this scope automatically.

‍

// server/routes/analytics.js
import express from 'express';

const router = express.Router();

router.post('/guest-token', async (req, res) => {
const { userId, tenantId } = req.auth; // from your auth middleware

try {
const response = await fetch(
'https://api.usedatabrain.com/api/v2/guest-token/create',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.DATABRAIN_API_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
clientId: tenantId,
dataAppName: process.env.DATABRAIN_DATA_APP_NAME,
expiryTime: 3600000, // 1 hour
}),
}
);

const data = await response.json();
res.json({ token: data.token });
} catch (error) {
res.status(500).json({ error: 'Token generation failed' });
}
});

export default router;

‍

Frontend: React Component with Token Refresh

// components/AnalyticsDashboard.jsx
import { useEffect, useState, useCallback } from 'react';
import '@databrainhq/plugin/web';

export default function AnalyticsDashboard({ dashboardId }) {
const [token, setToken] = useState(null);

const fetchToken = useCallback(async () => {
const res = await fetch('/api/analytics/guest-token', { method: 'POST' });
const data = await res.json();
setToken(data.token);
}, []);

useEffect(() => {
fetchToken();
// Refresh before expiry (50 min for 1hr token)
const interval = setInterval(fetchToken, 50 * 60 * 1000);
return () => clearInterval(interval);
}, [fetchToken]);

if (!token) return 
Loading analytics...
;

const theme = {
drillBreadCrumbs: {
fontFamily: 'Inter, sans-serif',
fontColor: '#374151',
activeColor: '#2563eb',
},
};

return (



);
}

‍

Designing Drill-Friendly Data Models

Your drill-down experience is only as good as your underlying data. A few data modeling practices make drill-downs work well:

Include hierarchy columns in your datasets. If you want a Region > Country > City drill path, all three columns need to be available in the same dataset or joined view. Drill-down generates queries against the metric's source data, so missing columns mean broken drill levels.

Use consistent naming across metrics. Cross-dashboard drill-down applies the drilled column name as a filter to all other metrics. If one metric calls it region and another calls it sales_region, the cross-dashboard filter won't match. Use the same column names (or aliases) across metrics that share a dashboard.

Pre-aggregate carefully. If your source data is already aggregated (e.g., a summary table with only region-level totals), you can't drill into country or city. Ensure your source data has the granularity needed for the deepest drill level.

Consider table drill-down volume. The deepest drill level (especially tables) removes GROUP BY and returns individual rows. On a table with millions of rows, this can produce large result sets. Use level-specific filters or ensure the drill path narrows the data sufficiently before reaching the table level.

‍

Best Practices for Drill-Down Design

Limit depth to 3-4 levels. Each drill level triggers a new database query. Beyond 4 levels, the experience becomes slow and users lose track of where they are.

Choose meaningful hierarchies. The dimension order should reflect how your users think about the data. Geographic hierarchies (Region > Country > City) and temporal hierarchies (Year > Quarter > Month) are universally understood.

Use cross-dashboard drill sparingly. It's powerful but can be confusing if the dashboard has many unrelated metrics. Best used when all metrics on the dashboard share common dimensions.

Design for the return trip. Users need a clear way to drill back up. Breadcrumb navigation should be visible and intuitive. Style the breadcrumbs to match your app using the drillBreadCrumbs theme option.

Consider table drill-down carefully. Table drill-down removes the GROUP BY clause and returns individual rows. On high-cardinality datasets, this can produce thousands of rows. Use table views only at the deepest drill levels, or apply level-specific filters to limit results.

Enable caching for repeat drill paths. Users often drill down, go back, and drill into a different value. Enable query caching in Workspace Settings to avoid re-executing the same queries when users navigate back through their drill history.

‍

Production Pitfalls: What Goes Wrong After Launch

Setup issues are covered in the drill-down docs. These are the problems that surface after you've shipped to real users:

Drill latency spikes at deeper levels. At level 0 your query might touch a summary table; by level 3 you're running filtered queries against raw transactional data. If your database doesn't have indexes on the columns used in drill hierarchies, response times balloon. Add composite indexes on (region, country, city) or whatever your drill path uses — the WHERE clauses accumulate, and without indexes each level compounds the slowdown. Enable query caching in Databrain's Workspace Settings to eliminate repeat queries when users navigate back.

Cross-dashboard drill silently breaks mixed-schema dashboards. This is the most common post-launch complaint. When a user drills on "region" in a revenue chart, the filter region = 'West' gets applied to every metric on the dashboard — including ones sourced from tables that don't have a region column. The result is empty charts or SQL errors for those metrics. The fix is architectural: if you're using cross-dashboard drill, every metric on that dashboard should share a common column vocabulary. If that's not possible, split the dashboard into focused views and use regular (single-metric) drill-down instead.

Table drill-down overwhelms the frontend with large payloads. Table visualization at the deepest drill level removes GROUP BY and returns individual rows. On a 50M-row table, even after 3 levels of filtering you might still get 10,000+ rows in a single response. This isn't just slow — it can freeze the browser tab. Mitigation: use level-specific filters to cap results, or avoid table as the final drill level for high-cardinality datasets. An aggregated chart with export-to-CSV is often a better UX for the deepest level.

Users abandon after 2 levels. Usage analytics typically show steep drop-off beyond level 2. This isn't a bug — it means your hierarchy has too many levels or the intermediate levels aren't answering meaningful questions. Design each level to answer a progressively more specific question ("where?", then "when?", then "what?"). If users aren't reaching level 3, remove it or restructure.

‍

How This Compares to Other Approaches

Different analytics platforms take different approaches to drilling, and the right choice depends on your users:

Metabase offers "drill-through" — a contextual menu that lets users filter, see individual records, auto-generate reports, and break out by different dimensions. It's more exploratory but less structured than predefined hierarchies. Best for internal analytics teams who want maximum flexibility.

Looker uses a drill_fields parameter in LookML, giving developers code-level control over what appears when users click table cells. It's powerful for developers but requires LookML expertise and is tightly coupled to Looker's modeling layer.

Apache Superset / Preset introduced "Drill By" — a right-click contextual menu that lets users select any dimension to drill by, without predefined hierarchies. Very flexible but less guided — users need to know which dimensions are meaningful.

Databrain takes a middle path: predefined hierarchies for a guided experience, but with the flexibility to configure chart types, dimensions, and filters at each level. The cross-dashboard filtering adds a unique capability for multi-metric dashboards. This approach is particularly well-suited for customer-facing analytics where your users need a guided path rather than open-ended exploration.

Capability Metabase Looker Superset Databrain

‍

Getting Started

If you're building with Databrain, the implementation path is straightforward:

1. Create your metrics with the dimensions you want in the hierarchy.
2. Enable drill-down in Settings > Actions for each metric.
3. Configure drill levels — set the dimension order and optionally customize chart types per level.
4. Enable cross-dashboard drill if you want clicks to filter the entire dashboard.
5. Embed the dashboard using the <dbn-dashboard> web component with the code patterns above.

For detailed setup instructions, see our Drill Down guide and Developer Docs for embedded drill-down.

Ready to add drill-downs to your product? Start building with Databrain or explore the Embed Playground to see drill-downs in action.