# Lotus v0.16.5 - 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.

