Cinder.QueryBuilder (Cinder v0.3.0)

View Source

Query 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.

Gets the current sort direction for a given key.

Toggles sort direction for a given key in the sort specification.

Types

column()

@type column() :: %{
  field: String.t(),
  filterable: boolean(),
  filter_type: atom(),
  filter_fn: function() | nil,
  sort_fn: function() | nil
}

filter()

@type filter() :: %{type: atom(), value: any(), operator: atom()}

filters()

@type filters() :: %{required(String.t()) => filter()}

query_opts()

@type query_opts() :: keyword()

sort_by()

@type sort_by() :: [{String.t(), :asc | :desc}]

Functions

apply_filters(query, filters, columns)

Applies filters to an Ash query based on filter configuration and column definitions.

apply_query_opts(query, opts)

Applies query options like load and select to an Ash query.

apply_sorting(query, sort_by, columns)

Applies sorting to an Ash query based on sort specifications and column definitions.

apply_standard_filter(query, key, filter_config, column)

Applies standard filters by delegating to the appropriate filter module.

build_and_execute(resource, options)

Builds a complete query with filters, sorting, and pagination.

Parameters

  • resource: The Ash resource to query
  • options: 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

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}

build_error_page_info()

Builds error pagination info for failed queries.

build_expression_sort(key)

Builds expression sort for relationship fields using dot notation.

build_page_info_with_total_count(results, current_page, page_size, total_count)

Builds pagination info from query results and total count.

get_sort_direction(sort_by, key)

Gets the current sort direction for a given key.

toggle_sort_direction(current_sort, key)

Toggles sort direction for a given key in the sort specification.

Cycles through: none → ascending → descending → none