or run

npx @tessl/cli init

Types and Interfaces

Core TypeScript definitions for the Lightdash platform.

Core Data Types

Explore

An Explore represents a data model with its tables, joins, dimensions, and metrics.

interface Explore {
  name: string;
  label: string;
  tags: string[];
  baseTable: string;
  joinedTables: CompiledExploreJoin[];
  tables: Record<string, CompiledTable>;
  unfilteredTables?: Record<string, CompiledTable>;
  targetDatabase: SupportedDbtAdapter;
  ymlPath?: string;
  sqlPath?: string;
  groupLabel?: string;
  warehouse?: string;
  spotlight?: { visibility: string; categories?: string[]; };
  aiHint?: string | string[];
  databricksCompute?: string;
  type?: ExploreType;
}

enum ExploreType {
  DEFAULT = 'default',
  VIRTUAL = 'virtual',
}

enum JoinRelationship {
  ONE_TO_ONE = 'one-to-one',
  ONE_TO_MANY = 'one-to-many',
  MANY_TO_ONE = 'many-to-one',
  MANY_TO_MANY = 'many-to-many',
}

interface CompiledTable {
  name: string;
  label: string;
  database: string;
  schema: string;
  sqlTable: string;
  description?: string;
  dimensions: Record<string, CompiledDimension>;
  metrics: Record<string, CompiledMetric>;
  requiredFilters?: ModelRequiredFilterRule[];
  requiredAttributes?: RequiredAttributes;
  groupLabel?: string;
  sqlWhere?: string;
  uncompiledSqlWhere?: string;
  parameterReferences?: string[];
  parameters?: Record<string, unknown>;
  sets?: Record<string, Set>;
  orderFieldsBy?: OrderFieldsByStrategy;
  hidden?: boolean;
}

interface CompiledExploreJoin {
  table: string;
  sqlOn: string;
  compiledSqlOn: string;
  relationship: JoinRelationship;
  type?: 'left' | 'right' | 'inner' | 'full';
  always?: boolean;
  hidden?: boolean;
  tablesReferences?: string[];
  parameterReferences?: string[];
}

interface ExploreError {
  name: string;
  label?: string;
  tags?: string[];
  groupLabel?: string;
  baseTable?: string;
  joinedTables?: ExploreJoin[];
  errors: InlineError[];
}

interface InlineError {
  type: InlineErrorType;
  message: string;
  coordinates?: Coordinates;
}

enum InlineErrorType {
  METADATA_PARSE_ERROR = 'METADATA_PARSE_ERROR',
  NO_DIMENSIONS_FOUND = 'NO_DIMENSIONS_FOUND',
}

function isExploreError(explore: Explore | ExploreError): explore is ExploreError;

Field

Fields represent dimensions and metrics that can be queried.

enum FieldType {
  DIMENSION = 'dimension',
  METRIC = 'metric',
}

enum DimensionType {
  STRING = 'string',
  NUMBER = 'number',
  TIMESTAMP = 'timestamp',
  DATE = 'date',
  BOOLEAN = 'boolean',
}

enum MetricType {
  PERCENTILE = 'percentile',
  MEDIAN = 'median',
  AVERAGE = 'average',
  COUNT = 'count',
  COUNT_DISTINCT = 'count_distinct',
  SUM = 'sum',
  MIN = 'min',
  MAX = 'max',
  NUMBER = 'number',
  STRING = 'string',
  DATE = 'date',
  TIMESTAMP = 'timestamp',
  BOOLEAN = 'boolean',
  PERCENT_OF_PREVIOUS = 'percent_of_previous',
  PERCENT_OF_TOTAL = 'percent_of_total',
  RUNNING_TOTAL = 'running_total',
}

interface Field {
  fieldType: FieldType;
  type: DimensionType | MetricType;
  name: string;
  label: string;
  table: string;
  tableLabel: string;
  sql: string;
  description?: string;
  source?: Source;
  hidden: boolean;
  compact?: Compact;
  round?: number;
  format?: Format;
  groupLabel?: string;
  index?: number;
  tags?: string[];
  required?: boolean;
  requiredAttributes?: RequiredAttributes;
}

