or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

guides

authorization.md building-queries.md compilation.md visualization.md working-with-data.md

quick-reference

common-apis.md imports.md types-at-a-glance.md

reference

architecture.md getting-started-full.md

index.md

tile.json

Common Import Patterns

This guide shows the most common import patterns for @lightdash/common. For complete API signatures, see the API documentation.

Pattern 1: Query Building

import {
  type MetricQuery,
  type Explore,
  FilterOperator,
  UnitOfTime,
  getFields,
  getDimensions,
  getMetrics,
} from "@lightdash/common";

Use for: Building and executing queries against explores.

Pattern 2: Dashboard & Charts

import {
  type Dashboard,
  type SavedChart,
  ChartKind,
  type ChartConfig,
  type DashboardTile,
} from "@lightdash/common";

Use for: Creating and managing dashboards and chart configurations.

Pattern 3: Data Formatting

import {
  formatItemValue,
  formatDate,
  formatTimestamp,
  formatNumberValue,
  type CustomFormat,
} from "@lightdash/common";

Use for: Formatting query results for display.

Pattern 4: Authorization

import {
  defineUserAbility,
  type LightdashUser,
  type ProjectMemberProfile,
  type MemberAbility,
} from "@lightdash/common";

Use for: Checking user permissions and access control.

Pattern 5: Compilation

import { ExploreCompiler, type UncompiledExplore, type Explore } from "@lightdash/common";

Use for: Compiling dbt models into Lightdash explores.

Pattern 6: Warehouse Integration

import {
  type WarehouseClient,
  WarehouseTypes,
  type WarehouseCredentials,
  type Project,
} from "@lightdash/common";

Use for: Connecting to and querying data warehouses.

Pattern 7: Visualization

import {
  CartesianChartDataModel,
  PieChartDataModel,
  ChartKind,
  type VizCartesianChartOptions,
} from "@lightdash/common";

Use for: Creating chart visualizations with ECharts.

Pattern 8: Filtering

import {
  type Filters,
  type FilterGroup,
  type FilterRule,
  FilterOperator,
  isFilterGroup,
} from "@lightdash/common";

Use for: Building and managing query filters.

Pattern 9: Field Operations

import {
  getItemMap,
  getFieldMap,
  findFieldByIdInExplore,
  getItemId,
  type ItemsMap,
} from "@lightdash/common";

Use for: Working with explore fields and items.

Pattern 10: Validation & Type Guards

import { validateEmail, validatePassword, isDimension, isMetric, isField } from "@lightdash/common";

Use for: Validating data and narrowing TypeScript types.

Core Imports

All essential types and utilities in one place:

import {
  // Data Modeling
  type Explore,
  type MetricQuery,
  type Field,
  type Dimension,
  type Metric,
  type CompiledField,
  type CompiledDimension,
  type CompiledMetric,
  type Table,
  type CompiledTable,

  // Filtering
  type Filters,
  type FilterGroup,
  type FilterRule,
  FilterOperator,

  // Dashboards & Charts
  type Dashboard,
  type SavedChart,
  type ChartConfig,
  ChartKind,

  // Warehouses
  type WarehouseClient,
  type WarehouseCredentials,
  WarehouseTypes,

  // Projects
  type Project,
  type Space,
  ProjectType,

  // Compiler
  ExploreCompiler,

  // Utilities
  getFields,
  getDimensions,
  getMetrics,
  getVisibleFields,
  findFieldByIdInExplore,
  getFieldMap,
  getItemMap,
  formatItemValue,
  formatDate,
  formatTimestamp,
  formatNumberValue,
  validateEmail,
  validatePassword,
  defineUserAbility,
  CartesianChartDataModel,
  PieChartDataModel,
  TableDataModel,
} from "@lightdash/common";

CommonJS Imports

For CommonJS environments (Node.js with require):

// Note: TypeScript type imports are not available in CommonJS
// Use JSDoc comments for type hints if needed

const {
  // Compiler
  ExploreCompiler,

  // Utilities
  getFields,
  getDimensions,
  getMetrics,
  formatItemValue,
  validateEmail,
  defineUserAbility,

  // Data Models
  CartesianChartDataModel,
  PieChartDataModel,
  TableDataModel,

  // Enums
  FilterOperator,
  WarehouseTypes,
  ChartKind,

  // JSON Schemas
  chartAsCodeSchema,
  dashboardAsCodeSchema,

  // Constants
  JWT_HEADER_NAME,
} = require("@lightdash/common");

Note: Type definitions are only available when using TypeScript or ESM imports. In CommonJS, types must be specified through JSDoc comments or TypeScript declaration files.