@spec aggregate_to_cql(atom(), atom() | nil) :: String.t()

Converts aggregate type and field to CQL aggregate expression.

@spec apply_base_filter(list(), term()) :: list()

Applies the base_filter from the resource DSL to the query filters.

The base_filter is prepended to the query filters so it is always applied.

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

Builds an aggregate CQL query.

Supports COUNT, SUM, AVG, MIN, MAX with optional GROUP BY.

Examples

build_aggregate_query("users", "COUNT(*) AS total", "WHERE status = ?", ["active"])
# => {"SELECT COUNT(*) AS total FROM users WHERE status = ?", ["active"]}

@spec build_contains_clause(String.t(), term(), :contains | :contains_key) ::
  {String.t(), list()}

Builds a CONTAINS clause for collection type filtering.

In CQL, CONTAINS is used to check if a collection column contains a value. CONTAINS KEY is used to check if a map column contains a key.

@spec build_group_by(list() | nil) :: {String.t(), list()}

Builds GROUP BY clause for aggregate queries.

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

Builds keyset pagination clause using TOKEN() function.

Keyset pagination is more efficient than OFFSET for large datasets. It uses the CQL TOKEN() function on partition keys to fetch pages.

Examples

# For a single partition key column:
build_keyset_clause(%{partition_keys: [:id], values: [last_id], direction: :after})
# => {"WHERE TOKEN(id) > TOKEN(?)", [last_id]}

# For composite partition keys:
build_keyset_clause(%{partition_keys: [:org_id, :id], values: [last_org, last_id], direction: :after})
# => {"WHERE TOKEN(org_id, id) > TOKEN(?, ?)", [last_org, last_id]}

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

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

Supports:

• Column selection (:select)
• DISTINCT on partition key columns
• Keyset pagination (:keyset)
• Aggregate queries (:aggregates)
• GROUP BY for aggregate queries
• Base filter from resource DSL
• Multiple ORDER BY columns
• IN queries with multiple values
• CONTAINS / CONTAINS KEY for collection types
• TOKEN() function for partition key queries

@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)
• Bare atoms (default to ASC)
• Maps with only :field key (default to ASC)

Supports multiple columns for compound ordering.

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

Builds WHERE clause from Ash 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.

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

Supports:

• Standard comparison operators: eq, not_eq, gt, gte, lt, lte
• IN with list values
• CONTAINS for collection type filtering
• CONTAINS KEY for map key filtering
• TOKEN() function for partition key queries
• EXISTS for existence checks
• AND/OR boolean combinations
• Nested expressions

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

Converts Ash filter expressions to CQL (bang version).

Raises ArgumentError on unknown filter expressions.