@spec can_run?(Lotus.Storage.Query.t(), opts()) :: boolean()

Checks if a query can be run with the provided variables.

Returns true if all required variables have values (either from defaults or supplied vars), false otherwise.

Examples

# Query with all required variables having defaults
Lotus.can_run?(query)
# => true

# Query missing required variables
Lotus.can_run?(query)
# => false

# Query with runtime variable overrides
Lotus.can_run?(query, vars: %{"user_id" => 123})
# => true (if user_id was the missing variable)

Creates a new dashboard.

Creates a new card for a dashboard.

Creates a new filter for a dashboard.

Creates a filter mapping connecting a dashboard filter to a card's query variable.

Creates a new saved query.

Creates a new visualization for a query.

Returns all configured data sources.

Returns the default data source as a {name, module} tuple.

• If there's only one data source configured, returns it
• If multiple sources are configured and default_source is set, returns that source
• If multiple sources are configured without default_source, raises an error
• If no data sources are configured, raises an error

Deletes a dashboard.

Deletes a card.

Deletes a filter.

Deletes a filter mapping.

Deletes a saved query.

Deletes a visualization (by struct or id).

Describes a specific table, returning its column definitions.

Options

• :context — opaque value threaded into the :after_describe_table and :after_discover middleware events.
• :scope — opaque value passed to the visibility resolver and hashed into the cache key. See Lotus.Visibility.Resolver.

Examples

{:ok, columns} = Lotus.describe_table("primary", "users")
{:ok, columns} = Lotus.describe_table("postgres", "customers", schema: "reporting")
{:ok, columns} = Lotus.describe_table(MyApp.DataRepo, "products", search_path: "analytics, public")

Disables public sharing for a dashboard.

Enables public sharing for a dashboard by generating a unique token.

Gets a single dashboard by ID. Returns nil if not found.

Gets a single dashboard by ID. Raises if not found.

Gets a dashboard by its public sharing token.

Gets a single card by ID. Returns nil if not found.

Options

• :preload - A list of associations to preload

Gets a single card by ID. Raises if not found.

Options

• :preload - A list of associations to preload

Gets a single filter by ID. Returns nil if not found.

Gets a single filter by ID. Raises if not found.

Gets a data source by name.

Raises if the source is not configured.

Gets a single query by ID. Returns nil if not found.

Gets a single query by ID. Raises if not found.

Gets statistics for a specific table.

Examples

{:ok, stats} = Lotus.get_table_stats("primary", "users")
{:ok, stats} = Lotus.get_table_stats("postgres", "customers", schema: "reporting")
# Returns %{row_count: 1234}

Invalidates all cached discovery entries associated with the given scope.

Uses tag-based invalidation — each scoped cache entry is tagged with a scope digest, so this clears only entries for the specified scope without flushing the entire cache.

Examples

:ok = Lotus.invalidate_scope(%{tenant_id: 42})
:ok = Lotus.invalidate_scope(%{role: :admin})

Lists all filter mappings for a card.

Lists all cards for a dashboard.

Options

• :preload - A list of associations to preload (e.g., [:query, :filter_mappings])

Lists all filters for a dashboard.

Lists all dashboards.

Options

• :preload - A list of associations to preload (e.g., [:cards])

Lists dashboards with optional filtering.

Options

• :search - Search term to match against dashboard names

Lists the names of all configured data sources.

Useful for building UI dropdowns.

Lists all saved queries.

Lists all relations (tables with column information) in a data repository.

Options

• :context — opaque value threaded into the :after_list_relations and :after_discover middleware events.
• :scope — opaque value passed to the visibility resolver and hashed into the cache key. See Lotus.Visibility.Resolver.

Examples

{:ok, relations} = Lotus.list_relations("postgres", search_path: "reporting, public")
# Returns [{"reporting", "customers"}, {"public", "users"}, ...]

Lists all schemas in the given repository.

Returns a list of schema names. For databases without schemas (like SQLite), returns an empty list.

Options

• :context — opaque value threaded into the :after_list_schemas and :after_discover middleware events.
• :scope — opaque value passed to the visibility resolver and hashed into the cache key. See Lotus.Visibility.Resolver.

Examples

{:ok, schemas} = Lotus.list_schemas("postgres")
# Returns ["public", "reporting", ...]

{:ok, schemas} = Lotus.list_schemas("sqlite")
# Returns []

Lists all tables in a data repository.

For databases with schemas (PostgreSQL), returns {schema, table} tuples. For databases without schemas (SQLite), returns just table names as strings.

Options

