The 30 most frequently used APIs in Lightdash Common, organized by category with concise signatures.
Get all fields (dimensions + metrics) from an explore.
function getFields(explore: Explore): CompiledField[];Usage:
const fields = getFields(explore);Get only dimensions from an explore.
function getDimensions(explore: Explore): CompiledDimension[];Usage:
const dimensions = getDimensions(explore);Get only metrics from an explore.
function getMetrics(explore: Explore): CompiledMetric[];Usage:
const metrics = getMetrics(explore);Create a field ID → field mapping for O(1) lookups.
function getFieldMap(
explore: Explore,
additionalMetrics?: AdditionalMetric[]
): Record<string, Field>;Usage:
const fieldMap = getFieldMap(explore);
const field = fieldMap["orders_customer_id"]; // O(1) lookupCreate an item ID → item mapping including fields, table calculations, and custom dimensions.
function getItemMap(
explore: Explore,
additionalMetrics?: AdditionalMetric[],
tableCalculations?: TableCalculation[],
customDimensions?: CustomDimension[]
): ItemsMap;Usage:
const itemsMap = getItemMap(explore, query.additionalMetrics, query.tableCalculations);
const item = itemsMap["orders_total_revenue"];Find a specific field by its ID in an explore.
function findFieldByIdInExplore(
explore: Explore,
fieldId: string
): Field | undefined;Usage:
const field = findFieldByIdInExplore(explore, "orders_customer_id");Format a value based on its field/item definition.
function formatItemValue(
item: Field | TableCalculation | CustomDimension | undefined,
value: unknown,
convertToUTC?: boolean,
parameters?: Record<string, unknown>
): string;Usage:
const formatted = formatItemValue(field, rawValue, true); // Convert to UTC
const withParams = formatItemValue(field, rawValue, false, { threshold: 100 });Format a date value according to a time interval.
function formatDate(
date: MomentInput,
timeInterval?: TimeFrames,
convertToUTC?: boolean
): string;Usage:
const formatted = formatDate(new Date(), TimeFrames.DAY, true);Format a timestamp value with time component.
function formatTimestamp(
value: MomentInput,
timeInterval?: TimeFrames,
convertToUTC?: boolean
): string;Usage:
const formatted = formatTimestamp(value, TimeFrames.MILLISECOND, false);Format a number with custom formatting options.
function formatNumberValue(value: number, format?: CustomFormat): string;Usage:
const formatted = formatNumberValue(1234.56, {
type: CustomFormatType.CURRENCY,
currency: "USD",
round: 2,
});Format multiple result rows based on items map.
function formatRows(
rows: Record<string, unknown>[],
itemsMap: ItemsMap,
pivotValuesColumns?: string[],
parameters?: Record<string, string>
): ResultRow[];Usage:
const formattedRows = formatRows(rawRows, itemsMap);Main class for compiling dbt models into Lightdash explores.
class ExploreCompiler {
constructor(warehouseSqlBuilder: WarehouseSqlBuilder);
compileExplore(uncompiledExplore: UncompiledExplore): Explore;
}Usage:
const compiler = new ExploreCompiler(warehouseSqlBuilder);
const explore = compiler.compileExplore(uncompiledExplore);Create a user ability object for permission checks.
function defineUserAbility(
user: LightdashUser | SessionUser,
projectProfiles: ProjectMemberProfile[],
customRoleScopes?: Record<string, Scope[]>
): MemberAbility;Usage:
const ability = defineUserAbility(user, projectProfiles);
if (ability.can("view", "Dashboard")) {
// User can view dashboards
}Check if a field is a dimension.
function isDimension(field: Field): field is Dimension;Usage:
if (isDimension(field)) {
console.log("Dimension type:", field.type);
}Check if a field is a metric.
function isMetric(field: Field): field is Metric;Usage:
if (isMetric(field)) {
console.log("Metric type:", field.type);
}Check if an item is a table calculation.
function isTableCalculation(value: any): value is TableCalculation;Usage:
if (isTableCalculation(item)) {
console.log("Table calculation:", item.displayName);
}Check if an item is a custom dimension.
function isCustomDimension(value: any): value is CustomDimension;Usage:
if (isCustomDimension(item)) {
console.log("Custom dimension type:", item.type);
}Check if a value is a filter group (vs filter rule).
function isFilterGroup(value: FilterGroup | FilterRule): value is FilterGroup;Usage:
if (isFilterGroup(filterItem)) {
// Process nested filters
} else {
// Process single filter rule
}Check if an explore compilation failed.
function isExploreError(explore: Explore | ExploreError): explore is ExploreError;Usage:
if (isExploreError(explore)) {
console.error("Compilation errors:", explore.errors);
}Validate an email address.
function validateEmail(email: string): boolean;Usage:
if (validateEmail(userInput)) {
// Valid email
}Validate a password against Lightdash requirements.
function validatePassword(password: string): boolean;Usage:
if (validatePassword(password)) {
// Valid password (min 8 chars)
}Check if two arrays have any common elements.
function hasIntersection<T>(arr1: T[], arr2: T[]): boolean;Usage:
if (hasIntersection(userRoles, requiredRoles)) {
// User has at least one required role
}Get the ID of an item (field, table calculation, or custom dimension).
function getItemId(item: Item): string;Usage:
const itemId = getItemId(field); // Returns "table_fieldname"Get the display label of an item.
function getItemLabel(item: Item): string;Usage:
const label = getItemLabel(field); // Returns field.label or field.nameConvert a snake_case or camelCase name to a friendly display name.
function friendlyName(text: string): string;Usage:
const friendly = friendlyName("customer_id"); // Returns "Customer id"Get all item IDs referenced in a metric query.
function itemsInMetricQuery(metricQuery: MetricQuery): string[];Usage:
const itemIds = itemsInMetricQuery(query);
// Returns: ["orders_status", "orders_count", "calc_percent", ...]Flatten filter groups into an array of filter rules.
function getFilterRules(filters: Filters): FilterRule[];Usage:
const allRules = getFilterRules(query.filters);
allRules.forEach(rule => {
console.log(`Filter on ${rule.target.fieldId}`);
});For comprehensive API documentation, see:
For task-oriented guides, see: