Parameters System

/**
 * Supported parameter value types
 */
type ParameterValue = string | number | string[] | number[];

/**
 * Map of parameter names to values
 */
type ParametersValuesMap = Record<string, ParameterValue>;

/**
 * Map of parameter names to definitions
 */
type ParameterDefinitions = Record<string, LightdashProjectParameter>;

/**
 * Dashboard-specific parameter value with metadata
 */
interface DashboardParameterValue {
  /** Parameter name */
  parameterName: string;
  /** Parameter value */
  value: ParameterValue;
}

/**
 * Dashboard parameters map
 */
type DashboardParameters = Record<string, DashboardParameterValue>;

/**
 * Parameter prefixes for reference syntax
 */
enum LightdashParameters {
  /** Full prefix: ${lightdash.parameters.param_name} */
  PREFIX = 'lightdash.parameters',
  /** Short prefix: ${ld.parameters.param_name} */
  PREFIX_SHORT = 'ld.parameters',
}

/**
 * Regex pattern for SQL parameter replacement
 * Requires full ${} syntax: ${lightdash.parameters.param_name}
 */
const parameterRegex: RegExp;

-- Full syntax
SELECT * FROM orders WHERE status = '${lightdash.parameters.order_status}'

-- Short syntax
SELECT * FROM orders WHERE created_at >= '${ld.parameters.start_date}'

-- Table-level parameter (scoped to model)
SELECT * FROM orders WHERE region = '${lightdash.parameters.orders.region}'

/**
 * Extract parameter references from SQL or format strings
 * @param sql - SQL or format string to analyze
 * @param regex - Optional custom regex pattern
 * @returns Array of unique parameter names
 */
function getParameterReferences(
  sql: string,
  regex?: RegExp
): string[];

/**
 * Extract parameters from both SQL and format strings
 * @param compiledSql - Compiled SQL to extract parameters from
 * @param format - Optional format string
 * @returns Array of unique parameter names from both sources
 */
function getParameterReferencesFromSqlAndFormat(
  compiledSql: string,
  format?: string
): string[];

import {
  getParameterReferences,
  getParameterReferencesFromSqlAndFormat,
} from '@lightdash/common';

// Extract from SQL
const sql = `
  SELECT * FROM orders
  WHERE status = '\${lightdash.parameters.status}'
    AND region = '\${ld.parameters.region}'
`;

const params = getParameterReferences(sql);
// params = ['status', 'region']

// Extract from SQL and format string
const compiledSql = 'SELECT amount FROM orders';
const format = '\${ld.parameters.currency_symbol}\${value}';

const allParams = getParameterReferencesFromSqlAndFormat(
  compiledSql,
  format
);
// allParams = ['currency_symbol']

/**
 * Validate parameter references against available parameters
 * @param tableName - Table name for error messages
 * @param parameterReferences - Parameter names being referenced
 * @param availableParameters - Available parameter names
 * @throws CompileError if parameters are missing
 */
function validateParameterReferences(
  tableName: string,
  parameterReferences: string[],
  availableParameters: string[]
): void;

/**
 * Validate parameter names follow naming rules
 * @param parameters - Parameters to validate
 * @returns Validation result with invalid parameter names
 */
function validateParameterNames(
  parameters: Record<string, LightdashProjectParameter> | undefined
): {
  isInvalid: boolean;
  invalidParameters: string[];
};

import {
  validateParameterReferences,
  validateParameterNames,
} from '@lightdash/common';

// Validate references
const referencedParams = ['order_status', 'region'];
const availableParams = ['order_status', 'region', 'start_date'];

try {
  validateParameterReferences(
    'orders',
    referencedParams,
    availableParams
  );
  // Validation passes
} catch (error) {
  // CompileError thrown if parameters missing
}

// Validate parameter names (alphanumeric, underscore, hyphen only)
const parameters = {
  'order_status': { type: 'string', default: 'pending' },
  'invalid name!': { type: 'string', default: 'test' },
};

