Skip to main content

Configuration Reference

This reference covers all configuration options available in Olytix Core, including project configuration files and environment variables.

Project Configuration​

The olytix-core_project.yml file defines your project settings and is located at the root of your project directory.

Basic Structure​

name: my_analytics
version: 1.0.0
profile: default

config:
  # Default settings
  default_schema: public
  default_materialization: view

  # Path configuration
  model_paths:
    - models
  cube_paths:
    - cubes
  source_paths:
    - sources
  metric_paths:
    - metrics
  seed_paths:
    - seeds
  target_path: target

semantic:
  # Semantic layer settings
  default_timezone: UTC
  auto_generate_cubes: false
  cache:
    enabled: true
    ttl_seconds: 300

lineage:
  # Lineage tracking
  column_level: true
  include_in_manifest: true

experimental:
  # Experimental features
  {}

Project Configuration Fields​

FieldTypeDefaultDescription
namestring-Project name (required)
versionstring1.0.0Project version
profilestringdefaultDatabase profile name

Config Section​

FieldTypeDefaultDescription
default_schemastringpublicDefault database schema
default_materializationstringviewDefault model materialization
model_pathslist["models"]Directories containing model files
cube_pathslist["cubes"]Directories containing cube files
source_pathslist["sources"]Directories containing source files
metric_pathslist["metrics"]Directories containing metric files
seed_pathslist["seeds"]Directories containing seed files
target_pathstringtargetOutput directory for compiled artifacts

Semantic Section​

FieldTypeDefaultDescription
default_timezonestringUTCDefault timezone for time operations
auto_generate_cubesbooleanfalseAutomatically generate cubes from models
cache.enabledbooleantrueEnable query result caching
cache.ttl_secondsinteger300Cache time-to-live in seconds

Lineage Section​

FieldTypeDefaultDescription
column_levelbooleantrueEnable column-level lineage tracking
include_in_manifestbooleantrueInclude lineage in manifest.json

Environment Variables​

Olytix Core uses environment variables with the OLYTIX_ prefix. Nested configuration uses double underscores (__) as delimiters.

Environment​

VariableTypeDefaultDescription
OLYTIX_ENVIRONMENTstringdevelopmentEnvironment: development, staging, production

Metadata Database​

VariableTypeDefaultDescription
OLYTIX_METADATA_DB__HOSTstringlocalhostMetadata database host
OLYTIX_METADATA_DB__PORTinteger5432Metadata database port
OLYTIX_METADATA_DB__DATABASEstringolytix-core_metadataMetadata database name
OLYTIX_METADATA_DB__USERstringolytix-coreMetadata database user
OLYTIX_METADATA_DB__PASSWORDstring-Metadata database password
OLYTIX_METADATA_DB__MIN_CONNECTIONSinteger5Minimum connection pool size
OLYTIX_METADATA_DB__MAX_CONNECTIONSinteger20Maximum connection pool size
OLYTIX_METADATA_DB__CONNECTION_TIMEOUT_SECONDSfloat10.0Connection timeout
OLYTIX_METADATA_DB__COMMAND_TIMEOUT_SECONDSfloat60.0Command timeout
OLYTIX_METADATA_DB__IDLE_TIMEOUT_SECONDSfloat300.0Idle connection timeout

Warehouse Configuration​

Warehouse Type​

VariableTypeDefaultDescription
OLYTIX_WAREHOUSE__TYPEstringpostgresqlWarehouse type: postgresql, snowflake, bigquery, databricks, redshift, duckdb

PostgreSQL​

VariableTypeDefaultDescription
OLYTIX_WAREHOUSE__POSTGRESQL__HOSTstringlocalhostPostgreSQL host
OLYTIX_WAREHOUSE__POSTGRESQL__PORTinteger5432PostgreSQL port
OLYTIX_WAREHOUSE__POSTGRESQL__DATABASEstringolytix-coreDatabase name
OLYTIX_WAREHOUSE__POSTGRESQL__USERstringolytix-coreDatabase user
OLYTIX_WAREHOUSE__POSTGRESQL__PASSWORDstring-Database password
OLYTIX_WAREHOUSE__POSTGRESQL__MIN_CONNECTIONSinteger5Minimum connections
OLYTIX_WAREHOUSE__POSTGRESQL__MAX_CONNECTIONSinteger20Maximum connections

Snowflake​

VariableTypeDefaultDescription
OLYTIX_WAREHOUSE__SNOWFLAKE__ACCOUNTstring-Snowflake account identifier
OLYTIX_WAREHOUSE__SNOWFLAKE__USERstring-Snowflake user
OLYTIX_WAREHOUSE__SNOWFLAKE__PASSWORDstring-Snowflake password
OLYTIX_WAREHOUSE__SNOWFLAKE__WAREHOUSEstring-Snowflake warehouse
OLYTIX_WAREHOUSE__SNOWFLAKE__DATABASEstring-Snowflake database
OLYTIX_WAREHOUSE__SNOWFLAKE__SCHEMAstringPUBLICSnowflake schema
OLYTIX_WAREHOUSE__SNOWFLAKE__ROLEstring-Snowflake role
OLYTIX_WAREHOUSE__SNOWFLAKE__AUTH_METHODstringpasswordAuth method: password, externalbrowser, oauth, key_pair
OLYTIX_WAREHOUSE__SNOWFLAKE__PRIVATE_KEY_PATHstring-Path to private key for key_pair auth
OLYTIX_WAREHOUSE__SNOWFLAKE__MIN_CONNECTIONSinteger1Minimum connections
OLYTIX_WAREHOUSE__SNOWFLAKE__MAX_CONNECTIONSinteger10Maximum connections
OLYTIX_WAREHOUSE__SNOWFLAKE__CONNECTION_TIMEOUT_SECONDSfloat30.0Connection timeout
OLYTIX_WAREHOUSE__SNOWFLAKE__QUERY_TIMEOUT_SECONDSfloat300.0Query timeout

BigQuery​

VariableTypeDefaultDescription
OLYTIX_WAREHOUSE__BIGQUERY__PROJECTstring-GCP project ID
OLYTIX_WAREHOUSE__BIGQUERY__DATASETstring-Default dataset
OLYTIX_WAREHOUSE__BIGQUERY__LOCATIONstringUSBigQuery location
OLYTIX_WAREHOUSE__BIGQUERY__CREDENTIALS_PATHstring-Path to service account JSON
OLYTIX_WAREHOUSE__BIGQUERY__QUERY_TIMEOUT_SECONDSfloat300.0Query timeout
OLYTIX_WAREHOUSE__BIGQUERY__MAXIMUM_BYTES_BILLEDinteger-Maximum bytes billed per query

Databricks​

VariableTypeDefaultDescription
OLYTIX_WAREHOUSE__DATABRICKS__HOSTstring-Databricks workspace host
OLYTIX_WAREHOUSE__DATABRICKS__HTTP_PATHstring-SQL warehouse HTTP path
OLYTIX_WAREHOUSE__DATABRICKS__ACCESS_TOKENstring-Personal access token
OLYTIX_WAREHOUSE__DATABRICKS__CATALOGstringmainUnity Catalog name
OLYTIX_WAREHOUSE__DATABRICKS__SCHEMAstringdefaultDefault schema
OLYTIX_WAREHOUSE__DATABRICKS__CONNECTION_TIMEOUT_SECONDSfloat30.0Connection timeout
OLYTIX_WAREHOUSE__DATABRICKS__QUERY_TIMEOUT_SECONDSfloat300.0Query timeout

Redshift​

VariableTypeDefaultDescription
OLYTIX_WAREHOUSE__REDSHIFT__HOSTstring-Redshift cluster endpoint
OLYTIX_WAREHOUSE__REDSHIFT__PORTinteger5439Redshift port
OLYTIX_WAREHOUSE__REDSHIFT__DATABASEstringdevDatabase name
OLYTIX_WAREHOUSE__REDSHIFT__USERstring-Database user
OLYTIX_WAREHOUSE__REDSHIFT__PASSWORDstring-Database password
OLYTIX_WAREHOUSE__REDSHIFT__SCHEMAstringpublicDefault schema
OLYTIX_WAREHOUSE__REDSHIFT__SSLbooleantrueEnable SSL
OLYTIX_WAREHOUSE__REDSHIFT__MIN_CONNECTIONSinteger1Minimum connections
OLYTIX_WAREHOUSE__REDSHIFT__MAX_CONNECTIONSinteger10Maximum connections