interface Dimension extends Field {
  fieldType: FieldType.DIMENSION;
  type: DimensionType;
  timeInterval?: TimeFrames | string;
  group?: string;
  urls?: FieldUrl[];
  customFormat?: CustomFormat;
  defaultColor?: string;
  colors?: Record<string, string>;
}

interface CompiledDimension extends Dimension {
  compiledSql: string;
  tablesReferences: string[];
  tablesRequiredAttributes?: Record<string, RequiredAttributes>;
}

interface Metric extends Field {
  fieldType: FieldType.METRIC;
  type: MetricType;
  isAutoGenerated: boolean;
  group?: string;
  urls?: FieldUrl[];
  percentile?: number;
  formatOptions?: CustomFormat;
  filters?: MetricFilterRule[];
}

interface CompiledMetric extends Metric {
  compiledSql: string;
  tablesReferences: string[];
  tablesRequiredAttributes?: Record<string, RequiredAttributes>;
}

type CompiledField = CompiledDimension | CompiledMetric;

interface FilterableDimension extends Dimension {
  type: DimensionType.STRING | DimensionType.NUMBER | DimensionType.TIMESTAMP | DimensionType.DATE | DimensionType.BOOLEAN;
}

type FilterableField = FilterableDimension | Metric;

interface Source {
  path: string;
  range: Range;
  content?: string;
  highlight?: {
    start: number;
    end: number;
  };
}

interface FieldUrl {
  url: string;
  label: string;
}

type FieldId = string;
type FieldRef = { table: string; field: string };

// Type guards
function isField(value: any): value is Field;
function isDimension(field: Field): field is Dimension;
function isMetric(field: Field): field is Metric;
function isFilterableDimension(field: Field): field is FilterableDimension;
function isFilterableField(field: Field): field is FilterableField;
function isCompiledMetric(field: Field): field is CompiledMetric;

// Utilities
function convertFieldRefToFieldId(fieldRef: FieldRef): FieldId;
function getFieldRef(fieldId: FieldId): FieldRef;
function getFieldLabel(field: Field): string;
function defaultSql(columnName: string): string;
function friendlyName(text: string): string;

Custom Dimensions

Runtime-defined dimensions (bins, custom SQL).

enum CustomDimensionType { BIN = 'bin', SQL = 'sql' }
enum BinType { FIXED_NUMBER = 'fixed_number', FIXED_WIDTH = 'fixed_width', CUSTOM_RANGE = 'custom_range' }

type BinRange = {
  from: number | undefined;  // undefined for first range (unbounded start)
  to: number | undefined;    // undefined for last range (unbounded end)
}

interface CustomBinDimension {
  id: string;
  name: string;
  type: CustomDimensionType.BIN;
  table: string;
  dimensionId: FieldId;
  binType: BinType;
  binNumber?: number;
  binWidth?: number;
  customRange?: CustomBinRange[];
}

interface CustomSqlDimension {
  id: string;
  name: string;
  type: CustomDimensionType.SQL;
  table: string;
  sql: string;
  dimensionType: DimensionType;
}

type CustomDimension = CustomBinDimension | CustomSqlDimension;

function isCustomBinDimension(value: any): value is CustomBinDimension;
function isCustomSqlDimension(value: any): value is CustomSqlDimension;

Table Calculations

Post-query calculations.

enum TableCalculationType { NUMBER = 'number', STRING = 'string', DATE = 'date', TIMESTAMP = 'timestamp', BOOLEAN = 'boolean' }

interface TableCalculation {
  name: string;
  displayName: string;
  sql?: string;
  calculationType?: TableCalculationType;
  windowFunction?: WindowFunction;
  template?: TableCalculationTemplate;
  order?: number;
  format?: CustomFormat;
}

interface WindowFunction {
  type: WindowFunctionType;  // 'row_number' | 'rank' | 'sum' | 'avg' | 'count' | 'min' | 'max'
  field?: string;
  orderBy?: { field: string; ascending: boolean };
  frame?: FrameClause;
}

function isTableCalculation(value: any): value is TableCalculation;

Custom Formatting

Value display formatting.

enum CustomFormatType {
  DEFAULT = 'default', PERCENT = 'percent', CURRENCY = 'currency',
  NUMBER = 'number', ID = 'id', DATE = 'date', TIMESTAMP = 'timestamp',
  CUSTOM = 'custom'
}