const validation = validateParameterNames(parameters);
// validation = {
//   isInvalid: true,
//   invalidParameters: ['invalid name!']
// }

/**
 * Get all available parameter names for project and explore
 * @param projectParameters - Project-level parameters
 * @param exploreParameters - Explore-level parameters
 * @returns Array of all available parameter names
 */
function getAvailableParameterNames(
  projectParameters: Record<string, LightdashProjectParameter> | undefined,
  exploreParameters: Record<string, LightdashProjectParameter> | undefined
): string[];

/**
 * Get parameters from included tables (model-level parameters)
 * @param includedTables - Tables with parameter definitions
 * @returns Map of qualified parameter names to definitions
 */
function getAvailableParametersFromTables(
  includedTables: (Table | CompiledTable)[]
): Record<string, LightdashProjectParameter>;

import {
  getAvailableParameterNames,
  getAvailableParametersFromTables,
} from '@lightdash/common';

// Get all available parameter names
const projectParams = {
  'global_date': { type: 'date', default: '2024-01-01' },
};

const exploreParams = {
  'order_status': { type: 'string', default: 'pending' },
};

const allParams = getAvailableParameterNames(
  projectParams,
  exploreParams
);
// allParams = ['global_date', 'order_status']

// Get table-scoped parameters
const tables = [
  {
    name: 'orders',
    parameters: {
      'region': { type: 'string', default: 'US' },
    },
  },
  {
    name: 'customers',
    parameters: {
      'segment': { type: 'string', default: 'retail' },
    },
  },
];

const tableParams = getAvailableParametersFromTables(tables);
// tableParams = {
//   'orders.region': { type: 'string', default: 'US' },
//   'customers.segment': { type: 'string', default: 'retail' }
// }

# lightdash.yml or dbt_project.yml
parameters:
  global_start_date:
    type: date
    default: '2024-01-01'
    description: 'Global start date for analysis'

  currency:
    type: string
    default: 'USD'
    description: 'Currency code for reporting'

SELECT * FROM orders
WHERE created_at >= '${lightdash.parameters.global_start_date}'

# models/orders.yml
models:
  - name: orders
    parameters:
      region:
        type: string
        default: 'US'
        description: 'Order region filter'

SELECT * FROM orders
WHERE region = '${lightdash.parameters.orders.region}'

explores:
  - name: sales_analysis
    parameters:
      sales_threshold:
        type: number
        default: 1000

SELECT * FROM orders
WHERE total_amount > ${lightdash.parameters.sales_threshold}

parameters:
  report_date:
    type: date
    default: '2024-01-01'

dimensions:
  - name: is_in_reporting_period
    type: boolean
    sql: |
      ${TABLE}.order_date >= '${lightdash.parameters.report_date}'

parameters:
  exchange_rate:
    type: number
    default: 1.0

metrics:
  - name: revenue_usd
    type: number
    sql: ${TABLE}.revenue * ${lightdash.parameters.exchange_rate}

parameters:
  currency_symbol:
    type: string
    default: '$'

dimensions:
  - name: amount
    type: number
    format: '${ld.parameters.currency_symbol}${value}'

parameters:
  selected_regions:
    type: string[]
    default: ['US', 'UK', 'CA']

dimensions:
  - name: is_selected_region
    type: boolean
    sql: |
      ${TABLE}.region IN (${lightdash.parameters.selected_regions})

import {
  getParameterReferences,
  validateParameterReferences,
  getAvailableParameterNames,
} from '@lightdash/common';

function validateExploreParameters(
  compiledSql: string,
  projectParameters: Record<string, LightdashProjectParameter>,
  exploreParameters: Record<string, LightdashProjectParameter>,
  tableName: string
) {
  // Extract parameter references from SQL
  const references = getParameterReferences(compiledSql);

  // Get all available parameters
  const available = getAvailableParameterNames(
    projectParameters,
    exploreParameters
  );

  // Validate all references exist
  validateParameterReferences(tableName, references, available);
}