DuckDB​

VariableTypeDefaultDescription
OLYTIX_WAREHOUSE__DUCKDB__DATABASEstring:memory:Database path or :memory:
OLYTIX_WAREHOUSE__DUCKDB__SCHEMAstringmainDefault schema
OLYTIX_WAREHOUSE__DUCKDB__READ_ONLYbooleanfalseRead-only mode
OLYTIX_WAREHOUSE__DUCKDB__THREADSinteger-Number of threads
OLYTIX_WAREHOUSE__DUCKDB__MEMORY_LIMITstring-Memory limit (e.g., 4GB)

Redis Cache​

VariableTypeDefaultDescription
OLYTIX_REDIS__HOSTstringlocalhostRedis host
OLYTIX_REDIS__PORTinteger6379Redis port
OLYTIX_REDIS__DBinteger0Redis database number
OLYTIX_REDIS__PASSWORDstring-Redis password
OLYTIX_REDIS__MAX_CONNECTIONSinteger50Maximum connections
OLYTIX_REDIS__SOCKET_TIMEOUTfloat5.0Socket timeout in seconds
OLYTIX_REDIS__RETRY_ON_TIMEOUTbooleantrueRetry on timeout

API Settings​

VariableTypeDefaultDescription
OLYTIX_API__HOSTstring0.0.0.0API host
OLYTIX_API__PORTinteger8000API port
OLYTIX_API__WORKERSinteger4Number of workers
OLYTIX_API__DEBUGbooleanfalseDebug mode
OLYTIX_API__CORS_ORIGINSlist["*"]Allowed CORS origins
OLYTIX_API__CORS_ALLOW_CREDENTIALSbooleantrueAllow credentials in CORS
OLYTIX_API__API_PREFIXstring/api/v1API prefix
OLYTIX_API__DOCS_ENABLEDbooleantrueEnable OpenAPI docs

Authentication​

VariableTypeDefaultDescription
OLYTIX_AUTH__ENABLEDbooleanfalseEnable authentication
OLYTIX_AUTH__API_KEY_HEADERstringX-API-KeyAPI key header name
OLYTIX_AUTH__JWT_SECRETstring-JWT secret key (required in production)
OLYTIX_AUTH__JWT_ALGORITHMstringHS256JWT algorithm
OLYTIX_AUTH__JWT_EXPIRY_HOURSinteger24JWT token expiry in hours
OLYTIX_AUTH__API_KEYSlist[]Valid API keys

Query Limits​

VariableTypeDefaultDescription
OLYTIX_QUERY_LIMITS__MAX_JOIN_DEPTHinteger10Maximum join depth
OLYTIX_QUERY_LIMITS__MAX_SUBQUERY_DEPTHinteger5Maximum subquery depth
OLYTIX_QUERY_LIMITS__MAX_EXPRESSIONSinteger1000Maximum expressions per query
OLYTIX_QUERY_LIMITS__MAX_RESULT_ROWSinteger1000000Maximum result rows
OLYTIX_QUERY_LIMITS__TIMEOUT_SECONDSinteger300Query timeout
OLYTIX_QUERY_LIMITS__PLAN_CACHE_SIZEinteger1000Plan cache size

Pre-Aggregation​

VariableTypeDefaultDescription
OLYTIX_PREAGG__ENABLEDbooleantrueEnable pre-aggregation
OLYTIX_PREAGG__SCHEMA_NAMEstringpreaggSchema for pre-agg tables
OLYTIX_PREAGG__ENABLE_ON_DEMANDbooleantrueEnable on-demand builds
OLYTIX_PREAGG__ON_DEMAND_TIMEOUT_SECONDSfloat300.0On-demand build timeout
OLYTIX_PREAGG__STALE_THRESHOLD_SECONDSinteger3600Stale threshold
OLYTIX_PREAGG__MAX_CONCURRENT_BUILDSinteger4Max concurrent builds
OLYTIX_PREAGG__BUILD_TIMEOUT_SECONDSinteger3600Build timeout
OLYTIX_PREAGG__RETRY_DELAY_SECONDSinteger300Retry delay after failure
OLYTIX_PREAGG__MAX_RETRIESinteger3Maximum retry attempts
OLYTIX_PREAGG__CACHE_TTL_SECONDSinteger3600Hot cache TTL
OLYTIX_PREAGG__WARM_CACHE_ON_BUILDbooleantrueWarm cache after build

DAX API​

VariableTypeDefaultDescription
OLYTIX_DAX__ENABLEDbooleantrueEnable DAX API
OLYTIX_DAX__XMLA_ENABLEDbooleantrueEnable XMLA protocol endpoint
OLYTIX_DAX__SESSION_TIMEOUT_SECONDSinteger3600XMLA session timeout
OLYTIX_DAX__SESSION_CLEANUP_INTERVAL_SECONDSinteger300Session cleanup interval
OLYTIX_DAX__QUERY_TIMEOUT_SECONDSinteger300DAX query timeout
OLYTIX_DAX__MAX_RESULT_ROWSinteger1000000Max rows from DAX query
OLYTIX_DAX__CACHE_ENABLEDbooleantrueEnable DAX query caching
OLYTIX_DAX__CACHE_TTL_SECONDSinteger300DAX cache TTL
OLYTIX_DAX__CATALOG_NAMEstringOlytix CoreXMLA catalog name
OLYTIX_DAX__SERVER_NAMEstringOlytix CoreXMLA server name

Resilience Configuration​

Circuit Breaker​

VariableTypeDefaultDescription
OLYTIX_RESILIENCE__CIRCUIT_BREAKER__FAILURE_THRESHOLDinteger5Failures before opening
OLYTIX_RESILIENCE__CIRCUIT_BREAKER__SUCCESS_THRESHOLDinteger3Successes to close
OLYTIX_RESILIENCE__CIRCUIT_BREAKER__RECOVERY_TIMEOUT_SECONDSfloat30.0Recovery timeout
OLYTIX_RESILIENCE__CIRCUIT_BREAKER__HALF_OPEN_MAX_CALLSinteger3Max half-open calls

Retry Policy​

VariableTypeDefaultDescription
OLYTIX_RESILIENCE__RETRY__MAX_RETRIESinteger3Maximum retry attempts
OLYTIX_RESILIENCE__RETRY__BASE_DELAY_SECONDSfloat0.1Initial delay
OLYTIX_RESILIENCE__RETRY__MAX_DELAY_SECONDSfloat5.0Maximum delay
OLYTIX_RESILIENCE__RETRY__EXPONENTIAL_BASEfloat2.0Exponential backoff base
OLYTIX_RESILIENCE__RETRY__JITTERbooleantrueAdd random jitter

Bulkhead​

VariableTypeDefaultDescription
OLYTIX_RESILIENCE__BULKHEAD__MAX_CONCURRENT_REQUESTSinteger100Max concurrent requests
OLYTIX_RESILIENCE__BULKHEAD__MAX_QUEUE_DEPTHinteger500Max queue depth
OLYTIX_RESILIENCE__BULKHEAD__QUEUE_TIMEOUT_SECONDSfloat30.0Queue timeout

Tenant Limits​

VariableTypeDefaultDescription
OLYTIX_RESILIENCE__TENANT__MAX_CONNECTIONSinteger20Max connections per tenant
OLYTIX_RESILIENCE__TENANT__MAX_CONCURRENT_QUERIESinteger10Max concurrent queries
OLYTIX_RESILIENCE__TENANT__MAX_MEMORY_MBinteger4096Max memory in MB
OLYTIX_RESILIENCE__TENANT__MAX_QUERY_DURATION_SECONDSinteger300Max query duration

Logging​

VariableTypeDefaultDescription
OLYTIX_LOGGING__LEVELstringINFOLog level: DEBUG, INFO, WARNING, ERROR, CRITICAL
OLYTIX_LOGGING__FORMATstringjsonLog format: json, console
OLYTIX_LOGGING__INCLUDE_TIMESTAMPbooleantrueInclude timestamp
OLYTIX_LOGGING__INCLUDE_CALLERbooleantrueInclude caller info

Feature Flags​

VariableTypeDefaultDescription
OLYTIX_ENABLE_METRICSbooleantrueEnable Prometheus metrics
OLYTIX_ENABLE_TRACINGbooleantrueEnable OpenTelemetry tracing

Configuration File (.env)​

You can use a .env file in your project root for local development:

# .env
OLYTIX_ENVIRONMENT=development

# Database
OLYTIX_WAREHOUSE__TYPE=postgresql
OLYTIX_WAREHOUSE__POSTGRESQL__HOST=localhost
OLYTIX_WAREHOUSE__POSTGRESQL__PORT=5432
OLYTIX_WAREHOUSE__POSTGRESQL__DATABASE=analytics
OLYTIX_WAREHOUSE__POSTGRESQL__USER=developer
OLYTIX_WAREHOUSE__POSTGRESQL__PASSWORD=secret

# Redis
OLYTIX_REDIS__HOST=localhost
OLYTIX_REDIS__PORT=6379

# API
OLYTIX_API__PORT=8000
OLYTIX_API__DEBUG=true

# Logging
OLYTIX_LOGGING__LEVEL=DEBUG
OLYTIX_LOGGING__FORMAT=console

Production Configuration Example​

# Production .env
OLYTIX_ENVIRONMENT=production

# Snowflake warehouse
OLYTIX_WAREHOUSE__TYPE=snowflake
OLYTIX_WAREHOUSE__SNOWFLAKE__ACCOUNT=xy12345.us-east-1
OLYTIX_WAREHOUSE__SNOWFLAKE__USER=analytics_service
OLYTIX_WAREHOUSE__SNOWFLAKE__PASSWORD=${SNOWFLAKE_PASSWORD}
OLYTIX_WAREHOUSE__SNOWFLAKE__WAREHOUSE=COMPUTE_WH
OLYTIX_WAREHOUSE__SNOWFLAKE__DATABASE=ANALYTICS
OLYTIX_WAREHOUSE__SNOWFLAKE__ROLE=ANALYTICS_ROLE

# Redis cluster
OLYTIX_REDIS__HOST=redis.production.internal
OLYTIX_REDIS__PASSWORD=${REDIS_PASSWORD}

# API settings
OLYTIX_API__PORT=8000
OLYTIX_API__WORKERS=8
OLYTIX_API__DEBUG=false
OLYTIX_API__CORS_ORIGINS=["https://app.example.com"]

# Authentication (required in production)
OLYTIX_AUTH__ENABLED=true
OLYTIX_AUTH__JWT_SECRET=${JWT_SECRET}
OLYTIX_AUTH__API_KEYS=["key1", "key2"]

# Query limits
OLYTIX_QUERY_LIMITS__MAX_RESULT_ROWS=100000
OLYTIX_QUERY_LIMITS__TIMEOUT_SECONDS=60

# Pre-aggregation
OLYTIX_PREAGG__ENABLED=true
OLYTIX_PREAGG__MAX_CONCURRENT_BUILDS=8

# Logging
OLYTIX_LOGGING__LEVEL=INFO
OLYTIX_LOGGING__FORMAT=json

# Observability
OLYTIX_ENABLE_METRICS=true
OLYTIX_ENABLE_TRACING=true

Best Practices​

  1. Use environment variables for secrets: Never commit passwords or API keys to version control.

  2. Set appropriate timeouts: Configure timeouts based on your query complexity and infrastructure.

  3. Enable authentication in production: Always set OLYTIX_AUTH__ENABLED=true for production deployments.

  4. Configure connection pools: Size connection pools based on expected concurrency.

  5. Use structured logging: Set OLYTIX_LOGGING__FORMAT=json for production to enable log aggregation.

  6. Set query limits: Protect your system with appropriate query complexity and result size limits.

  7. Enable pre-aggregations: Use pre-aggregations for frequently queried data combinations.