@spec create_post_fields_cql(String.t()) :: String.t()

Returns the CQL statement to create the search_post_fields table.

Stores the raw analyzed text per field for each post. Used during updates to diff old vs new terms and compute additions/removals.

@spec create_post_terms_cql(String.t()) :: String.t()

Returns the CQL statement to create the search_post_terms table.

This is the primary inverted index table. Each row maps a term to a post_id with term frequency for ranking.

Partition key: (term, shard) to avoid hotspot partitions for common terms. Clustering key: post_id for ordered retrieval.

@spec create_tables(module(), String.t()) :: :ok | {:error, term()}

Creates all search engine tables in the given keyspace.

Returns :ok on success or {:error, reason} on failure.

@spec drop_tables(module(), String.t()) :: :ok | {:error, term()}

Drops all search engine tables from the given keyspace.

Returns :ok on success or {:error, reason} on failure.

@spec shard_for(String.t(), non_neg_integer()) :: non_neg_integer()

Computes the shard number for a given term.

Uses :erlang.phash2/2 to distribute terms across the configured number of shards. This prevents hotspot partitions for high-frequency terms.