diff --git a/docs/src/python/user-guide/lazy/execution.py b/docs/src/python/user-guide/lazy/execution.py index 721c0a45e3af..fb33fe66ed28 100644 --- a/docs/src/python/user-guide/lazy/execution.py +++ b/docs/src/python/user-guide/lazy/execution.py @@ -36,4 +36,34 @@ .fetch(n_rows=int(100)) ) # --8<-- [end:partial] + +# --8<-- [start:background] +import time + +background_query = ( + pl.scan_csv("docs/data/reddit.csv") + .with_columns(pl.col("name").str.to_uppercase()) + .filter(pl.col("comment_karma") > 0) + .collect(background=True) +) + +def wait_for_query(background_query, *, max_wait_time): + start_time = time.monotonic() + + while True: + result = background_query.fetch() + if result is not None: + return result # query successfully completed + + current_time = time.monotonic() + if (current_time - start_time) > max_wait_time: + background_query.cancel() + msg = f"Background query took more than {max_wait_time} s" + raise RuntimeError(msg) + + # continue waiting + time.sleep(1) + +result = wait_for_query(background_query, max_wait_time=10) +# --8<-- [end:background] """ diff --git a/docs/user-guide/lazy/execution.md b/docs/user-guide/lazy/execution.md index 975f52a0ac4a..69939700b489 100644 --- a/docs/user-guide/lazy/execution.md +++ b/docs/user-guide/lazy/execution.md @@ -77,3 +77,18 @@ shape: (27, 6) │ 77768 ┆ TINHEADNED ┆ 1139665457 ┆ 1536497404 ┆ 4434 ┆ 103 │ └───────┴───────────────────────────┴─────────────┴────────────┴───────────────┴────────────┘ ``` + +### Cancellable Executions + +With background mode, you can run a query in the background and get a handler for +an the in process query. The handler can be used to to do something else while +the query is running or be canceled. + +Here we run a background query and cancel the query if it took more than +`max_wait_time` seconds to complete. + +!!! warning "background mode is **unstable**" + + Background mode may be changed at any point as a breaking change. + +{{code_block('user-guide/lazy/execution','background',['scan_csv','collect'])}}