enum NumberSeparator {
  DEFAULT = 'default', COMMA_PERIOD = 'commaPeriod', SPACE_PERIOD = 'spacePeriod',
  PERIOD_COMMA = 'periodComma', SPACE_COMMA = 'spaceComma', NO_SEPARATOR_PERIOD = 'noSeparatorPeriod'
}

enum Compact {
  THOUSANDS = 'thousands', MILLIONS = 'millions', BILLIONS = 'billions',
  KILOBYTES = 'kilobytes', MEGABYTES = 'megabytes', GIGABYTES = 'gigabytes'
}

interface CustomFormat {
  type: CustomFormatType;
  round?: number;
  separator?: NumberSeparator;
  currency?: string;
  compact?: Compact;
  prefix?: string;
  suffix?: string;
  timeInterval?: TimeFrames;
  custom?: string;
}

function isSummable(item: Field | TableCalculation | CustomDimension): boolean;
function findCompactConfig(compact: Compact | undefined): CompactConfig | undefined;

Items Map

Combined view of all queryable items.

type ItemsMap = Record<string, CompiledField | TableCalculation | AdditionalMetric | CustomDimension>;
type Item = ItemsMap[string];
type FilterableItem = CompiledField | AdditionalMetric | CustomDimension;

function isFilterableItem(item: Item | undefined): item is FilterableItem;

Dashboard Types

interface Dashboard {
  organizationUuid: string;
  projectUuid: string;
  uuid: string;
  name: string;
  description?: string;
  tiles: DashboardTile[];
  filters: DashboardFilters;
  tabs?: DashboardTab[];
  spaceUuid: string;
  slug: string;
}

enum DashboardTileTypes {
  SAVED_CHART = 'saved_chart',
  MARKDOWN = 'markdown',
  LOOM = 'loom',
  SQL_CHART = 'sql_chart'
}

type DashboardTile = DashboardChartTile | DashboardMarkdownTile | DashboardLoomTile | DashboardSqlChartTile;

interface DashboardChartTile {
  uuid: string;
  type: DashboardTileTypes.SAVED_CHART;
  x: number; y: number; h: number; w: number;
  properties: {
    savedChartUuid: string | null;
    title?: string;
    hideTitle?: boolean;
  };
}

function isDashboardChartTileType(tile: DashboardTile): tile is DashboardChartTile;
function hasChartsInDashboard(dashboard: Dashboard): boolean;

Chart Types

enum ChartKind {
  LINE = 'line', HORIZONTAL_BAR = 'horizontal_bar', VERTICAL_BAR = 'vertical_bar',
  SCATTER = 'scatter', AREA = 'area', MIXED = 'mixed',
  PIE = 'pie', TABLE = 'table', BIG_NUMBER = 'big_number',
  FUNNEL = 'funnel', TREEMAP = 'treemap', GAUGE = 'gauge', MAP = 'map'
}

enum ChartType {
  CARTESIAN = 'cartesian', BIG_NUMBER = 'big_number', TABLE = 'table',
  PIE = 'pie', FUNNEL = 'funnel', TREEMAP = 'treemap', GAUGE = 'gauge', MAP = 'map'
}

interface SavedChart {
  uuid: string;
  projectUuid: string;
  name: string;
  tableName: string;
  metricQuery: MetricQuery;
  chartConfig: ChartConfig;
  tableConfig: TableChart;
  pivotConfig?: PivotConfig;
  spaceUuid: string;
  slug: string;
}

type ChartConfig = CartesianChartConfig | PieChartConfig | BigNumberConfig | TableChartConfig | FunnelChartConfig;

function isCartesianChartConfig(config: ChartConfig): config is CartesianChartConfig;
function isPieChartConfig(config: ChartConfig): config is PieChartConfig;
function getChartType(savedChart: SavedChart): ChartType;

Project and Warehouse Types

enum ProjectType { DEFAULT = 'DEFAULT', PREVIEW = 'PREVIEW' }
enum WarehouseTypes {
  BIGQUERY = 'bigquery', POSTGRES = 'postgres', REDSHIFT = 'redshift',
  SNOWFLAKE = 'snowflake', DATABRICKS = 'databricks', TRINO = 'trino', CLICKHOUSE = 'clickhouse'
}

