Hyper-Converged Database (HCD) guardrails

Hyper-Converged Database (HCD) is a self-managed database powered by Apache Cassandra®, an open-source NoSQL distributed database. To ensure high availability and optimum performance, HCD has guardrails on underlying Cassandra functionality. These guardrails prevent configurations that could negatively impact performance or availability.

You can configure most of these settings in cassandra.yaml.

Startup warnings and failures

HCD issues warnings or prevents startup for certain configurations to maintain optimal performance and compatibility.

Startup warnings

The following configurations generate warnings at startup:

Startup warnings for HCD
Parameter	Configuration location	Warns when
Non-murmur3 partitioner	`cassandra.yaml`: `partitioner` property	You use a partitioner other than murmur3.
JBOD (multiple data directories)	`cassandra.yaml`: `data_file_directories` property	You configure multiple data directories. DataStax recommends using striped LVM instead.
Non-BTI SSTable format	Automatically configured by HCD	You don’t use BTI SSTable format type. This is automatically configured by HCD and cannot be changed in the `cassandra.yaml` file.
Materialized views enabled	`cassandra.yaml` - `materialized_views_enabled` property	You set `materialized_views_enabled: true` in configuration.
SASI indexes enabled	`cassandra.yaml` - `enable_sasi_indexes` property (removed in HCD 2.0)	Migrating or upgrading from an earlier version where SASI indexes were supported. HCD doesn’t support SASI indexes. Remove any `enable_sasi_indexes` entry from `cassandra.yaml` and switch to SAI indexes.
COMPACT STORAGE tables	Table-level setting	COMPACT STORAGE tables are present in the database. This is a table-level setting, not a `cassandra.yaml` configuration.
COMPACT STORAGE table dropping enabled	`cassandra.yaml` - `drop_compact_storage_enabled` property	You enable the ability to drop COMPACT STORAGE tables. Instead, you must manually migrate such tables.
Legacy secondary indexes	Table-level setting and `cassandra.yaml` - `secondary_indexes_per_table_fail_threshold`	You enable legacy secondary indexes or if any tables use them. This is a table-level setting and a `cassandra.yaml` configuration. In `cassandra.yaml`, set `secondary_indexes_per_table_fail_threshold` to 0 to disable this warning.
High tombstone failure threshold	`cassandra.yaml` - `tombstone_failure_threshold` property	You set `tombstone_failure_threshold` higher than 100,000.
High batch size failure threshold	`cassandra.yaml` - `batch_size_fail_threshold` property	You set `batch_size_fail_threshold` higher than `50KiB`.

Startup failures

The following configurations cause HCD to fail to start:

Startup failures for HCD
Configuration	Description
Transient replication	HCD will fail to start if transient replication is enabled.

Limited functions and configurations

The following table lists specific limitations and configurations for HCD:

Guardrails for HCD
Parameter	Limit	Notes
Large partition	Warning	Issues a warning when reading or compacting a partition that exceeds 100 MB.
Page size	Fixed	HCD configures the proper page size automatically.
User-defined functions (UDFs) and user-defined aggregate functions (UDAs)	Disabled	HCD supports UDFs and UDAs, but you must enable them in the `cassandra.yaml` file.
List operations	Enabled	Read-before-write operations for lists are enabled by default. Configured with `read_before_write_list_operations_enabled: true`.

Guardrails configuration

The following tables list the default guardrail thresholds by category:

Warning thresholds

Warning thresholds for HCD
Guardrail parameter	Default threshold	Warns when
`tombstone_warn_threshold`	1000	The tombstone count exceeds this threshold.
`partition_size_warn_threshold`	100MiB	The partition size exceeds 100 MiB.
`batch_size_warn_threshold`	5KiB	The batch size exceeds 5 KiB.
`unlogged_batch_across_partitions_warn_threshold`	10	The unlogged batch spans more than 10 partitions.
`vector_dimensions_warn_threshold`	-1 (unlimited)	The vector dimensions exceed the threshold.
`collection_size_warn_threshold`	10MiB	The collection size exceeds 10 MiB.
`items_per_collection_warn_threshold`	200	The number of items per collection exceeds 200.
`tables_warn_threshold`	100	The number of tables exceeds 100.
`offset_rows_warn_threshold`	10000	The `OFFSET` exceeds 10,000 rows.
`data_disk_usage_percentage_warn_threshold`	70	The disk usage percentage exceeds 70%.

Failure thresholds

Failure thresholds for HCD
Guardrail parameter	Default threshold	Fails when
`column_value_size_fail_threshold`	-1 (unlimited)	The column value size exceeds the threshold.
`columns_per_table_fail_threshold`	200	The number of columns per table exceeds 200.
`fields_per_udt_fail_threshold`	100	The number of fields per UDT exceeds 100.
`vector_dimensions_fail_threshold`	8192	The vector dimensions exceed 8192.
`secondary_indexes_per_table_fail_threshold`	0	Any secondary indexes are created (not allowed).
`sai_indexes_per_table_fail_threshold`	10	The number of SAI indexes per table exceeds 10.
`sai_indexes_total_fail_threshold`	100	The total number of SAI indexes exceeds 100.
`sasi_indexes_per_table_failure_threshold`	0	Any SASI indexes are created (not allowed).
`sai_ann_rerank_k_fail_threshold`	4000	The SAI ANN rerank K value exceeds 4000.
`materialized_views_per_table_fail_threshold`	0	Any materialized views are created (not allowed).
`tables_fail_threshold`	200	The number of tables exceeds 200.
`page_size_fail_threshold`	-1 (unlimited)	The page size exceeds the threshold.
`in_select_cartesian_product_fail_threshold`	25	The IN clause creates a Cartesian product exceeding 25.
`partition_keys_in_select_fail_threshold`	20	The number of partition keys in SELECT exceeds 20.
`data_disk_usage_percentage_fail_threshold`	-1 (unlimited)	The disk usage percentage exceeds the threshold.
`data_disk_usage_max_disk_size`	-1 (unlimited)	The disk usage exceeds the maximum disk size threshold.
`offset_rows_failure_threshold`	20000	The `OFFSET` exceeds 20,000 rows.
`query_filters_warn_threshold`	-1 (unlimited)	The number of query filters exceeds the warn threshold.
`query_filters_fail_threshold`	-1 (unlimited)	The number of query filters exceeds the fail threshold.
`write_consistency_levels_disallowed`	ANY	Disallows any write consistency level.