- Diagnostics — inspect pre-aggregations and query plans. These don’t change cluster state.
- Cache and queue — inspect and manipulate the cache and the queue used for pre-aggregation builds.
- Store maintenance and recovery — operate on the underlying stores. Includes destructive commands.
Connecting
Cube Store’s MySQL protocol is served by the router on port3306 by default
(configurable via CUBESTORE_PORT, or CUBESTORE_BIND_ADDR for the full
address). Connect with the MySQL CLI client:
This connection is available when you run Cube Store yourself. Cube’s cloud
platform doesn’t expose the Cube Store port, so you can’t attach a MySQL client
to it.You can still inspect query plans there: in the SQL Runner, pick the
cache data
source and run EXPLAIN or EXPLAIN ANALYZE against Cube Store. That path only
accepts read-only statements, so the cache and queue and
store maintenance and recovery commands below
are rejected before they reach Cube Store. If you need one of those, contact
support.Avoid DUMP there. It wraps a SELECT, so it reads as a query and gets through,
but it writes to the router’s local disk and nothing cleans it up.Diagnostics
These commands don’t change cluster state and are safe to run on a healthy cluster.DUMP is the one exception to watch: it doesn’t touch cluster state
either, but it does write to the router’s local disk — see below.
information_schema.tables
To check which pre-aggregations are managed by Cube Store, query
information_schema.tables:
.cubestore/
folder in the project root during development.
EXPLAIN
Synopsis:
EXPLAIN shows the logical plan for a query:
EXPLAIN ANALYZE
Synopsis:
EXPLAIN ANALYZE shows the physical plan for the router and all workers used for
query processing:
EXPLAIN ANALYZE nor EXPLAIN ANALYZE DETAILED accepts one. Plain EXPLAIN is the only
one of the three that works on information_schema.tables.
EXPLAIN ANALYZE DETAILED
Synopsis:
EXPLAIN and EXPLAIN ANALYZE, which only show the plan, EXPLAIN ANALYZE DETAILED actually executes the query under per-query tracing and renders a
detailed execution trace as a tree with a per-category timing summary. Use it to
diagnose where time is spent within a query:
Reading a query plan
When you’re debugging performance, one thing to keep in mind is that Cube Store, due to its design, will always use some index to query data, and usage of the index itself doesn’t necessarily tell if the particular query is performing optimally or not. What’s important to look at is aggregation and partition merge strategies. In most of the cases for aggregation, Cube Store will useHashAggregate or InplaceAggregate strategy as well as Merge and MergeSort operators to merge different partitions.
Even for larger datasets, scan operations on sorted data will almost always be much more efficient and faster than hash aggregate as the Cube Store optimizer decides to use those only if there’s an index with appropriate sorting.
So, as a rule of thumb, if you see in your plan PartialHashAggregate and FinalHashAggregate nodes together with Merge operators, those queries most likely perform sub-optimally.
On the other hand, if you see PartialInplaceAggregate, FinalInplaceAggregate, and FullInplaceAggregate together with MergeSort operators in your plan, then there’s a high chance the query performs optimally.
Sometimes, there can be exceptions to this rule.
For example, a total count query run on top of the index will perform HashAggregate strategy on top of MergeSort nodes even if all required indexes are in place.
This query would be optimal as well.
DUMP
Synopsis:
DUMP plans the query, then writes a metastore backup together with the Parquet
files the query reads into a new directory under dumps/ and returns its path.
Use it to capture the exact state behind a query for offline inspection.
Cache and queue
Cube Store keeps a key-value cache and a job queue in its cache store. These commands operate on them directly.CACHE
Synopsis:
CACHE SET stores a value, optionally only if the key doesn’t exist (NX) and
optionally with a time to live in seconds (TTL). CACHE GET reads a single
key, CACHE KEYS lists keys under a prefix, CACHE INCR atomically increments a
counter, and CACHE REMOVE deletes a single key.
CACHE CLEAR removes every entry by iterating over them and deleting each one.
It requires a cache store healthy enough to be read.
QUEUE
Synopsis:
QUEUE LIST, QUEUE PENDING, and
QUEUE ACTIVE inspect it; QUEUE STALLED, QUEUE ORPHANED, and QUEUE TO_CANCEL list jobs that have stopped making progress. The remaining commands
add, claim, acknowledge, and cancel individual jobs.
QUEUE ADD’s options may be given in any order. For GET, ACK, CANCEL,
HEARTBEAT, RESULT, RESULT_BLOCKING, and MERGE_EXTRA, key is either the
job’s path or its numeric queue id.
QUEUE CLEAR empties the queue by iterating over its entries, the same way
CACHE CLEAR does.
Store maintenance and recovery
Cube Store keeps two RocksDB-backed stores: the metastore, which holds pre-aggregation metadata (tables, partitions, indexes, jobs), and the cachestore, which holds the cache and queue above.SYS METASTORE
Synopsis:
HEALTHCHECK verifies the store is readable. COMPACTION triggers a RocksDB
compaction. SET_CURRENT switches the metastore to a specific snapshot by id.
SYS CACHESTORE
Synopsis:
HEALTHCHECK verifies the store is readable and INFO reports its current
state. COMPACTION triggers a RocksDB compaction, PERSIST flushes to durable
storage, and EVICTION runs the eviction pass that reclaims space.
SYS
Synopsis:
SYS KILL ALL JOBS deletes every queued job from the metastore, which is how a
cluster stuck on a wedged build is cleared. SYS REPARTITION schedules a
repartition of a single partition by id.
SYS DROP CACHE and SYS DROP QUERY CACHE both clear the in-memory query result
cache; they are currently equivalent.
SYS PANIC WORKER deliberately panics a worker process. It exists for testing
failure handling and has no operational use.