interface Project {
  organizationUuid: string;
  projectUuid: string;
  name: string;
  type: ProjectType;
  dbtConnection: DbtProjectConfig;
  warehouseConnection?: CreateWarehouseCredentials;
}

type WarehouseCredentials = BigQueryCredentials | PostgresCredentials | RedshiftCredentials | SnowflakeCredentials | DatabricksCredentials | TrinoCredentials | ClickHouseCredentials;

function mergeWarehouseCredentials(target: WarehouseCredentials, update: Partial<CreateWarehouseCredentials>): CreateWarehouseCredentials;

User and Authorization Types

interface LightdashUser {
  userUuid: string;
  firstName: string;
  lastName: string;
  email: string;
  organizationUuid?: string;
  isActive: boolean;
  role?: OrganizationMemberRole;
}

interface SessionUser extends LightdashUser {
  userId: number;
  ability: MemberAbility;
  isSetupComplete: boolean;
  isEmailVerified: boolean;
}

interface Space {
  organizationUuid: string;
  uuid: string;
  name: string;
  isPrivate: boolean;
  dashboards: SpaceDashboard[];
  access: SpaceShare[];
  projectUuid: string;
  slug: string;
}

enum SpaceMemberRole { VIEWER = 'viewer', EDITOR = 'editor', ADMIN = 'admin' }

function isUserWithOrg(user: LightdashUser): user is LightdashUserWithOrg;

Filter Types

enum FilterType { STRING = 'string', NUMBER = 'number', DATE = 'date', BOOLEAN = 'boolean' }

enum FilterOperator {
  NULL = 'isNull', NOT_NULL = 'notNull',
  EQUALS = 'equals', NOT_EQUALS = 'notEquals',
  STARTS_WITH = 'startsWith', ENDS_WITH = 'endsWith',
  INCLUDE = 'include', NOT_INCLUDE = 'doesNotInclude',
  LESS_THAN = 'lessThan', GREATER_THAN = 'greaterThan',
  IN_THE_PAST = 'inThePast', IN_THE_NEXT = 'inTheNext', IN_THE_CURRENT = 'inTheCurrent'
}

enum UnitOfTime { days = 'days', weeks = 'weeks', months = 'months', quarters = 'quarters', years = 'years' }

interface FilterRule<O = FilterOperator, T = FieldTarget> {
  id: string;
  target: T;
  operator: O;
  values?: any[];
  settings?: any;
  disabled?: boolean;
  required?: boolean;
}

type FieldTarget = { fieldId: string };

type FilterGroup = OrFilterGroup | AndFilterGroup;
type AndFilterGroup = { id: string; and: (FilterGroup | FilterRule)[] };
type OrFilterGroup = { id: string; or: (FilterGroup | FilterRule)[] };

interface Filters {
  dimensions?: FilterGroup;
  metrics?: FilterGroup;
  tableCalculations?: FilterGroup;
}

interface DashboardFilters {
  dimensions: DashboardFilterRule[];
  metrics: DashboardFilterRule[];
  tableCalculations: DashboardFilterRule[];
}

function isFilterGroup(value: FilterGroup | FilterRule): value is FilterGroup;
function isFilterRule(value: FilterGroup | FilterRule): value is FilterRule;

Metric Query Types

interface MetricQuery {
  exploreName: string;
  dimensions: string[];
  metrics: string[];
  filters: Filters;
  sorts: SortField[];
  limit: number;
  tableCalculations: TableCalculation[];
  additionalMetrics?: AdditionalMetric[];
  customDimensions?: CustomDimension[];
  timezone?: string;
}

interface SortField {
  fieldId: string;
  descending: boolean;
  nullsFirst?: boolean;
}

interface AdditionalMetric {
  name?: string;
  label?: string;
  type: MetricType;
  sql?: string;
  table: string;
  baseDimensionName?: string;
  percentile?: number;
  formatOptions?: CustomFormat;
  filters?: MetricFilterRule[];
}

interface MetricQueryResponse {
  rows: Record<string, unknown>[];
  metricQuery: MetricQuery;
  fields: Record<string, Field | TableCalculation | AdditionalMetric | CustomDimension>;
}

function isAdditionalMetric(value: any): value is AdditionalMetric;
function hasFormatOptions(metric: Metric | AdditionalMetric): boolean;

Warehouse Client Interface