• :context — opaque value threaded into the :after_list_tables and :after_discover middleware events. See Lotus.Middleware.
• :scope — opaque value passed to the visibility resolver and hashed into the cache key. Different scopes produce independent cached entries. See Lotus.Visibility.Resolver.

Examples

{:ok, tables} = Lotus.list_tables("postgres")
# Returns [{"public", "users"}, {"public", "posts"}, ...]

{:ok, tables} = Lotus.list_tables("postgres", search_path: "reporting, public")
# Returns [{"reporting", "customers"}, {"public", "users"}, ...]

{:ok, tables} = Lotus.list_tables("sqlite")
# Returns ["products", "orders", "order_items"]

{:ok, tables} = Lotus.list_tables("postgres", context: %{tenant: "acme"})
# Middleware sees `%{tenant: "acme"}` in the payload

{:ok, tables} = Lotus.list_tables("postgres", scope: %{role: :admin})
# Visibility resolver receives scope; result cached separately per scope

Lists all visualizations for a query.

Returns visualizations ordered by position, then by id.

Reorders cards in a dashboard.

Returns the configured Ecto repository where Lotus stores query definitions.

Runs all query cards in a dashboard and returns their results.

Returns a map of card IDs to their results.

Options

• :filter_values - Map of filter names to their current values
• :parallel - Whether to run cards in parallel (default: true)
• :timeout - Timeout per card in milliseconds (default: 30000)

Runs a single dashboard card and returns its result.

Options

• :filter_values - Map of filter names to their current values
• :timeout - Query timeout in milliseconds

@spec run_query(Lotus.Storage.Query.t() | term(), opts()) ::
  {:ok, Lotus.Result.t()} | {:error, term()}

Run a saved query (by struct or id).

Variables in the query statement (using {{variable_name}} syntax) are substituted with values from the query's default variables and any runtime overrides provided via the vars option.

Variable Resolution

Variables are resolved in this order:

1. Runtime values from vars option (highest priority)
2. Default values from the query's variable definitions
3. If neither exists, raises an error for missing required variable

Examples

# Run query with default variable values
Lotus.run_query(query)

# Override variables at runtime
Lotus.run_query(query, vars: %{"min_age" => 25, "status" => "active"})

# Run with timeout and repo options
Lotus.run_query(query, timeout: 10_000, repo: MyApp.DataRepo)

# Run by query ID
Lotus.run_query(query_id, vars: %{"user_id" => 123})

Variable Types

Variables are automatically cast based on their type definition:

• :text - Used as-is (strings)
• :number - Cast from string to integer
• :date - Cast from ISO8601 string to Date struct

Windowed pagination

Pass window: [limit: pos_integer, offset: non_neg_integer, count: :none | :exact] to return only a page of rows from the original query. When count: :exact, Lotus will also compute SELECT COUNT(*) FROM (original_sql) and include meta.total_count in the result. The num_rows field always reflects the number of rows in the returned page.

@spec run_statement(
  Lotus.Query.Statement.body(),
  Lotus.Query.Statement.params(),
  opts()
) ::
  {:ok, Lotus.Result.t()} | {:error, term()}

Run an ad-hoc statement (bypassing storage), read-only by default and sandboxed.

The statement is the adapter-native payload: SQL text for Ecto-backed sources, a decoded JSON object or DSL term for others.

Options

• :read_only — when true (default), blocks write operations (INSERT, UPDATE, DELETE, DDL) at both the application and database level. Set to false to allow write queries.

Examples

# Run against default configured repo
{:ok, result} = Lotus.run_statement("SELECT * FROM users")

# Run against specific repo
{:ok, result} = Lotus.run_statement("SELECT * FROM products", [], repo: MyApp.DataRepo)

# With parameters
{:ok, result} = Lotus.run_statement("SELECT * FROM users WHERE id = $1", [123])

# With search_path for schema resolution
{:ok, result} = Lotus.run_statement("SELECT * FROM users", [], search_path: "reporting, public")

# Allow write queries (development use)
{:ok, result} = Lotus.run_statement(
  "INSERT INTO notes (body) VALUES ($1)",
  ["hello"],
  read_only: false
)

Windowed pagination

Pass window: [limit: pos_integer, offset: non_neg_integer, count: :none | :exact] to page results from the statement. See run_query/2 for details. The cache key automatically incorporates the window so different pages are cached independently.

Returns whether unique query names are enforced.

Updates an existing dashboard.

Updates a card.

Updates a filter.

Updates an existing query.

Updates an existing visualization.

Validates a visualization config against query results.

Checks that all referenced fields exist in the result columns and that numeric aggregations (sum, avg) are applied only to numeric columns.

Returns the current version of Lotus.