Struct ApiaryNode 

pub struct ApiaryNode {
    pub config: NodeConfig,
    pub storage: Arc<dyn StorageBackend>,
    pub registry: Arc<RegistryManager>,
    pub query_ctx: Arc<Mutex<ApiaryQueryContext>>,
    pub bee_pool: Arc<BeePool>,
    pub cell_cache: Arc<CellCache>,
    pub thermometer: ColonyThermometer,
    pub abandonment_tracker: Arc<AbandonmentTracker>,
    /* private fields */
}

An Apiary compute node — the runtime for one machine in the swarm.

The node holds a reference to the storage backend and its configuration. In solo mode it uses LocalBackend; in multi-node mode it uses S3Backend. The node is otherwise stateless — all committed state lives in object storage.

Fields

config: NodeConfig

Node configuration including auto-detected capacity.

storage: Arc<dyn StorageBackend>

The shared storage backend (object storage or local filesystem).

registry: Arc<RegistryManager>

Registry manager for DDL operations.

query_ctx: Arc<Mutex<ApiaryQueryContext>>

DataFusion-based SQL query context.

bee_pool: Arc<BeePool>

Pool of bees for isolated task execution.

cell_cache: Arc<CellCache>

Local cell cache with LRU eviction.

thermometer: ColonyThermometer

Colony thermometer for measuring system health.

abandonment_tracker: Arc<AbandonmentTracker>

Abandonment tracker for task failure handling.

Implementations

impl ApiaryNode

pub async fn start(config: NodeConfig) -> Result<Self>

Start a new Apiary node with the given configuration.

Initialises the appropriate storage backend based on config.storage_uri and logs the node’s capacity.

pub async fn shutdown(&self)

Gracefully shut down the node.

Stops background tasks (heartbeat writer, world view builder), deletes the heartbeat file, and cleans up resources.

pub async fn write_to_frame( &self, hive: &str, box_name: &str, frame_name: &str, batch: &RecordBatch, ) -> Result<WriteResult>

Write data to a frame. This is the end-to-end write path:

1. Resolve frame from registry
2. Open/create ledger
3. Validate schema
4. Partition data
5. Write cells to storage
6. Commit ledger entry

pub async fn read_from_frame( &self, hive: &str, box_name: &str, frame_name: &str, partition_filter: Option<&HashMap<String, String>>, ) -> Result<Option<RecordBatch>>

Read data from a frame, optionally filtering by partition values. Returns all matching data as a merged RecordBatch.

pub async fn overwrite_frame( &self, hive: &str, box_name: &str, frame_name: &str, batch: &RecordBatch, ) -> Result<WriteResult>

Overwrite all data in a frame with new data. Commits a RewriteCells entry removing all existing cells and adding new ones.

pub async fn init_frame_ledger( &self, hive: &str, box_name: &str, frame_name: &str, ) -> Result<()>

Initialize the ledger for a frame (called after create_frame in registry).

pub async fn sql(&self, query: &str) -> Result<Vec<RecordBatch>>

Execute a SQL query and return results as RecordBatches.

The query is executed through the BeePool — assigned to an idle bee or queued if all bees are busy. Each bee runs in its own sealed chamber with memory budget and timeout enforcement.

Supports:

• Standard SQL (SELECT, GROUP BY, ORDER BY, etc.) over frames
• Custom commands: USE HIVE, USE BOX, SHOW HIVES, SHOW BOXES, SHOW FRAMES, DESCRIBE
• 3-part table names: hive.box.frame
• 1-part names after USE HIVE / USE BOX

pub async fn bee_status(&self) -> Vec<BeeStatus>

Return the status of each bee in the pool.

pub async fn world_view(&self) -> WorldView

Return the current world view snapshot.

pub async fn swarm_status(&self) -> SwarmStatus

Return swarm status: a summary of all nodes visible to this node.

pub async fn colony_status(&self) -> ColonyStatus

Return the current colony status: temperature and regulation state.

pub async fn sql_distributed(&self, query: &str) -> Result<Vec<RecordBatch>>

Execute a distributed query (v2 feature - explicit control).

This method is reserved for v2 when users want explicit control over distributed execution strategy. In v1, distributed execution happens transparently within the query context based on query planning.