C3 AI Documentation Home

Cassandra Database

Cassandra is the key-value (KV) store that the C3 Agentic AI Platform uses by default in shared environments (SE) and in single node environments with a shared database. A KV store saves each record under a key and serves large volumes of reads and writes by key. Types that persist to the KV datastore, such as normalized time series, store their data in the KV store of the environment. A single node environment uses SqlKvStore instead, unless it requests Cassandra or uses a shared database.

Cassandra and the other platform datastores

The platform keeps KV data and relational data in separate datastores. The following table shows where Cassandra fits:

DatastoreKindWhen the platform uses it
CassandraKV storeThe default KV store for shared environments (SE) and single node environments with a shared database
PostgreSQLSQL storeRelational data for Types that persist to the SQL datastore
H2SQL storeThe SQL store of a single node environment, unless the environment requests PostgreSQL. The platform runs H2 in PostgreSQL compatibility mode.

The platform also supports other KV stores and file system storage. To compare these options with Cassandra and choose one, see Specify a KV Store.

When to use Cassandra

Cassandra suits data with the following characteristics:

  • Heavy volume: Large data loads, such as high-frequency sensor readings.
  • Time series: Time-stamped data points that the platform normalizes and reads by time range.
  • High availability: Cassandra keeps running through automatic failover. By default, the platform stores three replicas of each record (replicationFactor is 3).
  • Eventual consistency: Cassandra prioritizes availability. Replicas can differ briefly after a write and then converge.
  • Flexible schema: Cassandra applies schema changes without downtime.

Choose a SQL store instead when your data is relational and needs transactions with immediate consistency.

How the platform normalizes time series data

Normalization turns raw time series data points into evenly spaced intervals that the platform can read and aggregate. The platform runs the same normalization pipeline whether the raw data is in Cassandra, in another KV store, or in a SQL store. The platform stores the normalized time series in the KV datastore, which is Cassandra by default.

flowchart LR A[Read raw time series] --> B[Clean and sort] B --> C[De-duplicate] C --> D[Resolve overlaps] D --> E[Detect interval] E --> F[Interpolate] F --> G[Align to interval] G --> H[Store normalized time series]

The pipeline runs the following stages:

  1. Read raw time series: The platform reads the raw data points.
  2. Clean and sort: The platform rejects points with no value, points whose start and end are more than 50 years apart, and points more than 50 years in the past or future. The platform also orders the points by time.
  3. De-duplicate: TimedDataFields#duplicateHandling controls exact duplicates. The values are IGNORE and KEEP, and the default is IGNORE.
  4. Resolve overlaps: TimedDataFields#overlapHandling controls overlapping measurements. The values are SUM, AVG, MIN, and MAX, and the default is AVG.
  5. Detect interval: When you do not set the interval, the platform detects it from the first 100 raw data points. To set the interval yourself, use TimedDataFields#interval. The finest interval that the platform detects is QUARTER_HOUR.
  6. Interpolate: TimedDataFields#interpolator fills missing data points. The values are LINEAR_INTERPOLATOR and ZERO_INTERPOLATOR, and the default is ZERO_INTERPOLATOR.
  7. Align to interval: The treatment parameter of the Ann.Ts annotation controls how the platform combines values into each interval. See AggOp for the treatment values.
  8. Store normalized time series: The platform writes the normalized data points.

Configure how Cassandra stores time series data

Two settings control how Cassandra stores normalized time series data, including when data moves from hot storage to cold storage.

SettingDescriptionDefault value
TimedDataFields#bucketIntervalTime interval that groups normalized time series values into buckets to optimize readsMONTH
NormalizationConfig#partitionStrategyMap from a data point Type, or ALL, to a NormalizationPartitionStrategy that defines when data moves from hot storage to cold storageALL: data older than six months moves to cold storage

Use hot/cold storage for high-volume time series

Hot/cold storage separates data by how often you read it. Hot storage holds low-volume, frequently read data. Cold storage holds heavy-volume, less frequently read data, such as the history of a time series.

Use hot/cold storage when most queries read recent data and you must keep older data. To change when data moves to cold storage, set the partitionStrategy setting of NormalizationConfig.

To learn more about hot/cold storage for time series data, see the "Hot/cold normalized storage" section in Understand Normalization.

See also

Was this page helpful?