featurebyte 3.4.1__tar.gz → 3.4.2__tar.gz

{featurebyte-3.4.1 → featurebyte-3.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: featurebyte
-Version: 3.4.1
+Version: 3.4.2
 Summary: Python Library for FeatureOps
 Author: FeatureByte
 Author-email: FeatureByte <it-admin@featurebyte.com>

{featurebyte-3.4.1 → featurebyte-3.4.2}/featurebyte/__init__.py

@@ -33,6 +33,8 @@ from featurebyte.api.feature_group import BaseFeatureGroup, FeatureGroup
 from featurebyte.api.feature_job_setting_analysis import FeatureJobSettingAnalysis
 from featurebyte.api.feature_list import FeatureList
 from featurebyte.api.feature_store import FeatureStore
+from featurebyte.api.forecast_table import ForecastTable
+from featurebyte.api.forecast_view import ForecastView
 from featurebyte.api.historical_feature_table import HistoricalFeatureTable
 from featurebyte.api.item_table import ItemTable
 from featurebyte.api.item_view import ItemView
@@ -513,6 +515,8 @@ __all__ = [
     "CalendarTable",
     "CalendarView",
     "Catalog",
+    "ForecastTable",
+    "ForecastView",
     "ChangeView",
     "CronFeatureJobSetting",
     "Crontab",

{featurebyte-3.4.1 → featurebyte-3.4.2}/featurebyte/api/base_table.py

@@ -516,8 +516,9 @@ class TableApiObject(
         TableDataType.TIME_SERIES_TABLE,
         TableDataType.SNAPSHOTS_TABLE,
         TableDataType.CALENDAR_TABLE,
+        TableDataType.FORECAST_TABLE,
     ] = Field(
-        description="Table type. Either source_table, event_table, item_table, dimension_table, scd_table, time_series_table, snapshots_table or calendar_table."
+        description="Table type. Either source_table, event_table, item_table, dimension_table, scd_table, time_series_table, snapshots_table, calendar_table or forecast_table."
     )
 
     # pydantic instance variable (internal use)

{featurebyte-3.4.1 → featurebyte-3.4.2}/featurebyte/api/calendar_view.py

@@ -164,6 +164,7 @@ class CalendarView(View, RawMixin):
             If joining a CalendarView to the given view type is not supported
         """
         from featurebyte.api.event_view import EventView
+        from featurebyte.api.item_view import ItemView
         from featurebyte.api.snapshots_view import SnapshotsView
         from featurebyte.api.time_series_view import TimeSeriesView
 
@@ -178,7 +179,7 @@ class CalendarView(View, RawMixin):
         }
         # The join should transform the left view's (EventView, TimeSeriesView, etc) timestamp
         # column into its local time, truncated to day, and match with CalendarView's date column.
-        if isinstance(left_view, EventView):
+        if isinstance(left_view, (EventView, ItemView)):
             original_timestamp_schema = left_view.event_timestamp_schema
             column_name = left_view.timestamp_column
         elif isinstance(left_view, TimeSeriesView):

{featurebyte-3.4.1 → featurebyte-3.4.2}/featurebyte/api/catalog.py

@@ -1214,8 +1214,8 @@ class Catalog(NameAttributeUpdatableMixin, SavableApiObject, CatalogGetByIdMixin
         Gets a Table object from the catalog based on its name.
 
         A Table object represents a source table within the data warehouse and provides metadata to support feature
-        engineering. There are seven distinct types of Table objects: EventTable, ItemTable, DimensionTable,
-        SCDTable, TimeSeriesTable, SnapshotsTable and CalendarTable.
+        engineering. There are eight distinct types of Table objects: EventTable, ItemTable, DimensionTable,
+        SCDTable, TimeSeriesTable, SnapshotsTable, CalendarTable and ForecastTable.
 
         Parameters
         ----------

{featurebyte-3.4.1 → featurebyte-3.4.2}/featurebyte/api/deployment.py

@@ -38,6 +38,7 @@ from featurebyte.exception import (
 from featurebyte.models.base import PydanticObjectId
 from featurebyte.models.batch_request_table import BatchRequestInput
 from featurebyte.models.deployment import DeploymentModel
+from featurebyte.models.deployment_sql import DeploymentSqlModel
 from featurebyte.schema.batch_feature_table import (
     BatchExternalFeatureTableCreate,
     BatchFeatureTableCreate,
@@ -531,6 +532,46 @@ class Deployment(DeletableApiObject):
             ).replace("<API_TOKEN>", str(current_profile.api_token)),
         )
 
+    @typechecked
+    def get_deployment_sql(
+        self,
+        max_features_per_query: Optional[int] = None,
+    ) -> DeploymentSqlModel:
+        """
+        Generate SQL code that can be used to compute features for this deployment. The generated
+        SQL can be scheduled and run directly in your data warehouse to populate feature tables
+        without going through FeatureByte's serving infrastructure.
+
+        Parameters
+        ----------
+        max_features_per_query: Optional[int]
+            Maximum number of features to include in a single SQL query. If not specified, features
+            are only split by aggregation source. Use this to control the complexity of each
+            individual query.
+
+        Returns
+        -------
+        DeploymentSqlModel
+            Object containing the generated SQL. Key attributes:
+            - feature_table_sqls: List of FeatureTableSql objects, each with sql_code,
+              feature_names, feature_ids, and optional feature_job_setting.
+            - udf_registration_sqls: List of SQL statements for registering any required UDFs.
+
+        Examples
+        --------
+        Generate deployment SQL for a deployment.
+
+        >>> deployment = catalog.get_deployment(<deployment_name>)  # doctest: +SKIP
+        >>> deployment_sql = deployment.get_deployment_sql()  # doctest: +SKIP
+        >>> for feature_table_sql in deployment_sql.feature_table_sqls:  # doctest: +SKIP
+        ...     print(feature_table_sql.sql_code)
+        """
+        payload = {"deployment_id": str(self.id)}
+        if max_features_per_query is not None:
+            payload["max_features_per_query"] = max_features_per_query  # type: ignore[assignment]
+        result = self.post_async_task(route="/deployment_sql", payload=payload)
+        return DeploymentSqlModel(**result)
+
     def get_feature_jobs_status(
         self,
         job_history_window: int = 1,

featurebyte-3.4.2/featurebyte/api/forecast_table.py

@@ -0,0 +1,275 @@
+"""
+ForecastTable class
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, List, Optional, Type, cast
+
+from bson import ObjectId
+from pydantic import Field, StrictStr, model_validator
+from typing_extensions import Literal
+
+from featurebyte.api.base_table import TableApiObject
+from featurebyte.common.doc_util import FBAutoDoc
+from featurebyte.common.validator import construct_data_model_validator
+from featurebyte.enum import DBVarType, TableDataType, ViewMode
+from featurebyte.exception import RecordRetrievalException
+from featurebyte.models.forecast_table import ForecastTableModel
+from featurebyte.query_graph.graph import GlobalQueryGraph
+from featurebyte.query_graph.model.table import (
+    AllTableDataT,
+    ForecastTableData,
+)
+from featurebyte.query_graph.model.timestamp_schema import TimestampSchema
+from featurebyte.query_graph.node.cleaning_operation import ColumnCleaningOperation
+from featurebyte.query_graph.node.input import InputNode
+from featurebyte.query_graph.node.nested import ViewMetadata
+from featurebyte.schema.forecast_table import ForecastTableCreate, ForecastTableUpdate
+
+if TYPE_CHECKING:
+    from featurebyte.api.forecast_view import ForecastView
+
+
+class ForecastTable(TableApiObject):
+    """
+    A ForecastTable object represents a table of forecasted values indexed by both a
+    point-in-time (effective timestamp) and a forecast horizon (forecast timestamp).
+    """
+
+    # class variables
+    __fbautodoc__: ClassVar[FBAutoDoc] = FBAutoDoc(
+        proxy_class="featurebyte.ForecastTable",
+        skip_params_and_signature_in_class_docs=True,
+    )
+    _route: ClassVar[str] = "/forecast_table"
+    _update_schema_class: ClassVar[Any] = ForecastTableUpdate
+    _create_schema_class: ClassVar[Any] = ForecastTableCreate
+    _get_schema: ClassVar[Any] = ForecastTableModel
+    _table_data_class: ClassVar[Type[AllTableDataT]] = ForecastTableData
+
+    # pydantic instance variable (public)
+    type: Literal[TableDataType.FORECAST_TABLE] = TableDataType.FORECAST_TABLE
+
+    # pydantic instance variable (internal use)
+    internal_natural_key_column: Optional[StrictStr] = Field(
+        alias="natural_key_column", default=None
+    )
+    internal_effective_timestamp_column: StrictStr = Field(alias="effective_timestamp_column")
+    internal_effective_timestamp_schema: Optional[TimestampSchema] = Field(
+        alias="effective_timestamp_schema", default=None
+    )
+    internal_forecast_timestamp_column: StrictStr = Field(alias="forecast_timestamp_column")
+    internal_forecast_timestamp_schema: Optional[TimestampSchema] = Field(
+        alias="forecast_timestamp_schema", default=None
+    )
+
+    # pydantic validators
+    _model_validator = model_validator(mode="after")(
+        construct_data_model_validator(
+            columns_info_key="internal_columns_info",
+            expected_column_field_name_type_pairs=[
+                (
+                    "internal_record_creation_timestamp_column",
+                    DBVarType.supported_timestamp_types(),
+                ),
+                (
+                    "internal_natural_key_column",
+                    DBVarType.supported_id_types(),
+                ),
+                (
+                    "internal_effective_timestamp_column",
+                    DBVarType.supported_datetime_types(),
+                ),
+                (
+                    "internal_forecast_timestamp_column",
+                    DBVarType.supported_datetime_types(),
+                ),
+            ],
+        )
+    )
+
+    def get_view(
+        self,
+        view_mode: Literal[ViewMode.AUTO, ViewMode.MANUAL] = ViewMode.AUTO,
+        drop_column_names: Optional[List[str]] = None,
+        column_cleaning_operations: Optional[List[ColumnCleaningOperation]] = None,
+    ) -> ForecastView:
+        """
+        Gets a ForecastView object from a ForecastTable object.
+
+        Parameters
+        ----------
+        view_mode: Literal[ViewMode.AUTO, ViewMode.MANUAL]
+            View mode to use. When auto, the view will be constructed with cleaning operations from
+            the table, and the record creation timestamp column will be dropped.
+        drop_column_names: Optional[List[str]]
+            List of column names to drop (manual mode only).
+        column_cleaning_operations: Optional[List[ColumnCleaningOperation]]
+            List of cleaning operations to apply per column in manual mode only. Each element in
+            the list indicates the cleaning operations for a specific column.
+
+        Returns
+        -------
+        ForecastView
+            ForecastView object constructed from the source table.
+
+        Examples
+        --------
+        Get a ForecastView in automated mode.
+
+        >>> forecast_table = catalog.get_table("FORECAST")  # doctest: +SKIP
+        >>> forecast_view = forecast_table.get_view()  # doctest: +SKIP
+        """
+        from featurebyte.api.forecast_view import ForecastView
+
+        self._validate_view_mode_params(
+            view_mode=view_mode,
+            drop_column_names=drop_column_names,
+            column_cleaning_operations=column_cleaning_operations,
+        )
+
+        drop_column_names = drop_column_names or []
+        if view_mode == ViewMode.AUTO and self.record_creation_timestamp_column:
+            drop_column_names.append(self.record_creation_timestamp_column)
+
+        data_node = self.frame.node
+        assert isinstance(data_node, InputNode)
+        forecast_table_data = cast(ForecastTableData, self.table_data)
+        (
+            forecast_table_data,
+            column_cleaning_operations,
+        ) = self._prepare_table_data_and_column_cleaning_operations(
+            table_data=forecast_table_data,
+            column_cleaning_operations=column_cleaning_operations,
+            view_mode=view_mode,
+        )
+
+        view_graph_node, columns_info = forecast_table_data.construct_forecast_view_graph_node(
+            forecast_table_node=data_node,
+            drop_column_names=drop_column_names,
+            metadata=ViewMetadata(
+                view_mode=view_mode,
+                drop_column_names=drop_column_names,
+                column_cleaning_operations=column_cleaning_operations,
+                table_id=data_node.parameters.id,
+            ),
+        )
+        inserted_graph_node = GlobalQueryGraph().add_node(view_graph_node, input_nodes=[data_node])
+        columns_info = self._prepare_columns_info_for_view(
+            view_node=inserted_graph_node, columns_info=columns_info
+        )
+        return ForecastView(
+            feature_store=self.feature_store,
+            tabular_source=self.tabular_source,
+            columns_info=columns_info,
+            node_name=inserted_graph_node.name,
+            natural_key_column=self.natural_key_column,
+        )
+
+    @property
+    def timestamp_column(self) -> Optional[str]:
+        """
+        Timestamp column name of the ForecastTable (effective timestamp)
+
+        Returns
+        -------
+        Optional[str]
+        """
+        return self.effective_timestamp_column
+
+    @property
+    def natural_key_column(self) -> Optional[str]:
+        """
+        Natural key column name of the ForecastTable
+
+        Returns
+        -------
+        Optional[str]
+        """
+        try:
+            return self.cached_model.natural_key_column
+        except RecordRetrievalException:
+            return self.internal_natural_key_column
+
+    @property
+    def effective_timestamp_column(self) -> str:
+        """
+        Effective timestamp column name of the ForecastTable
+
+        Returns
+        -------
+        str
+        """
+        try:
+            return self.cached_model.effective_timestamp_column
+        except RecordRetrievalException:
+            return self.internal_effective_timestamp_column
+
+    @property
+    def effective_timestamp_schema(self) -> Optional[TimestampSchema]:
+        """
+        Schema of the effective timestamp column
+
+        Returns
+        -------
+        Optional[TimestampSchema]
+        """
+        try:
+            return self.cached_model.effective_timestamp_schema
+        except RecordRetrievalException:
+            return self.internal_effective_timestamp_schema
+
+    @property
+    def forecast_timestamp_column(self) -> str:
+        """
+        Forecast timestamp column name of the ForecastTable
+
+        Returns
+        -------
+        str
+        """
+        try:
+            return self.cached_model.forecast_timestamp_column
+        except RecordRetrievalException:
+            return self.internal_forecast_timestamp_column
+
+    @property
+    def forecast_timestamp_schema(self) -> Optional[TimestampSchema]:
+        """
+        Schema of the forecast timestamp column
+
+        Returns
+        -------
+        Optional[TimestampSchema]
+        """
+        try:
+            return self.cached_model.forecast_timestamp_schema
+        except RecordRetrievalException:
+            return self.internal_forecast_timestamp_schema
+
+    @classmethod
+    def get_by_id(
+        cls,
+        id: ObjectId,
+    ) -> ForecastTable:
+        """
+        Returns a ForecastTable object by its unique identifier (ID).
+
+        Parameters
+        ----------
+        id: ObjectId
+            ForecastTable unique identifier ID.
+
+        Returns
+        -------
+        ForecastTable
+            ForecastTable object.
+
+        Examples
+        --------
+        Get a ForecastTable object that is already saved.
+
+        >>> fb.ForecastTable.get_by_id(<forecast_table_id>)  # doctest: +SKIP
+        """
+        return cls._get_by_id(id=id)

featurebyte-3.4.2/featurebyte/api/forecast_view.py

@@ -0,0 +1,168 @@
+"""
+ForecastView class
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Optional, cast
+
+from pydantic import Field
+
+from featurebyte.api.view import RawMixin, View, ViewColumn
+from featurebyte.common.doc_util import FBAutoDoc
+from featurebyte.enum import TableDataType
+from featurebyte.exception import JoinViewMismatchError
+from featurebyte.query_graph.enum import GraphNodeType, NodeType
+from featurebyte.query_graph.model.timestamp_schema import TimestampSchema
+from featurebyte.query_graph.node.input import ForecastTableInputNodeParameters, InputNode
+
+
+class ForecastViewColumn(ViewColumn):
+    """
+    ForecastViewColumn class
+    """
+
+    # class variables
+    __fbautodoc__: ClassVar[FBAutoDoc] = FBAutoDoc()
+
+
+class ForecastView(View, RawMixin):
+    """
+    A ForecastView object is a modified version of the ForecastTable object that provides additional
+    capabilities for transforming data. With a ForecastView, you can create and transform columns
+    and filter records prior to feature declaration.
+
+    See Also
+    --------
+    - [forecast_table#get_view](/reference/featurebyte.api.forecast_table.ForecastTable.get_view/): get forecast view from a `ForecastTable`
+    """
+
+    # class variables
+    __fbautodoc__: ClassVar[FBAutoDoc] = FBAutoDoc(
+        proxy_class="featurebyte.ForecastView",
+        skip_params_and_signature_in_class_docs=True,
+    )
+    _series_class: ClassVar[Any] = ForecastViewColumn
+    _view_graph_node_type: ClassVar[GraphNodeType] = GraphNodeType.FORECAST_VIEW
+
+    # pydantic instance variables
+    natural_key_column: Optional[str] = Field(
+        frozen=True,
+        default=None,
+        description="Represents the natural key column of the forecast table.",
+    )
+
+    @property
+    def timestamp_column(self) -> str:
+        """
+        Timestamp column of the forecast table (effective timestamp)
+
+        Returns
+        -------
+        str
+        """
+        return self.effective_timestamp_column
+
+    @property
+    def effective_timestamp_column(self) -> str:
+        """
+        Effective timestamp column of the forecast table
+
+        Returns
+        -------
+        str
+        """
+        return self._get_forecast_table_node_parameters().effective_timestamp_column
+
+    @property
+    def effective_timestamp_schema(self) -> Optional[TimestampSchema]:
+        """
+        Effective timestamp schema of the forecast table
+
+        Returns
+        -------
+        Optional[TimestampSchema]
+        """
+        return self._get_forecast_table_node_parameters().effective_timestamp_schema
+
+    @property
+    def forecast_timestamp_column(self) -> str:
+        """
+        Forecast timestamp column of the forecast table
+
+        Returns
+        -------
+        str
+        """
+        return self._get_forecast_table_node_parameters().forecast_timestamp_column
+
+    @property
+    def forecast_timestamp_schema(self) -> Optional[TimestampSchema]:
+        """
+        Forecast timestamp schema of the forecast table
+
+        Returns
+        -------
+        Optional[TimestampSchema]
+        """
+        return self._get_forecast_table_node_parameters().forecast_timestamp_schema
+
+    def _get_forecast_table_node_parameters(self) -> ForecastTableInputNodeParameters:
+        input_node = next(
+            node
+            for node in self.graph.iterate_nodes(target_node=self.node, node_type=NodeType.INPUT)
+            if cast(InputNode, node).parameters.type == TableDataType.FORECAST_TABLE
+        )
+        return cast(ForecastTableInputNodeParameters, input_node.parameters)
+
+    def _get_additional_inherited_columns(self) -> set[str]:
+        return {self.effective_timestamp_column, self.forecast_timestamp_column}
+
+    @property
+    def protected_attributes(self) -> list[str]:
+        """
+        List of protected attributes used to extract protected_columns
+
+        Returns
+        -------
+        list[str]
+        """
+        out = super().protected_attributes + [
+            "effective_timestamp_column",
+            "forecast_timestamp_column",
+        ]
+        if self.natural_key_column is not None:
+            out.append("natural_key_column")
+        return out
+
+    @property
+    def _getitem_frame_params(self) -> dict[str, Any]:
+        """
+        Parameters that will be passed to frame-like class constructor in __getitem__ method
+
+        Returns
+        -------
+        dict[str, Any]
+        """
+        params = super()._getitem_frame_params
+        params.update({"natural_key_column": self.natural_key_column})
+        return params
+
+    def validate_join(self, other_view: View) -> None:
+        """
+        Validate join should be implemented by view classes that have extra requirements.
+
+        Parameters
+        ----------
+        other_view: View
+            the other view that we are joining with
+
+        Raises
+        ------
+        JoinViewMismatchError
+            raised when ForecastView is used as the left-hand side of a join
+        """
+        raise JoinViewMismatchError("ForecastView cannot be used as the left-hand side of a join")
+
+    def _get_join_column(self) -> Optional[str]:
+        return self.natural_key_column

{featurebyte-3.4.1 → featurebyte-3.4.2}/featurebyte/api/item_view.py

@@ -18,6 +18,7 @@ from featurebyte.query_graph.model.feature_job_setting import (
     FeatureJobSettingUnion,
 )
 from featurebyte.query_graph.model.table import ItemTableData
+from featurebyte.query_graph.model.timestamp_schema import TimestampSchema
 from featurebyte.query_graph.node.metadata.operation import DerivedDataColumn
 from featurebyte.typing import OffsetType
 
@@ -156,6 +157,17 @@ class ItemView(View, GroupByMixin, RawMixin):
         """
         return self.timestamp_column_name
 
+    @property
+    def event_timestamp_schema(self) -> Optional[TimestampSchema]:
+        """
+        Event timestamp schema inherited from the associated EventView
+
+        Returns
+        -------
+        Optional[TimestampSchema]
+        """
+        return self.event_view.event_timestamp_schema
+
     @property
     def timestamp_timezone_offset_column(self) -> Optional[str]:
         """