AshScylla.DataLayer.QueryBuilder (AshScylla v0.2.0)

Query building functions for AshScylla data layer.

Provides optimized query building with filter-to-CQL conversion, prepared statement support, and token-based pagination.

Secondary Index Support

When filtering on non-primary key columns, this module checks if a secondary index exists and generates appropriate CQL. ScyllaDB/Cassandra can use secondary indexes for equality checks (=) but not for range queries.

Summary

Functions

build_optimized_query(data_layer)

Builds an optimized CQL query from the data layer query struct.

build_order_by(sorts)

Builds ORDER BY clause from sort items.

build_where_clause(filters)

Builds WHERE clause from Ash filters.

can_use_secondary_index?(resource, filters)

Checks if a filter can use secondary indexes.

filter_to_cql(unknown)

Converts Ash filter expressions to CQL (safe version).

filter_to_cql!(filter)

Converts Ash filter expressions to CQL (bang version).

Functions

build_optimized_query(data_layer)

@spec build_optimized_query(AshScylla.DataLayer.t()) :: {String.t(), list()}

Builds an optimized CQL query from the data layer query struct.

If filters are on columns with secondary indexes, the query will use those indexes automatically.

build_order_by(sorts)

@spec build_order_by(list()) :: {String.t(), list()}

Builds ORDER BY clause from sort items.

Sort items can be:

Maps with :field and :direction keys
Tuples like {field, direction} (Ash standard format)

build_where_clause(filters)

@spec build_where_clause(list()) :: {String.t(), list()}

Builds WHERE clause from Ash filters.

can_use_secondary_index?(resource, filters)

@spec can_use_secondary_index?(term(), list()) :: {:ok, list()} | {:error, term()}

Checks if a filter can use secondary indexes.

Returns {:ok, indexed_columns} if the filter can use indexes, or {:error, reason} if it cannot.

filter_to_cql(unknown)

@spec filter_to_cql(term()) ::
  {String.t(), list()} | {:error, {:unknown_filter, term()}}

Converts Ash filter expressions to CQL (safe version).

Returns {cql, params} on success or {:error, {:unknown_filter, term()}} on failure.

filter_to_cql!(filter)

@spec filter_to_cql!(term()) :: {String.t(), list()}

Converts Ash filter expressions to CQL (bang version).

Raises ArgumentError on unknown filter expressions.