How to embed the metrics catalog

​

Overview

​

When to use metrics catalog embedding

• Give customers a self-serve “what can I measure?” view of your semantic layer inside your product.
• Surface a metric browser next to your own charts so users can discover related metrics.
• Let embedded users start a new exploration from any metric without exposing your full Lightdash workspace.

​

Available features

• Browsing all metrics in the project the JWT is scoped to
• Searching and filtering by category
• Previewing a metric with its default time-series chart
• Continuing into an embedded Explore from any metric when content.canExplore is true
• Saving Explore results into a fixed destination space via write actions
• Row- and column-level filtering via user attributes

​

Prerequisites

• An embed secret for the project. See Embedding quickstart.
• At least one metric defined in the project’s semantic layer. See How to create metrics.
• A React or Next.js host application — metrics catalog embedding is only available through the React SDK.
• If you want embedded users to save charts from Explore, a destination space and a write actor. See Write actions.

​

Embed the metrics catalog with the React SDK

import Lightdash from '@lightdash/sdk';

function MyMetricsCatalog() {
  return (
    <Lightdash.MetricsCatalog
      instanceUrl="https://app.lightdash.cloud"
      token={generateMetricsCatalogToken()} // Server-side function
    />
  );
}

​

Generate a metrics catalog embed token

import jwt from 'jsonwebtoken';

const token = jwt.sign({
  content: {
    type: 'metricsCatalog',
    projectUuid: 'your-project-uuid',
    canExplore: true,
  },
  writeActions: {
    serviceAccountUserUuid: 'service-account-user-uuid',
    spaceUuid: 'destination-space-uuid',
  },
  userAttributes: {
    tenant_id: 'tenant-abc', // Row-level filtering for the embedded viewer
  },
  user: {
    email: 'customer@example.com',
  },
}, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });

• content.type — must be "metricsCatalog".
• content.projectUuid — pins the embed to a specific project. The catalog only lists metrics from this project.

• content.canExplore — when true, embedded users can click Explore from here on any metric to open the embedded Explore view. Omit or set to false to keep the embed read-only.
• writeActions — needed only when canExplore is true and you want embedded users to save charts they build from Explore. See Write actions.
• userAttributes — applies row- and column-level filters to catalog previews and Explore queries, identical to other embed types.
• user.email / user.externalId — surfaced in audit and analytics for the embedded viewer.

​

Controlling access

• The catalog only shows metrics from the project named in content.projectUuid.
• User attributes applied to the JWT hide metrics and dimensions whose required_attributes rules the embedded viewer does not satisfy, both in the catalog listing and in any Explore session launched from it.
• Metric previews and Explore queries run with the write actor’s permissions (when writeActions is set) plus any userAttributes filters, so embedded viewers only see rows and columns they are entitled to.
• When canExplore is not set to true, the catalog is read-only — the Explore from here action is hidden and Explore routes reject the token.
• Metrics catalog tokens are rejected by dashboard, chart, AI agent, and data app routes, and vice versa.

​

Example: read-only metrics catalog

const token = jwt.sign({
  content: {
    type: 'metricsCatalog',
    projectUuid: 'your-project-uuid',
  },
  userAttributes: {
    tenant_id: 'tenant-abc',
  },
}, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });

​

Next steps