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 databases have guardrails on underlying Cassandra functionality. These guardrails prevent configurations that could negatively impact performance or availability.

To configure guardrails, see Guardrails configuration.

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 databases
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 `cassandra.yaml`.
Materialized views enabled	`cassandra.yaml` - `enable_materialized_views` property	You set `enable_materialized_views: true` in configuration.
SASI indexes enabled	`cassandra.yaml` - `enable_sasi_indexes` property	You set `enable_sasi_indexes: true`. You must 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_index_per_table_failure_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_index_per_table_failure_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_in_kb` property	You set `batch_size_fail_threshold_in_kb` higher than 640 KB.

Startup failures

The following configurations cause HCD to fail to start:

Startup failures for HCD databases
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 databases:

Guardrails for HCD databases
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 databases
Guardrail parameter	Default threshold	Warns when
`tombstone_warn_threshold`	1000	The tombstone count exceeds this threshold.
`partition_size_warn_threshold_in_mb`	100	The partition size exceeds 100 MB.
`batch_size_warn_threshold_in_kb`	64	The batch size exceeds 64 KB.
`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_in_kb`	10240	The collection size exceeds 10,240 KB (10 MB).
`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.
`disk_usage_percentage_warn_threshold`	70	The disk usage percentage exceeds 70%.

Failure thresholds

Failure thresholds for HCD databases
Guardrail parameter	Default threshold	Fails when
`column_value_size_failure_threshold_in_kb`	-1 (unlimited)	The column value size exceeds the threshold.
`columns_per_table_failure_threshold`	200	The number of columns per table exceeds 200.
`fields_per_udt_failure_threshold`	100	The number of fields per UDT exceeds 100.
`vector_dimensions_failure_threshold`	8192	The vector dimensions exceed 8192.
`secondary_index_per_table_failure_threshold`	0	Any secondary indexes are created (not allowed).
`sai_indexes_per_table_failure_threshold`	10	The number of SAI indexes per table exceeds 10.
`sai_indexes_total_failure_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_view_per_table_failure_threshold`	0	Any materialized views are created (not allowed).
`tables_failure_threshold`	200	The number of tables exceeds 200.
`page_size_failure_threshold_in_kb`	-1 (unlimited)	The page size exceeds the threshold.
`in_select_cartesian_product_failure_threshold`	25	The IN clause creates a Cartesian product exceeding 25.
`partition_keys_in_select_failure_threshold`	20	The number of partition keys in SELECT exceeds 20.
`disk_usage_percentage_failure_threshold`	-1 (unlimited)	The disk usage percentage exceeds the threshold.
`disk_usage_max_disk_size_in_gb`	-1 (unlimited)	The disk usage exceeds the maximum disk size threshold in GB.
`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.