Glossary

Here's the list of "terms" that people working with ScyllaDB use in everyday work. Only useful for newbies who need to get a quick up-to-speed kick and start reading more docs/code.

Node: a node

vNode: a virtual part of the node

Ring: all nodes from a cluster are interconnected as a virtual ring

Coordinator: the node a client is connected to. It serves client’s request and may talk to other nodes, as data may be in partition belonging to some other node

Replica: other nodes in the cluster with respect to coordinator. Requests are usually spread between one or more replicas and then collected back on coordinator to create response to the client

Keyspace: analogue of a “database” in rdbm

Column family: analogue of a “table” in rdbm. The column family is created by the client inside a keyspace and is described as a set of columns, some of which are marked as primary keys. Data stored in a column family forms a set of rows

Column: a portion of data in a row. It’s the “name:value” pair where name is the column name set during column family creation

Row: a set of columns associated with a particular primary key. Some columns may be missing (i.o.w. contain no data), see mutation for details

Primary key: a tuple of columns marked by client as such. The key value is used to uniquely identify the row in its column family. Several (at least one) first columns in the key are called the partition key, the rest (if any) -- the cluster key

Partition key: defines a partition in which the row is stored (see token below)

Cluster key: forces the rows to be sorted by the respective column’s values when stored

When requesting a row one must specify the full partition key and may specify parts of the cluster key. No other columns may take part in the request. As rows are sorted by cluster key the request is served in an efficient manner without scanning the whole partition.

Token: a value (hash) calculated from partition key that defines a partition on which the row is stored

Token range: a subset of tokens, usually a union of non-overlapping [X:Y) intervals. Each vnode in a cluster and each shard on a respective node are responsible for some range

Partition: a set of rows with equal token. A partition is directly mapped into a vnode (and thus to node) using token ranges. The partition (i.e. -- the rows from it) is stored on the target node and is replicated on some more according to replication strategy

Shard: a part of a node in a computational sense. Usually it’s a thread bound to a CPU and a memory region that serves a part of the node’s token range (this part is naturally a token range too)

Replication strategy: the rule by which partitions are duplicated across nodes. Typical strategy is -- RF nodes clockwise (nodes are in a ring)

Replication factor (RF): the number of copies a partition must have on the cluster

Consistency level (CL): the number of nodes that must ack the IO request before it’s acknowledged to the client

Mutation: altering (adding, removing or changing) a value in a column. There’s no explicit “insert”, inserting effectively means “changing no data to some data”

Mutation fragment (MF): a record in internal structures describing a mutation. There’s no single and solid representation of data in a keyspace, instead there’s a sequence of MFs, that result in a specific value of columns in rows. The MFs are stored in LSM structure

Tombstone: a MF that says “data is removed”. When the MFs are merged to get the column value the tombstone makes the value to become empty

LSM: log-structured merge-tree. In simple words -- a way to manage mutation fragments. Consists of sstables, memtable and commit log

SSTable: an on-disk storage of mutation fragments sorted by primary key. The sstable is immutable, i.e. once written it’s never updated. Since their amount increases over time, a compaction procedure is run periodically, after which unneeded sstables are removed

Memtable: an in-memory data structure that holds a bunch of mutation fragments. Once there’s enough of them (e.g. size or number threshold is hit) they are sorted by partition and cluster keys and are written into a fresh new sstable

Commit log: an append-only on-disk unsorted sequence of mutation fragments. It effectively duplicates the contents of the memtable and is needed primarily not to lose the memtable contents before it’s flushed into sstable

Compaction: a process of squashing several mutation fragments that affect the same column (or row) into a single mutation fragment. Naturally happens with SStable granularity

SSTable run: a sequence of sstables with non-overlapping primary keys in them. Used in “leveled” compaction strategy (and maybe others)

Data cache / read cache: cached rows. The read cache is separate from memtable and keeps squashed mutation fragments thus forming the final data