Skip to content

Pull Queries

Illustration of a pull query

A pull query is a form of query issued by a client that retrieves a result as of "now", like a query against a traditional RDBS.

As a dual to the push query example, a pull query for a geographic location would ask for the current map coordinates of a particular user. Because it's a pull query, it returns immediately with a finite result and closes its connection. This is ideal for rendering a user interface once, at page load time. It's generally a good fit for any sort of synchronous control flow.

Pull queries enable you to fetch the current state of a materialized view. Because materialized views are incrementally updated as new events arrive, pull queries run with predictably low latency. They're a great match for request/response flows. For asynchronous application flows, see Push Query.

Execute a pull query by sending an HTTP request to the ksqlDB REST API, and the API responds with a single response.

Pull query features and limitations

  • Pull queries are expressed using a strict subset of ANSI SQL.
  • Pull queries are currently available only against materialized aggregate tables, which means tables that are created by using a persistent query with a GROUP BY clause.
  • For non-windowed aggregations, pull queries only support looking up events by key.
  • WHERE clauses can only have ROWKEY=x-style bounds for non-windowed tables.
  • Windowed tables support bounds on WINDOWSTART using operators <=, <, =, >, >=.
  • JOIN, PARTITION BY, GROUP BY and WINDOW clauses aren't supported.
  • SELECT statements can contain column arithmetic and function calls.
  • The result of a pull query isn't persisted anywhere.

Example pull query

The following pull query gets all events for the specified user that have a timestamp within the specified time window. The WHERE clause must contain a single value of ROWKEY to retrieve and may optionally include bounds on WINDOWSTART if the materialized table is windowed.

1
2
3
SELECT * FROM user_location
  WHERE ROWKEY = 'user19r7t33'
    AND '2019-10-02T21:31:16' <= WINDOWSTART AND WINDOWSTART <= '2019-10-03T21:31:16';

API Reference

Page last revised on: 2020-04-29

Last update: 2020-04-29