# Lotus v0.16.6 - Table of Contents Embeddable business intelligence engine for Elixir — run SQL queries, build dashboards, and manage analytics directly in your Phoenix app with Ecto. ## Pages - [Lotus](readme.md) - [Overview](overview.md) - [Installation](installation.md) - [Getting Started](getting-started.md) - [Dashboards](dashboards.md) - [Advanced Variables](advanced-variables.md) - [AI Query Generation](ai_query_generation.md) - [Configuration](configuration.md) - [Middleware](middleware.md) - [Visibility Rules](visibility.md) - [Caching Guide](caching.md) - [Telemetry](telemetry.md) - [Contributing to Lotus](contributing.md) ## Modules - [CSVParser](CSVParser.md) - [Lotus.AI.Error](Lotus.AI.Error.md): Domain errors for AI service failures. - [Lotus.AI.ErrorDetector](Lotus.AI.ErrorDetector.md): Analyzes SQL query errors and provides actionable suggestions. - [Lotus.AI.Prompts.Explanation](Lotus.AI.Prompts.Explanation.md): Prompts for AI-powered SQL query explanations. - [Lotus.AI.Prompts.Optimization](Lotus.AI.Prompts.Optimization.md): System prompts for AI-powered query optimization suggestions. - [Lotus.AI.Prompts.SQLGeneration](Lotus.AI.Prompts.SQLGeneration.md): System prompts for SQL query generation. - [Lotus.AI.Prompts.Variables](Lotus.AI.Prompts.Variables.md): Source-agnostic variable system documentation for AI prompts. - [Lotus.AI.SchemaOptimizer](Lotus.AI.SchemaOptimizer.md): Optimizes schema loading for large databases using two-stage approach. - [Lotus.Dashboards](Lotus.Dashboards.md): Service functions for managing dashboards in Lotus. - [Lotus.Middleware](Lotus.Middleware.md): Generic middleware pipeline for query execution and schema discovery hooks. - [Lotus.Normalizer](Lotus.Normalizer.md): Protocol for normalizing raw database values into JSON-safe, displayable forms. - [Lotus.Preflight.Relations](Lotus.Preflight.Relations.md): Manages preflight relations stored in the process dictionary. - [Lotus.Query.Filter](Lotus.Query.Filter.md): Represents a filter condition to apply on query results. - [Lotus.Query.Sort](Lotus.Query.Sort.md): Represents a sort directive to apply on query results. - [Lotus.Result.Statistics](Lotus.Result.Statistics.md): Computes column-level statistics from in-memory query results. - [Lotus.SQL.FilterInjector](Lotus.SQL.FilterInjector.md): Shared helpers for SQL-based sources to inject filter conditions into queries. - [Lotus.SQL.OptionalClause](Lotus.SQL.OptionalClause.md): Processes `[[...]]` optional clause syntax in SQL queries. - [Lotus.SQL.Sanitizer](Lotus.SQL.Sanitizer.md): Shared helpers for cleaning SQL strings before further processing. - [Lotus.SQL.SortInjector](Lotus.SQL.SortInjector.md): Shared helpers for SQL-based sources to inject sort directives into queries. - [Lotus.SQL.Validator](Lotus.SQL.Validator.md): Validates SQL syntax by preparing it against the database without executing. - [Lotus.Storage.Dashboard](Lotus.Storage.Dashboard.md): Represents a saved Lotus dashboard. - [Lotus.Storage.DashboardCard](Lotus.Storage.DashboardCard.md): Represents a card within a Lotus dashboard. - [Lotus.Storage.DashboardCard.Layout](Lotus.Storage.DashboardCard.Layout.md): Embedded schema for card layout in the dashboard grid. - [Lotus.Storage.DashboardCardFilterMapping](Lotus.Storage.DashboardCardFilterMapping.md): Maps a dashboard filter to a query variable within a card. - [Lotus.Storage.DashboardFilter](Lotus.Storage.DashboardFilter.md): Represents a filter control for a Lotus dashboard. - [Lotus.Storage.QueryVariable.StaticOption](Lotus.Storage.QueryVariable.StaticOption.md): Represents a single static option for a QueryVariable select widget. - [Lotus.Storage.QueryVisualization](Lotus.Storage.QueryVisualization.md): Represents a saved visualization configuration for a Lotus query. - [Lotus.Storage.SchemaCache](Lotus.Storage.SchemaCache.md): Caches table schema metadata for automatic type detection and casting. - [Lotus.Storage.TypeCaster](Lotus.Storage.TypeCaster.md): Casts variable values to appropriate types based on database column types. - [Lotus.Storage.TypeHandler](Lotus.Storage.TypeHandler.md): Behavior for implementing custom database type handlers. - [Lotus.Storage.TypeMapper](Lotus.Storage.TypeMapper.md): Maps database column types to Lotus internal types for automatic casting. - [Lotus.Storage.VariableResolver](Lotus.Storage.VariableResolver.md): Extracts variable-to-column bindings from SQL queries. - [Lotus.Variables](Lotus.Variables.md): Utilities for Lotus `{{variable}}` template syntax. - [Lotus.Visibility.Policy](Lotus.Visibility.Policy.md): Policy builders and validators for visibility rules. - [Lotus.Viz](Lotus.Viz.md): Service functions for managing query visualizations in Lotus storage. - Core API - [Lotus](Lotus.md): Lotus is a lightweight Elixir library for saving and executing read-only SQL queries. - [Lotus.Config](Lotus.Config.md): Configuration management for Lotus. - [Lotus.Value](Lotus.Value.md): Central value normalization for JSON/CSV/UI display. - Query Storage - [Lotus.Storage](Lotus.Storage.md): Storage operations for Lotus queries. - [Lotus.Storage.Query](Lotus.Storage.Query.md): Represents a saved Lotus query. - [Lotus.Storage.QueryVariable](Lotus.Storage.QueryVariable.md): Represents a variable placeholder (`{{var}}`) used inside a Lotus query. - Query Execution - [Lotus.Preflight](Lotus.Preflight.md): SQL preflight authorization for Lotus. - [Lotus.Result](Lotus.Result.md): Represents the result of a SQL query execution. - [Lotus.Runner](Lotus.Runner.md): SQL execution with safety checks, param binding, and result shaping. - Data Export - [Lotus.Export](Lotus.Export.md): Export functionality for Lotus.Result to various formats. - [Lotus.Export.Value](Lotus.Export.Value.md): Value normalization for export formats. Handles various database types and edge cases for CSV and JSON export. - Data Sources - [Lotus.Source](Lotus.Source.md): Source behavior for database-specific operations. - [Lotus.Sources.Default](Lotus.Sources.Default.md): Default source adapter implementation for unsupported or unknown database sources. - Schema Introspection - [Lotus.Schema](Lotus.Schema.md): Schema introspection functionality for Lotus. - [Lotus.Visibility](Lotus.Visibility.md): Schema and table visibility filtering for Lotus. - Telemetry - [Lotus.Telemetry](Lotus.Telemetry.md): Telemetry events emitted by Lotus. - Caching - [Lotus.Cache](Lotus.Cache.md): Lotus cache facade. If no adapter configured, acts as a no-op pass-through. - [Lotus.Cache.Adapter](Lotus.Cache.Adapter.md): Behaviour specification for cache adapters in the Lotus framework. - [Lotus.Cache.Cachex](Lotus.Cache.Cachex.md): A Cachex-based, local or distributed, in-memory cache adapter for Lotus. - [Lotus.Cache.ETS](Lotus.Cache.ETS.md): An ETS-based, local, in-memory cache adapter for Lotus. - Database Migrations - [Lotus.Migration](Lotus.Migration.md): Migration behavior for database-specific migrations. - [Lotus.Migrations](Lotus.Migrations.md): Migration management system for Lotus. - [Lotus.Migrations.Postgres.V1](Lotus.Migrations.Postgres.V1.md): Initial table structure for Lotus queries on PostgreSQL. - [Lotus.Migrations.Postgres.V2](Lotus.Migrations.Postgres.V2.md): Add lotus_query_visualizations table for storing chart configs per query. - [Lotus.Migrations.Postgres.V3](Lotus.Migrations.Postgres.V3.md): Add dashboard tables for storing dashboard configurations, cards, filters, and mappings. - OTP Application - [Lotus.Supervisor](Lotus.Supervisor.md): Top-level supervisor for Lotus. - AI - [Lotus.AI](Lotus.AI.md): AI-powered query generation for Lotus. - [Lotus.AI.Action](Lotus.AI.Action.md): Behaviour for AI tool actions. - [Lotus.AI.Actions](Lotus.AI.Actions.md): Convenience module for AI actions. - [Lotus.AI.Actions.ExecuteSQL](Lotus.AI.Actions.ExecuteSQL.md): Executes a SQL query against a data source. - [Lotus.AI.Actions.GetColumnValues](Lotus.AI.Actions.GetColumnValues.md): Retrieves distinct values for a specific column. - [Lotus.AI.Actions.GetTableSchema](Lotus.AI.Actions.GetTableSchema.md): Retrieves column details for a specific table. - [Lotus.AI.Actions.ListDataSources](Lotus.AI.Actions.ListDataSources.md): Lists all available data sources (repositories). - [Lotus.AI.Actions.ListSchemas](Lotus.AI.Actions.ListSchemas.md): Lists all available database schemas. - [Lotus.AI.Actions.ListTables](Lotus.AI.Actions.ListTables.md): Lists all available tables in a database. - [Lotus.AI.Actions.ValidateSQL](Lotus.AI.Actions.ValidateSQL.md): Validates SQL syntax against the database without executing. - [Lotus.AI.Conversation](Lotus.AI.Conversation.md): Manages conversational state for AI-assisted query generation. - [Lotus.AI.QueryExplainer](Lotus.AI.QueryExplainer.md): Generates AI-powered plain-language explanations for SQL queries. - [Lotus.AI.QueryOptimizer](Lotus.AI.QueryOptimizer.md): Generates AI-powered optimization suggestions for SQL queries. - [Lotus.AI.SQLGenerator](Lotus.AI.SQLGenerator.md): Generates SQL from natural language using ReqLLM. - [Lotus.AI.Tool](Lotus.AI.Tool.md): Tool utilities for LLM interactions. - SQL Processing - [Lotus.SQL.Transformer](Lotus.SQL.Transformer.md): Transforms SQL queries for database-specific syntax compatibility. - Exceptions - [Lotus.AI.Error.AuthenticationError](Lotus.AI.Error.AuthenticationError.md): The AI provider rejected the request due to invalid or missing credentials. - [Lotus.AI.Error.RateLimitError](Lotus.AI.Error.RateLimitError.md): The AI provider rejected the request due to rate limits or quota. - [Lotus.AI.Error.ServerError](Lotus.AI.Error.ServerError.md): The AI provider returned a server-side error (5xx). - [Lotus.AI.Error.ServiceError](Lotus.AI.Error.ServiceError.md): Catch-all for unexpected AI service errors. - [Lotus.AI.Error.TimeoutError](Lotus.AI.Error.TimeoutError.md): The AI request timed out.