Cinder.QueryBuilder (Cinder v0.5.0)
View SourceQuery building functionality for Cinder table components.
Handles the construction of Ash queries with filters, sorting, and pagination for table data loading.
Summary
Functions
Applies filters to an Ash query based on filter configuration and column definitions.
Applies query options like load and select to an Ash query.
Applies sorting to an Ash query based on sort specifications and column definitions.
Applies standard filters by delegating to the appropriate filter module.
Builds a complete query with filters, sorting, and pagination.
Builds error pagination info for failed queries.
Builds expression sort for relationship fields using dot notation.
Builds pagination info from query results and total count.
Extracts sort information from an Ash query for table UI initialization.
Gets the current sort direction for a given key.
Toggles sort direction for a given key in the sort specification.
Toggles sort direction with special handling for query-extracted sorts.
Types
Functions
Applies filters to an Ash query based on filter configuration and column definitions.
Applies query options like load and select to an Ash query.
Applies sorting to an Ash query based on sort specifications and column definitions.
Applies standard filters by delegating to the appropriate filter module.
Builds a complete query with filters, sorting, and pagination.
Parameters
resource
: The Ash resource to queryoptions
: Query building options including::actor
- The current user/actor:filters
- Filter map:sort_by
- Sort specifications:page_size
- Number of records per page:current_page
- Current page number:columns
- Column definitions:query_opts
- Additional Ash query and execution options
Supported Query Options
The :query_opts
parameter accepts both query building and execution options:
Query Building Options
:select
- Select specific attributes (handled byAsh.Query.select/2
):load
- Load relationships and calculations (handled byAsh.Query.load/2
)
Execution Options
These options are passed to both Ash.Query.for_read/3
and Ash.read/2
:
:timeout
- Query timeout in milliseconds or:infinity
(e.g.,:timer.seconds(30)
):authorize?
- Whether to run authorization during query execution:max_concurrency
- Maximum number of processes for parallel loading
Usage Examples
# Simple timeout for long-running queries
query_opts: [timeout: :timer.seconds(30)]
# Query building options
query_opts: [select: [:name, :email], load: [:posts]]
# Combined query building and execution options
query_opts: [
timeout: :timer.seconds(20),
authorize?: false,
select: [:title, :content],
load: [:author, :comments]
]
Returns
A tuple {:ok, {results, page_info}}
or {:error, reason}
Builds error pagination info for failed queries.
Builds expression sort for relationship fields using dot notation.
Builds pagination info from query results and total count.
Extracts sort information from an Ash query for table UI initialization.
Takes an Ash query and returns sort information in the format expected by
the table component: [{field_name, direction}]
Parameters
query
- An Ash.Query struct or resource modulecolumns
- Column definitions to map query sorts to table fields
Returns
A list of {field_name, direction}
tuples where:
field_name
is a string matching table column field namesdirection
is:asc
or:desc
Examples
# Query with sorts
query = User |> Ash.Query.for_read(:read) |> Ash.Query.sort([{:name, :desc}, {:created_at, :asc}])
extract_query_sorts(query, columns)
# => [{"name", :desc}, {"created_at", :asc}]
# Resource module (no sorts)
extract_query_sorts(User, columns)
# => []
Gets the current sort direction for a given key.
Toggles sort direction for a given key in the sort specification.
Provides a predictable three-step cycle:
- none → ascending → descending → none
When starting with extracted query sorts, use toggle_sort_from_query/2
for better UX that handles the transition from query state to user control.
Toggles sort direction with special handling for query-extracted sorts.
When a column has a sort from query extraction, the first user click provides intuitive behavior:
- desc (from query) → asc (user takes control)
- asc (from query) → desc (user takes control) Then follows normal toggle cycle.
This provides better UX when tables start with pre-sorted queries.