nevaberry Apache Cassandra Knowledge Patch
Use this skill when writing, reviewing, upgrading, or operating Apache Cassandra code, CQL, configuration, and tooling. Start with the compatibility-sensitive items below, then load the topic reference that matches the task.
How to apply this skill
- Identify the Cassandra version, SSTable format, index implementations, Java runtime, and whether the cluster is in a mixed-version state.
- For upgrades, check changed validation, authorization, command-line options, virtual-table representations, and operational defaults before changing automation.
- For query or storage correctness, identify whether SAI, legacy secondary indexes, BTI, static columns, tombstones, repair, or descending clustering order is involved.
- For operations, verify gossip, token metadata, disk guardrails, repair scheduling, and JMX visibility against live cluster state.
- Treat compatibility fallbacks as safeguards, not as reasons to postpone format upgrades or mixed-version completion.
Reference index
| Reference | Topics |
|---|---|
| Operations, topology, and repair | Gossip, token metadata, hints, bootstrap, JMX, failure detection, streaming, guardrails, and AutoRepair |
| Protocols and tooling | Native protocol, serialization, cqlsh, nodetool, build tooling, Java, FQL, and CQLSSTableWriter |
| Queries, schema, and indexing | CQL behavior, schema, SAI, legacy secondary indexes, filtering, clustering order, and index lifecycle |
| Security and configuration | Authorization, identities, audit logging, password handling, YAML, virtual settings, and extensions |
| Storage and data path | SSTables, compaction, commitlog, snapshots, caches, deletion reconciliation, and disk sizing |
Breaking and behavior-sensitive changes
Update nodetool import automation
The short option for nodetool import --copy-data is -cd. Replace scripts
that use the conflicting -p form.
nodetool import -cd keyspace_name table_name /path/to/sstables
Expect tighter authorization
Operations that previously crossed DC, authorizer, or system-keyspace boundaries may now be rejected. A non-superuser also cannot bind an identity to a superuser. Test provisioning and role-management flows with their real service accounts.
Password changes are rate-limited. Rotation automation should back off instead of assuming rapid repeated changes will succeed.
Do not depend on tool environment side effects
nodetool and related tools avoid sourcing cassandra-env.sh when it is not
needed. Put required settings in supported tool configuration or the caller's
environment instead of relying on incidental script side effects.
Parse virtual settings defensively
Complex values in system_views.settings are JSON, sensitive values are
redacted, previously omitted settings are visible, and mappings may contain
non-string keys. Inventory consumers must handle all four conditions without
expecting secrets.
Revalidate schema and snapshot names
Long table names that would exceed filesystem filename limits are rejected. Snapshot operations also reject invalid snapshot names, while valid snapshot directory names that older SSTable path checks rejected are accepted. Keep identifier generation within Cassandra's validation rules.
Recheck type compatibility
BytesType compatibility applies only to scalar types. Schema migration tools
must not assume it is compatible with collections or other non-scalar types.
Plan around mixed-version safeguards
The automated repair scheduler stops when it detects two Cassandra major versions. Mixed-version upgrades need an explicit repair plan and monitoring; do not assume scheduled repairs remain active.
Operations quick reference
Check topology consistency
Use the token-metadata check when gossip state and ownership appear inconsistent.
nodetool checktokenmetadata
Restarted nodes are protected from delayed shutdown gossip, and multi-field endpoint updates converge correctly. Still compare gossip, token metadata, and the node's current lifecycle state before taking topology action.
Configure and observe AutoRepair
Built-in AutoRepair provides in-process scheduling, a minimum task-duration
setting, preview_repaired, disk protection for full repair, and reporting of
expected versus actual bytes and keyspaces. Parallel repair counts greater than
one are supported. Monitor the scheduler and account for its mixed-major-version
shutdown behavior.
Inspect guardrails
Use the guardrail commands instead of scraping configuration indirectly.
nodetool getguardrailsconfig
The disk-usage guardrail can be disabled after it trips, and first boot works
when data_disk_usage_max_disk_size is set before the data directory exists.
Recalibrate corrected metrics
nodetool gcstats reports direct memory correctly, and nodetool tablestats
includes selected SAI state and query-performance details. Alert thresholds may
need adjustment after an upgrade.
Query and indexing quick reference
Define descending complex clustering keys
Frozen UDTs and vectors can be descending clustering keys. Snapshot schema CQL also carries the required UDT definitions.
CREATE TYPE coordinates (x int, y int);
CREATE TABLE samples (
sensor_id uuid,
position frozen<coordinates>,
embedding vector<float, 3>,
PRIMARY KEY (sensor_id, position, embedding)
) WITH CLUSTERING ORDER BY (position DESC, embedding DESC);
Account for index selection and lifecycle
When a column has both a legacy secondary index and SAI, Cassandra prioritizes the legacy index. SAI availability after restart, writer switches, repair flushes, segment checksum validation, ANN score ordering, and distributed static-column tombstones all have correctness-sensitive handling described in the indexing reference.
Validate filtering edge cases
Correct behavior covers descending min/max, numeric range intersections,
unresolved static rows, static-column SAI queries, composite map filters,
repaired intersection matches, and reads after column deletion. Use targeted
regression tests when an application depends on these cases.
Storage quick reference
Size compaction using compressed estimates
Free-space admission checks use each table's estimated compressed size. Unified Compaction also validates minimum and target size combinations. Review disk headroom and reject invalid compaction settings before rollout.
Preserve deletion semantics
Complex collection deletions, reconciliation-required deletions, deterministic TTL updates, and expired-row index notifications all avoid earlier data or index divergence paths. Do not recreate older client-side workarounds that discard tombstone or reconciliation information.
Handle damaged or legacy storage safely
Compaction marks corrupt SSTables suspected and releases buffer-pool resources; commitlog recovery skips CRC-damaged sync blocks correctly. Legacy Bloom-filter SSTables fall back from zero-copy streaming, and pre-table-ID snapshot schemas can be loaded.
Configuration and tooling quick reference
Validate configuration before startup
Audit logging options are sanitized and validated during startup. The default YAML's optional settings remain parseable when uncommented, and reflectively loaded extensions are type-checked before initialization.
Batchlog endpoint selection accepts random_remote, prefer_local,
dynamic_remote, and dynamic.
batchlog_endpoint_strategy: dynamic_remote
Use supported runtimes and build paths
The server fully supports Java 17. cqlsh supports Python 3.12 and 3.13,
cassandra-stress negotiates TLS 1.3 automatically, source distributions build
with ant artifacts, and documentation generation does not require Go.
ant artifacts
Use current writer capabilities
CQLSSTableWriter can notify clients when it emits an SSTable, choose BTI or
Big format, and serialize vectors containing date or time values. Choose
formats deliberately and attach production callbacks before bulk generation.