interface WarehouseClient {
  credentials: WarehouseCredentials;
  test(): Promise<void>;
  getCatalog(config: Pick<WarehouseCatalog, 'database' | 'schema' | 'table'>): Promise<WarehouseCatalog>;
  streamQuery(sql: string, streamCallback: (data: WarehouseResults) => void, options?: any): Promise<void>;
  runQuery(sql: string, tags?: RunQueryTags, options?: any): Promise<WarehouseResults>;
}

interface WarehouseResults {
  fields: Record<string, { type: DimensionType }>;
  rows: Record<string, unknown>[];
}

Error Classes

All extend LightdashError with statusCode and data properties.

class LightdashError extends Error {
  statusCode: number;
  data: LightdashErrorData;
}

// 400 errors
class ParameterError extends LightdashError {}  // Default: "Incorrect parameters"
class ParseError extends LightdashError {}  // Default: "Error parsing dbt project and lightdash metadata"
class CompileError extends LightdashError {}  // Default: "Error compiling sql from Lightdash configuration"
class FieldReferenceError extends LightdashError {}  // Default: "Failed to reference field in dbt project"
class WarehouseConnectionError extends LightdashError {}

// 401/403 errors
class ForbiddenError extends LightdashError {}  // Default: "You don't have access to this resource or action"
class AuthorizationError extends LightdashError {}  // Default: "You don't have authorization to perform this action"
class DeactivatedAccountError extends LightdashError {}  // Default: "Your account has been deactivated..."

// 404 errors
class NotExistsError extends LightdashError {}
class NotFoundError extends LightdashError {}

// 500 errors
class UnexpectedServerError extends LightdashError {}  // Default: "Something went wrong."
class UnexpectedDatabaseError extends LightdashError {}  // Default: "Unexpected error in Lightdash database."

function getErrorMessage(e: unknown): string;

Scheduler Types

enum SchedulerFormat { CSV = 'csv', IMAGE = 'image', GSHEETS = 'gsheets' }
enum SchedulerJobStatus { SCHEDULED = 'scheduled', STARTED = 'started', COMPLETED = 'completed', ERROR = 'error' }

interface SchedulerBase {
  schedulerUuid: string;
  name: string;
  format: SchedulerFormat;
  cron: string;
  timezone: string;
  enabled: boolean;
  savedChartUuid: string | null;
  dashboardUuid: string | null;
  targets: SchedulerTarget[];
  filters?: DashboardFilters;
}

type Scheduler = ChartScheduler | DashboardScheduler;

function isDashboardScheduler(scheduler: Scheduler): scheduler is DashboardScheduler;

Catalog Types

enum CatalogType { Field = 'field', Table = 'table' }
enum CatalogFilter { Dimensions = 'dimensions', Metrics = 'metrics', Tables = 'tables' }

interface CatalogItem {
  catalogType: CatalogType;
  name: string;
  label: string;
  projectUuid: string;
  tableName: string;
  tableLabel: string;
  fieldType?: FieldType;
  type?: DimensionType | MetricType;
  chartUsage?: number;
}

Authentication Types

enum AuthTokenPrefix { SCIM = 'scim_', SERVICE_ACCOUNT = 'sva_', PAT = 'pat_', OAUTH = 'oauth_' }

type Authentication = PersonalAccessTokenAuth | ServiceAccountAuth | JwtAuth | OauthAuth;

interface EmbedContent { type: 'dashboard' | 'chart'; uuid: string; }

See individual topic documentation for detailed API information.

Version

Tile

Files

types.mddocs/

Types and Interfaces

Core Data Types

Explore

Field

Custom Dimensions

Table Calculations

Custom Formatting

Items Map

Dashboard Types

Chart Types

Project and Warehouse Types

User and Authorization Types

Filter Types

Metric Query Types

Warehouse Client Interface

Error Classes

Scheduler Types

Catalog Types

Authentication Types

Version

Tile

Files

types.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Types and Interfaces

Core Data Types

Explore

Field

Custom Dimensions

Table Calculations

Custom Formatting

Items Map

Dashboard Types

Chart Types

Project and Warehouse Types

User and Authorization Types

Filter Types

Metric Query Types

Warehouse Client Interface

Error Classes

Scheduler Types

Catalog Types

Authentication Types

types.mddocs/