Implementation:Risingwavelabs Risingwave Handle Query

Knowledge Sources	RisingWave RisingWave Docs
Domains	Query_Processing, Batch_Execution
Last Updated	2026-02-09 07:00 GMT

Overview

Concrete tool for executing ad-hoc SQL queries against materialized views and tables provided by the frontend batch query handler.

Description

The handle_query function processes SQL SELECT statements by generating a batch execution plan, optionally fragmenting it for distributed execution, and streaming results back to the client via the PostgreSQL wire protocol. It supports both the native RisingWave batch executor and an optional DataFusion backend.

Usage

This handler is invoked whenever a user runs a SELECT query through any PostgreSQL-compatible client (psql, JDBC, etc.) connected to RisingWave on port 4566.

Code Reference

Source Location

• Repository: risingwave
• File: src/frontend/src/handler/query.rs
• Lines: L74-100+

Signature

pub async fn handle_query(
    handler_args: HandlerArgs,
    stmt: Statement,
    formats: Vec<Format>,
) -> Result<RwPgResponse>

Import

// Internal to the frontend crate
use crate::handler::query::handle_query;

I/O Contract

Inputs

Name	Type	Required	Description
handler_args	HandlerArgs	Yes	Session context and handler metadata
stmt	Statement	Yes	Parsed SQL SELECT statement
formats	Vec<Format>	Yes	Output format preferences (text or binary per column)

Outputs

Name	Type	Description
Result<RwPgResponse>	RwPgResponse	Query results streamed via pgwire protocol

Usage Examples

Query Materialized View

-- Connect via psql
psql -h localhost -p 4566 -d dev -U root

-- Query a materialized view
SELECT user_id, event_count
FROM user_event_counts
WHERE event_count > 100
ORDER BY event_count DESC
LIMIT 10;

Aggregation Query

SELECT
    DATE_TRUNC('hour', last_event) AS hour,
    SUM(event_count) AS total_events
FROM user_event_counts
GROUP BY DATE_TRUNC('hour', last_event)
ORDER BY hour DESC;

Related Pages

Implements Principle

• Principle:Risingwavelabs_Risingwave_Batch_Query_Serving

Requires Environment

• Environment:Risingwavelabs_Risingwave_Rust_Build_Environment