1+ # Copyright 2025 The Feast Authors
2+ #
3+ # Licensed under the Apache License, Version 2.0 (the "License");
4+ # you may not use this file except in compliance with the License.
5+ # You may obtain a copy of the License at
6+ #
7+ # https://www.apache.org/licenses/LICENSE-2.0
8+ #
9+ # Unless required by applicable law or agreed to in writing, software
10+ # distributed under the License is distributed on an "AS IS" BASIS,
11+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+ # See the License for the specific language governing permissions and
13+ # limitations under the License.
14+
115import asyncio
216import os
317import sys
418import threading
519import time
620import traceback
21+ from collections import defaultdict
722from contextlib import asynccontextmanager
823from datetime import datetime
924from importlib import resources as importlib_resources
10- from typing import Any , Dict , List , Optional , Union
25+ from typing import DefaultDict , NamedTuple , Any , Dict , List , Optional , Union
1126
1227import pandas as pd
1328import psutil
@@ -193,6 +208,21 @@ def get_app(
193208 registry_proto = None
194209 shutting_down = False
195210 active_timer : Optional [threading .Timer ] = None
211+ # --- Offline write batching config and batcher ---
212+ fs_cfg = getattr (store .config , "feature_server" , None )
213+ batching_cfg = None
214+ if fs_cfg is not None :
215+ batching_cfg = getattr (fs_cfg , "offline_write_batching" , None )
216+
217+ offline_batcher : Optional [OfflineWriteBatcher ] = None
218+ enabled = getattr (batching_cfg , "enabled" , False )
219+ if batching_cfg is not None and isinstance (enabled , bool ) and enabled is True :
220+ offline_batcher = OfflineWriteBatcher (store = store , cfg = batching_cfg )
221+
222+ offline_batcher = OfflineWriteBatcher (store = store , cfg = batching_cfg )
223+ logger .debug ("Offline write batching is ENABLED" )
224+ else :
225+ logger .debug ("Offline write batching is DISABLED" )
196226
197227 def stop_refresh ():
198228 nonlocal shutting_down
@@ -217,9 +247,13 @@ def async_refresh():
217247 async def lifespan (app : FastAPI ):
218248 await store .initialize ()
219249 async_refresh ()
220- yield
221- stop_refresh ()
222- await store .close ()
250+ try :
251+ yield
252+ finally :
253+ stop_refresh ()
254+ if offline_batcher is not None :
255+ offline_batcher .shutdown ()
256+ await store .close ()
223257
224258 app = FastAPI (lifespan = lifespan )
225259
@@ -324,22 +358,50 @@ async def push(request: PushFeaturesRequest) -> None:
324358 for feature_view in fvs_with_push_sources :
325359 assert_permissions (resource = feature_view , actions = actions )
326360
327- push_params = dict (
328- push_source_name = request .push_source_name ,
329- df = df ,
330- allow_registry_cache = request .allow_registry_cache ,
331- to = to ,
332- transform_on_write = request .transform_on_write ,
333- )
361+ async def _push_with_to (push_to : PushMode ) -> None :
362+ """
363+ Helper for performing a single push operation.
364+
365+ NOTE:
366+ - Feast providers **do not currently support async offline writes**.
367+ - Therefore:
368+ * ONLINE and ONLINE_AND_OFFLINE → may be async, depending on provider.async_supported.online.write
369+ * OFFLINE → always synchronous, but executed via run_in_threadpool when called from HTTP handlers.
370+ - The OfflineWriteBatcher handles offline writes directly in its own background thread, but the offline store writes are currently synchronous only.
371+ """
372+ push_params = dict (
373+ push_source_name = request .push_source_name ,
374+ df = df ,
375+ allow_registry_cache = request .allow_registry_cache ,
376+ to = push_to ,
377+ transform_on_write = request .transform_on_write ,
378+ )
334379
335- should_push_async = (
336- store ._get_provider ().async_supported .online .write
337- and to in [PushMode .ONLINE , PushMode .ONLINE_AND_OFFLINE ]
338- )
339- if should_push_async :
340- await store .push_async (** push_params )
380+ # Async currently only applies to online store writes (ONLINE / ONLINE_AND_OFFLINE paths) as theres no async for offline store
381+ if push_to in (PushMode .ONLINE , PushMode .ONLINE_AND_OFFLINE ) and (
382+ store ._get_provider ().async_supported .online .write
383+ ):
384+ await store .push_async (** push_params )
385+ else :
386+ await run_in_threadpool (lambda : store .push (** push_params ))
387+
388+ needs_online = to in (PushMode .ONLINE , PushMode .ONLINE_AND_OFFLINE )
389+ needs_offline = to in (PushMode .OFFLINE , PushMode .ONLINE_AND_OFFLINE )
390+ batching_active = offline_batcher is not None and needs_offline
391+
392+ if not batching_active :
393+ await _push_with_to (to )
341394 else :
342- store .push (** push_params )
395+ if needs_online :
396+ await _push_with_to (PushMode .ONLINE )
397+
398+ offline_batcher .enqueue (
399+ push_source_name = request .push_source_name ,
400+ df = df ,
401+ allow_registry_cache = request .allow_registry_cache ,
402+ transform_on_write = request .transform_on_write ,
403+ )
404+
343405
344406 async def _get_feast_object (
345407 feature_view_name : str , allow_registry_cache : bool
@@ -679,3 +741,167 @@ def start_server(
679741 )
680742 else :
681743 uvicorn .run (app , host = host , port = port , access_log = (not no_access_log ))
744+
745+ class _OfflineBatchKey (NamedTuple ):
746+ push_source_name : str
747+ allow_registry_cache : bool
748+ transform_on_write : bool
749+
750+
751+ class OfflineWriteBatcher :
752+ """
753+ In-process offline write batcher for /push requests.
754+
755+ - Buffers DataFrames per (push_source_name, allow_registry_cache, transform_on_write)
756+ - Flushes when either:
757+ * total rows in a buffer >= batch_size, or
758+ * time since last flush >= batch_interval_seconds
759+ - Flush runs in a dedicated background thread so the HTTP event loop stays unblocked.
760+ """
761+
762+ def __init__ (self , store : "feast.FeatureStore" , cfg : Any ):
763+ self ._store = store
764+ self ._cfg = cfg
765+
766+ # Buffers and timestamps keyed by batch key
767+ self ._buffers : DefaultDict [_OfflineBatchKey , List [pd .DataFrame ]] = defaultdict (
768+ list
769+ )
770+ self ._last_flush : DefaultDict [_OfflineBatchKey , float ] = defaultdict (time .time )
771+
772+ self ._lock = threading .Lock ()
773+ self ._stop_event = threading .Event ()
774+
775+ # Start background flusher thread
776+ self ._thread = threading .Thread (
777+ target = self ._run , name = "offline_write_batcher" , daemon = True
778+ )
779+ self ._thread .start ()
780+
781+ logger .debug (
782+ "OfflineWriteBatcher initialized: batch_size=%s, batch_interval_seconds=%s" ,
783+ getattr (cfg , "batch_size" , None ),
784+ getattr (cfg , "batch_interval_seconds" , None ),
785+ )
786+
787+ # ---------- Public API ----------
788+
789+ def enqueue (
790+ self ,
791+ push_source_name : str ,
792+ df : pd .DataFrame ,
793+ allow_registry_cache : bool ,
794+ transform_on_write : bool ,
795+ ) -> None :
796+ """
797+ Enqueue a dataframe for offline write, grouped by push source + flags.
798+ Cheap and non-blocking; heavy I/O happens in background thread.
799+ """
800+ key = _OfflineBatchKey (
801+ push_source_name = push_source_name ,
802+ allow_registry_cache = allow_registry_cache ,
803+ transform_on_write = transform_on_write ,
804+ )
805+
806+ with self ._lock :
807+ self ._buffers [key ].append (df )
808+ total_rows = sum (len (d ) for d in self ._buffers [key ])
809+
810+ # Size-based flush
811+ if total_rows >= self ._cfg .batch_size :
812+ logger .debug (
813+ "OfflineWriteBatcher size threshold reached for %s: %s rows" ,
814+ key ,
815+ total_rows ,
816+ )
817+ self ._flush_locked (key )
818+
819+ def flush_all (self ) -> None :
820+ """
821+ Flush all buffers synchronously. Intended for graceful shutdown.
822+ """
823+ with self ._lock :
824+ keys = list (self ._buffers .keys ())
825+ for key in keys :
826+ self ._flush_locked (key )
827+
828+ def shutdown (self , timeout : float = 5.0 ) -> None :
829+ """
830+ Stop the background thread and perform a best-effort flush.
831+ """
832+ logger .debug ("Shutting down OfflineWriteBatcher" )
833+ self ._stop_event .set ()
834+ try :
835+ self ._thread .join (timeout = timeout )
836+ except Exception :
837+ logger .exception ("Error joining OfflineWriteBatcher thread" )
838+
839+ # Best-effort final flush
840+ try :
841+ self .flush_all ()
842+ except Exception :
843+ logger .exception ("Error during final OfflineWriteBatcher flush" )
844+
845+ # ---------- Internal helpers ----------
846+
847+ def _run (self ) -> None :
848+ """
849+ Background loop: periodically checks for buffers that should be flushed
850+ based on time since last flush.
851+ """
852+ interval = max (1 , int (getattr (self ._cfg , "batch_interval_seconds" , 30 )))
853+ logger .debug (
854+ "OfflineWriteBatcher background loop started with check interval=%s" ,
855+ interval ,
856+ )
857+
858+ while not self ._stop_event .wait (timeout = interval ):
859+ now = time .time ()
860+ try :
861+ with self ._lock :
862+ for key , dfs in list (self ._buffers .items ()):
863+ if not dfs :
864+ continue
865+ last = self ._last_flush [key ] # this will also init the default timestamp
866+ age = now - last
867+ if age >= self ._cfg .batch_interval_seconds :
868+ logger .debug (
869+ "OfflineWriteBatcher time threshold reached for %s: age=%s" ,
870+ key ,
871+ age ,
872+ )
873+ self ._flush_locked (key )
874+ except Exception :
875+ logger .exception ("Error in OfflineWriteBatcher background loop" )
876+
877+ logger .debug ("OfflineWriteBatcher background loop exiting" )
878+
879+ def _flush_locked (self , key : _OfflineBatchKey ) -> None :
880+ """
881+ Flush a single buffer; caller must hold self._lock.
882+ """
883+ dfs = self ._buffers .get (key )
884+ if not dfs :
885+ return
886+
887+ batch_df = pd .concat (dfs , ignore_index = True )
888+ self ._buffers [key ].clear ()
889+ self ._last_flush [key ] = time .time ()
890+
891+ logger .debug (
892+ "Flushing offline batch for push_source=%s with %s rows" ,
893+ key .push_source_name ,
894+ len (batch_df ),
895+ )
896+
897+ # NOTE: offline writes are currently synchronous only, so we call directly
898+ try :
899+ self ._store .push (
900+ push_source_name = key .push_source_name ,
901+ df = batch_df ,
902+ allow_registry_cache = key .allow_registry_cache ,
903+ to = PushMode .OFFLINE ,
904+ transform_on_write = key .transform_on_write ,
905+ )
906+ except Exception :
907+ logger .exception ("Error flushing offline batch for %s" , key )
0 commit comments