API, CLI changes for historical features retrieval without entity_df, FAQ update

jyejare · jyejare · commit 8ff71c014d96 · 2025-07-29T17:27:02.000+05:30
Signed-off-by: jyejare &lt;jyejare@redhat.com&gt;
diff --git a/docs/getting-started/faq.md b/docs/getting-started/faq.md
@@ -39,7 +39,16 @@ Yes, this is possible. For example, you can use BigQuery as an offline store and
 
 ### How do I run `get_historical_features` without providing an entity dataframe?
 
-Feast does not provide a way to do this right now. This is an area we're actively interested in contributions for. See [GitHub issue](https://github.com/feast-dev/feast/issues/1611)
+Feast does supports fetching historical features without passing an entity dataframe with the request. 
+- As of today, only `postgres offline feature store` is supported for entity dataframe less retrieval. Remaining offline stores would be gradually updated to support the entity df less retrieval. The stores would be selected based on priorities and user base/request. 
+- The retrieval is based on `start_date` and `end_date` parameters to the function. Here are some combinations supported.
+  - Both params are given, Returns data during the given start to end timerange.
+  - Only start_date param is given, Returns data from the start date to `now` time.
+  - Only end_date param is given, Returns data during the end_date minus TTL time in feature view.
+  - Both params are `not` given, Returns data during the TTL time in feature view to now time.
+- When multiple features are requested from multiple feature-views it is required to have entity ids in both of them for `JOIN` so that 
+
+This is an area we're actively interested in contributions for. See [GitHub issue](https://github.com/feast-dev/feast/issues/1611)
 
 ### Does Feast provide security or access control?
 
diff --git a/sdk/python/feast/cli/features.py b/sdk/python/feast/cli/features.py
@@ -1,4 +1,5 @@
 import json
+from datetime import datetime
 from typing import List
 
 import click
