Semantics
Parameters
Enable dynamic query generation by allowing metrics to accept runtime values, making metrics flexible and reusable.
Overview
Parameters are runtime variables that can be injected into your metric queries. They allow you to create flexible, reusable metrics that can adapt to different requirements without modifying the metric definition.
Diagram showing how parameters flow from user input to query execution
Use Cases
Parameters are used for:
- Time-based Analysis: Dynamic date ranges, periods, and time windows
- User Segmentation: Filter by user groups, regions, or demographics
- A/B Testing: Compare different variants or test groups
- Custom Dashboards: Personalized views based on user preferences
- Report Generation: Automated reports with different parameters
Syntax
Type: ParameterDefinition
Runtime parameters for dynamic query generation. Allows metrics to accept parameters at query time.
{
"parameters": {
"date_range": {
"name": "date_range",
"type": "date",
"description": "Date range for filtering",
"required": true,
"default_value": "2024-01-01"
},
"user_segment": {
"name": "user_segment",
"type": "string",
"description": "User segment to filter by",
"required": false,
"allowed_values": ["premium", "standard", "basic"],
"default_value": "standard"
},
"revenue_threshold": {
"name": "revenue_threshold",
"type": "float",
"description": "Minimum revenue threshold",
"min_value": 0.0,
"max_value": 1000000.0,
"default_value": 1000.0
}
}
}
Parameters
name
Type: str
Required: Yes
Parameter identifier name. Used to reference the parameter in queries and API calls.
{
"name": "date_range"
}
type
Type: ParameterType
Required: Yes
Parameter data type. Determines how the parameter value is validated and processed.
Available Values:
string,integer,float,booleandate,datetime,list
{
"type": "date"
}
description
Type: Optional[str]
Default: None
Required: No
Human-readable explanation of the parameter. Helps users understand what the parameter controls.
{
"description": "Start date for the analysis period"
}
default_value
Type: Optional[Any]
Default: None
Required: No
Default value if not provided. Used when the parameter is not specified in the query.
{
"default_value": "2024-01-01"
}
required
Type: bool
Default: False
Required: No
Whether the parameter is mandatory. When true, the parameter must be provided.
{
"required": true
}
allowed_values
Type: Optional[List[Any]]
Default: None
Required: No
Array of valid values for enum-like parameters. Restricts parameter values to specific options.
{
"allowed_values": ["premium", "standard", "basic"]
}
validation_regex
Type: Optional[str]
Default: None
Required: No
Regular expression for string validation. Ensures parameter values match a specific pattern.
{
"validation_regex": "^[a-zA-Z0-9_]+$"
}
min_value
Type: Optional[float]
Default: None
Required: No
Minimum value for numeric parameters. Validates that numeric parameters meet minimum requirements.
{
"min_value": 0.0
}
max_value
Type: Optional[float]
Default: None
Required: No
Maximum value for numeric parameters. Validates that numeric parameters don't exceed maximum limits.
{
"max_value": 1000000.0
}
Patterns
Date Range Parameters
{
"parameters": {
"start_date": {
"name": "start_date",
"type": "date",
"description": "Analysis start date",
"required": true,
"default_value": "2024-01-01"
},
"end_date": {
"name": "end_date",
"type": "date",
"description": "Analysis end date",
"required": true,
"default_value": "2024-12-31"
}
}
}
User Segmentation Parameters
{
"parameters": {
"user_segment": {
"name": "user_segment",
"type": "string",
"description": "User segment to analyze",
"required": false,
"allowed_values": ["premium", "standard", "basic", "all"],
"default_value": "all"
},
"region": {
"name": "region",
"type": "string",
"description": "Geographic region",
"required": false,
"allowed_values": ["north_america", "europe", "asia", "all"],
"default_value": "all"
}
}
}
Threshold Parameters
{
"parameters": {
"revenue_threshold": {
"name": "revenue_threshold",
"type": "float",
"description": "Minimum revenue threshold",
"required": false,
"min_value": 0.0,
"max_value": 1000000.0,
"default_value": 1000.0
},
"min_orders": {
"name": "min_orders",
"type": "integer",
"description": "Minimum number of orders",
"required": false,
"min_value": 1,
"max_value": 10000,
"default_value": 1
}
}
}
Boolean Parameters
{
"parameters": {
"include_test_data": {
"name": "include_test_data",
"type": "boolean",
"description": "Include test data in analysis",
"required": false,
"default_value": false
},
"show_details": {
"name": "show_details",
"type": "boolean",
"description": "Show detailed breakdown",
"required": false,
"default_value": true
}
}
}
List Parameters
{
"parameters": {
"product_categories": {
"name": "product_categories",
"type": "list",
"description": "Product categories to include",
"required": false,
"allowed_values": ["electronics", "clothing", "books", "home"],
"default_value": ["electronics", "clothing"]
}
}
}
Using Parameters in Queries
Basic Parameter Usage
-- In your metric query
SELECT
user_segment,
SUM(revenue) as total_revenue
FROM orders o
JOIN users u ON o.user_id = u.id
WHERE
o.created_at >= $CORTEX_start_date
AND o.created_at <= $CORTEX_end_date
AND ($CORTEX_user_segment = 'all' OR u.segment = $CORTEX_user_segment)
GROUP BY user_segment
Conditional Logic with Parameters
-- Using parameters in conditional logic
SELECT
CASE
WHEN $CORTEX_include_test_data THEN 'All Users'
ELSE 'Production Users'
END as user_type,
COUNT(*) as user_count
FROM users
WHERE
($CORTEX_include_test_data = true OR email NOT LIKE '%@test.%')
Dynamic Filtering
-- Dynamic filtering based on parameters
SELECT
product_category,
SUM(revenue) as category_revenue
FROM orders o
JOIN products p ON o.product_id = p.id
WHERE
p.category IN ($CORTEX_product_categories)
AND o.revenue >= $CORTEX_revenue_threshold
GROUP BY product_category
Parameter Validation
Type Validation
{
"parameters": {
"age": {
"name": "age",
"type": "integer",
"min_value": 0,
"max_value": 120,
"description": "User age (0-120)"
}
}
}
String Pattern Validation
{
"parameters": {
"email_domain": {
"name": "email_domain",
"type": "string",
"validation_regex": "^[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
"description": "Email domain pattern"
}
}
}
Enum Validation
{
"parameters": {
"time_period": {
"name": "time_period",
"type": "string",
"allowed_values": ["daily", "weekly", "monthly", "quarterly", "yearly"],
"description": "Time period for aggregation"
}
}
}
Advanced Techniques
Dependent Parameters
{
"parameters": {
"analysis_type": {
"name": "analysis_type",
"type": "string",
"allowed_values": ["revenue", "users", "products"],
"description": "Type of analysis to perform"
},
"revenue_threshold": {
"name": "revenue_threshold",
"type": "float",
"description": "Revenue threshold (only used when analysis_type = 'revenue')",
"required": false
}
}
}
Parameter Combinations
{
"parameters": {
"start_date": {
"name": "start_date",
"type": "date",
"description": "Start date"
},
"end_date": {
"name": "end_date",
"type": "date",
"description": "End date"
},
"period_length": {
"name": "period_length",
"type": "integer",
"description": "Period length in days",
"min_value": 1,
"max_value": 365
}
}
}
UI Components
Date Pickers
{
"parameters": {
"date_range": {
"name": "date_range",
"type": "date",
"description": "Select date range",
"ui_component": "date_range_picker"
}
}
}
Dropdown Selectors
{
"parameters": {
"user_segment": {
"name": "user_segment",
"type": "string",
"allowed_values": ["premium", "standard", "basic"],
"ui_component": "dropdown"
}
}
}
Slider Controls
{
"parameters": {
"revenue_threshold": {
"name": "revenue_threshold",
"type": "float",
"min_value": 0,
"max_value": 100000,
"ui_component": "slider"
}
}
}
Best Practices
- Use Descriptive Names: Choose clear, descriptive parameter names
- Provide Defaults: Always provide sensible default values when possible
- Validate Input: Use appropriate validation rules for your parameters
- Document Parameters: Include clear descriptions for all parameters
- Test Edge Cases: Test parameter validation with edge cases and invalid values
Video Tutorial
Video: How to set up dynamic parameters in the Cortex dashboard
Parameter Builder Interface
Screenshot of the parameter configuration interface in the Cortex dashboard
API Usage Examples
Query with Parameters
curl -X POST /api/metrics/execute \
-H "Content-Type: application/json" \
-d '{
"metric_id": "user_revenue_analysis",
"parameters": {
"start_date": "2024-01-01",
"end_date": "2024-12-31",
"user_segment": "premium"
}
}'
Parameter Validation Response
{
"error": "Invalid parameter value",
"details": {
"parameter": "revenue_threshold",
"value": -100,
"constraint": "min_value: 0.0"
}
}
Related Topics
- Filters Configuration - Using parameters in filters
- Measures Configuration - Parameters in measure calculations
- Measures Configuration - Complete metric setup guide