Cluster Components

Key Components

The following components are fundamental to a SingleStore cluster. They are also key terms that are used throughout the documentation.


A cluster encompasses all of the nodes that are included in a complete SingleStore DB installation.

A cluster contains aggregator nodes and leaf nodes.


A node is a server that has an installation of a SingleStore DB instance.

See Node Requirements for SingleStore Commands to learn about the commands supported by different types of nodes.


A leaf is a node that stores a subset of a cluster’s data. It functions as a storage and compute node. To optimize performance, SingleStore automatically distributes data across leaf nodes into partitions. Each leaf contains several partitions. A cluster typically contains many leaves. Each leaf is in one of the Leaf States.


A partition contains a subset (a shard) of a database’s data. Each partition holds a vertical slice of data, distributed as per a hashing algorithm on the primary key or randomly for keyless sharded databases. A leaf node contains multiple partitions. When you run CREATE DATABASE, SingleStore splits the database into partitions, which are distributed evenly among available leaf nodes. With CREATE DATABASE, you can specify the number of partitions with the PARTITIONS=X option.

If you don’t specify the number of partitions explicitly, the default is used (the number of leaf nodes times the value of the default_partitions_per_leaf engine variable.


    SingleStore stores data in tables, which can be of one of the following types:

  • Universal Storage - (Default) Supports large-scale Online Transaction Processing (OLTP) and Hybrid Transactional and Analytical Processing (HTAP) workloads at a lower total cost of ownership (TCO). Universal Storage is a continuing evolution of the columnstore and supports transactional workloads that would have traditionally used the rowstore. SingleStore recommends using the Universal Storage tables for all kinds of workloads.

  • Rowstore - In-memory rowstore tables for high-performance OLTP workloads.

    The tables can have the following properties:

  • Sharded or Reference - A sharded table’s data is distributed across partitions. By contrast, a reference table’s data is replicated, in full, to all nodes in a cluster.

  • Persisted or Temporary - Defines whether the data stored in a table is persisted or stored temporarily for the duration of a client session. Temporary tables can further be classified into regular temporary tables and global temporary tables.


An aggregator is a node that routes queries to the leaves, aggregates the intermediate results, and sends the results back to the client. There are two types of aggregators: master and child.

master aggregator is a specialized aggregator responsible for cluster monitoring and failover. It orchestrates basic cluster operations and all DDL operations. Refer AGGREGATOR SET AS MASTER for more details.

A cluster contains exactly one master aggregator. A cluster may also contain zero or more child aggregators (depending on query volume).

Aggregator to Leaf Ratio

The minimal setup for a SingleStore cluster is just one aggregator (the master aggregator) and one leaf. You can add more aggregators, which will read metadata from the master aggregator, and can run DML commands on the leaves.

The number of deployed aggregator and leaf nodes determines the storage size and performance of a cluster. Typical deployments have a 5:1 ratio of leaf:aggregator nodes. In a well-designed cluster:

  • Applications that require higher connection capabilities from application servers have a higher aggregator-to-leaf node ratio.

  • Applications with larger storage requirements have a higher leaf-to-aggregator node ratio.

Last modified: June 22, 2022

Was this article helpful?