@@ -140,37 +141,69 @@ def get_online_features(ctx: click.Context, entities: List[str], features: List[
     "--dataframe",
     "-d",
     type=str,
-    required=True,
     help='JSON string containing entities and timestamps. Example: \'[{"event_timestamp": "2025-03-29T12:00:00", "driver_id": 1001}]\'',
 )
 @click.option(
     "--features",
     "-f",
     multiple=True,
-    required=True,
     help="Features to retrieve. feature-view:feature-name ex: driver_hourly_stats:conv_rate",
 )
+@click.option(
+    "--start-date",
+    "-s",
+    type=str,
+    help="Start date for historical feature retrieval. Format: YYYY-MM-DD HH:MM:SS",
+)
+@click.option(
+    "--end-date",
+    "-e",
+    type=str,
+    help="End date for historical feature retrieval. Format: YYYY-MM-DD HH:MM:SS",
+)
 @click.pass_context
-def get_historical_features(ctx: click.Context, dataframe: str, features: List[str]):
+def get_historical_features(
+    ctx: click.Context,
+    dataframe: str,
+    features: List[str],
+    start_date: str,
+    end_date: str,
+):
     """
     Fetch historical feature values for a given entity ID
     """
     store = create_feature_store(ctx)
-    try:
-        entity_list = json.loads(dataframe)
-        if not isinstance(entity_list, list):
-            raise ValueError("Entities must be a list of dictionaries.")
-
-        entity_df = pd.DataFrame(entity_list)
-        entity_df["event_timestamp"] = pd.to_datetime(entity_df["event_timestamp"])
+    if not dataframe and not start_date and not end_date:
+        click.echo(
+            "Either --dataframe or --start-date and/or --end-date must be provided."
+        )
+        return
 
-    except Exception as e:
-        click.echo(f"Error parsing entities JSON: {e}", err=True)
+    if dataframe and (start_date or end_date):
+        click.echo("Cannot specify both --dataframe and --start-date/--end-date.")
         return
 
+    entity_df = None
+    if dataframe:
+        try:
+            entity_list = json.loads(dataframe)
+            if not isinstance(entity_list, list):
+                raise ValueError("Entities must be a list of dictionaries.")
+
+            entity_df = pd.DataFrame(entity_list)
+            entity_df["event_timestamp"] = pd.to_datetime(entity_df["event_timestamp"])
+
+        except Exception as e:
+            click.echo(f"Error parsing entities JSON: {e}", err=True)
+            return
+
     feature_vector = store.get_historical_features(
         entity_df=entity_df,
         features=list(features),
+        start_date=datetime.strptime(start_date, "%Y-%m-%d %H:%M:%S")
+        if start_date
+        else None,
+        end_date=datetime.strptime(end_date, "%Y-%m-%d %H:%M:%S") if end_date else None,
     ).to_df()
 
     click.echo(feature_vector.to_json(orient="records", indent=4))
diff --git a/sdk/python/feast/infra/offline_stores/contrib/postgres_offline_store/postgres.py b/sdk/python/feast/infra/offline_stores/contrib/postgres_offline_store/postgres.py
@@ -46,7 +46,7 @@
 from feast.repo_config import RepoConfig
 from feast.saved_dataset import SavedDatasetStorage
 from feast.type_map import pg_type_code_to_arrow
-from feast.utils import make_tzaware
+from feast.utils import _utc_now, make_tzaware
 
 from .postgres_source import PostgreSQLSource
 
@@ -136,7 +136,7 @@ def get_historical_features(
         if entity_df is None:
             # Default to current time if end_date not provided
             if end_date is None:
-                end_date = datetime.now(tz=timezone.utc)
+                end_date = _utc_now()
             else:
                 end_date = make_tzaware(end_date)
 
diff --git a/sdk/python/feast/infra/offline_stores/remote.py b/sdk/python/feast/infra/offline_stores/remote.py
@@ -116,7 +116,7 @@ def __init__(
         client: FeastFlightClient,
         api: str,
         api_parameters: Dict[str, Any],
-        entity_df: Union[pd.DataFrame, str] = None,
+        entity_df: Optional[Union[pd.DataFrame, str]] = None,
         table: pa.Table = None,
         metadata: Optional[RetrievalMetadata] = None,
     ):
@@ -193,7 +193,7 @@ def get_historical_features(
         config: RepoConfig,
         feature_views: List[FeatureView],
         feature_refs: List[str],
-        entity_df: Union[pd.DataFrame, str],
+        entity_df: Optional[Union[pd.DataFrame, str]],
         registry: BaseRegistry,
         project: str,
         full_feature_names: bool = False,
@@ -482,8 +482,8 @@ def _get_entity_df_event_timestamp_range(
 def _send_retrieve_remote(
     api: str,
     api_parameters: Dict[str, Any],
-    entity_df: Union[pd.DataFrame, str],
-    table: pa.Table,
+    entity_df: Optional[Union[pd.DataFrame, str]],
+    table: Optional[pa.Table],
     client: FeastFlightClient,
 ):
     command_descriptor = _call_put(
@@ -510,7 +510,7 @@ def _call_put(
     api: str,
     api_parameters: Dict[str, Any],
     client: FeastFlightClient,
-    entity_df: Union[pd.DataFrame, str],
+    entity_df: Optional[Union[pd.DataFrame, str]],
     table: pa.Table,
 ):
     # Generate unique command identifier
@@ -535,7 +535,7 @@ def _call_put(
 
 def _put_parameters(
     command_descriptor: fl.FlightDescriptor,
-    entity_df: Union[pd.DataFrame, str],
+    entity_df: Optional[Union[pd.DataFrame, str]],
     table: pa.Table,
     client: FeastFlightClient,
 ):
diff --git a/sdk/python/feast/offline_server.py b/sdk/python/feast/offline_server.py
@@ -5,7 +5,7 @@
 import sys
 import traceback
 from datetime import datetime
-from typing import Any, Dict, List, cast
+from typing import Any, Dict, List, Optional, cast
 
 import click
 import pyarrow as pa
@@ -413,20 +413,24 @@ def list_actions(self, context):
             ),
         ]
 
-    def _validate_get_historical_features_parameters(self, command: dict, key: str):
-        assert key in self.flights, f"missing key={key}"
+    def _validate_get_historical_features_parameters(
+        self, command: dict, key: Optional[str] = None
+    ):
+        if key:
+            assert key in self.flights, f"missing key={key}"
         assert "feature_view_names" in command, "feature_view_names is mandatory"
         assert "name_aliases" in command, "name_aliases is mandatory"
         assert "feature_refs" in command, "feature_refs is mandatory"
         assert "project" in command, "project is mandatory"
         assert "full_feature_names" in command, "full_feature_names is mandatory"
 
-    def get_historical_features(self, command: dict, key: str):
+    def get_historical_features(self, command: dict, key: Optional[str] = None):
         self._validate_get_historical_features_parameters(command, key)
-
-        # Extract parameters from the internal flights dictionary
-        entity_df_value = self.flights[key]
-        entity_df = pa.Table.to_pandas(entity_df_value)
+        entity_df = None
+        if key:
+            # Extract parameters from the internal flights dictionary
+            entity_df_value = self.flights[key]
+            entity_df = pa.Table.to_pandas(entity_df_value)
 
         feature_view_names = command["feature_view_names"]
         name_aliases = command["name_aliases"]
diff --git a/sdk/python/tests/unit/infra/offline_stores/contrib/postgres_offline_store/test_postgres.py b/sdk/python/tests/unit/infra/offline_stores/contrib/postgres_offline_store/test_postgres.py
