A push query subscribes to a continuous result stream: SELECT ... FROM <stream_or_table> EMIT CHANGES; it returns rows indefinitely as new data arrives.
A pull query retrieves the current materialized state at query time: SELECT ... FROM <table> WHERE <key_condition>; it returns immediately with point-in-time data.
Pull queries are only supported on materialized tables (tables defined with CREATE TABLE AS SELECT, or tables backed by a source with a primary key).
Use push queries in applications that need real-time streaming results (e.g., dashboards, event-driven services).
Use pull queries for request/reply patterns where a client needs the current value of a key (e.g., user profile lookup).
Configure ksqlDB server's ksql.query.pull.enable=true (default) and ensure the relevant table has a running persistent query keeping it materialized.
Known gotchas
Pull queries on non-materialized streams are not supported; attempting them returns an error — you must first materialize the result into a table.
Push queries consume server resources for the duration of the client connection; unbounded push queries in high-traffic applications can exhaust server thread pools.
Pull query scalability depends on the ksqlDB cluster topology and whether persistent query state is co-located; consult current docs on pull query routing for multi-node deployments.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp