teradataml.dataframe.dataframe.DataFrame.as_of = as_of(self, **kwargs)

DESCRIPTION:
    Function to get DataFrame at specific time on temporal table.
    Note:
        Function is supported only on temporal tables or temporal views.
 
PARAMETERS:
    kwargs:
        Optional Argument.
        Specifies keyword arguments.
 
        valid_time:
            Optional Argument.
            Specifies the valid time to retrieve data from DataFrame created on either ValidTime
            or BiTemporal table/view.
            Notes:
                 Argument accepts below values:
                     * "current" - to get the current valid time data.
                     * any string other than "current" is considered as date and data will be retrieved at that of time.
                     * date object - to get the data at that of time.
                     * datetime object - to get the data at that point of time.
                     * tuple - to get the data which is valid between the two valid times.
                         * tuple should have only two elements. First element considered as starting time
                           and second element considered as end time for a period of time.
                           Records will be retrieved which are valid between the two valid times.
                         * Both elements can be of date or datetime or string type. If you are using
                           string, make sure the string represents a valid date.
                         * Any element can be None.
                            * If first element is None and valid time dimension column is PERIOD_DATE type,
                              then it is considered as '0001-01-01'.
                            * If first element is None and valid time dimension column is PERIOD_TIMESTAMP type,
                              then it is considered as '0001-01-01 00:00:00.000000+00:00'.
                            * If second element is None and valid time dimension column is PERIOD_DATE type,
                              then it is considered as '9999-12-31'.
                            * If second element is None and valid time dimension column is PERIOD_TIMESTAMP type,
                              then it is considered as '9999-12-31 23:59:59.999999+00:00'.
                    * None - to consider the DataFrame as regular DataFrame and retrieve all the records from
                             valid time dimension.
            Types: date or str or tuple or NoneType
 
        include_valid_time_column:
            Optional Argument.
            Specifies whether to include the valid time column in the resultant DataFrame.
            When set to True, valid time dimension column is included in resultant DataFrame.
            Otherwise, valid time dimension column is not included in resultant DataFrame.
            Note:
                Ignored when "valid_time" is either tuple or None.
            Default Value: False
            Types: bool
 
        transaction_time:
            Optional Argument.
            Specifies the transaction time to retrieve data from DataFrame created on either
            TransactionTime or BiTemporal table/view.
            Notes:
                 * Either valid_time or transaction_time must be provided.
                 * Argument accept below values.
                    * "current" - to get the records which are valid at current time.
                    * any string other than "current" is considered as date and records which are
                      valid at that of time.
                    * datetime object - to get the records which are valid at that of time.
                    * None - to consider the DataFrame as regular DataFrame and retrieve all the records
                      from transaction time dimension.
            Types: date or str or NoneType
 
        include_transaction_time_column:
            Optional Argument.
            Specifies whether to include the transaction time column in the resultant DataFrame.
            When set to True, transaction time dimension column is included in resultant DataFrame.
            Otherwise, transaction time dimension column is not included in resultant DataFrame.
            Default Value: False
            Types: bool
 
        additional_period:
            Optional Argument.
            Specifies the additional period to be kept in resultant DataFrame.
            Note:
                This is applicable only when "valid_time" is None.
            Types: tuple of date or str
 
RETURNS:
    teradataml DataFrame
 
RAISES:
    TeradatamlException.
 
EXAMPLES:
    # Load the data to run the example.
    >>> load_example_data("teradataml", "Employee_roles") # load valid time data.
    >>> load_example_data("teradataml", "Employee_Address") # load transaction time data.
    >>> load_example_data("teradataml", "Employee") # load bitemporal data.
 
    >>> df1 = DataFrame("Employee_roles")
               EmployeeName Department  Salary      role_validity_period
    EmployeeID
    1              John Doe         IT   100.0  ('20/01/01', '24/12/31')
    2            Jane Smith         DA   200.0  ('20/01/01', '99/12/31')
    3                   Bob  Marketing   330.0  ('25/01/01', '99/12/31')
    3                   Bob      Sales   300.0  ('24/01/01', '24/12/31')
 
    # Example 1: Get the employee roles from DataFrame df1 which are valid at current time.
    >>> df1.as_of(valid_time="current")
               EmployeeName Department  Salary
    EmployeeID
    2            Jane Smith         DA   200.0
    3                   Bob  Marketing   330.0
 
    # Example 2: Get the employee roles from DataFrame df1 which are valid at current time.
    #            Also include valid time dimension column.
    >>> df1.as_of(valid_time="current", include_valid_time_column=True)
               EmployeeName Department  Salary      role_validity_period
    EmployeeID
    2            Jane Smith         DA   200.0  ('20/01/01', '99/12/31')
    3                   Bob  Marketing   330.0  ('25/01/01', '99/12/31')
 
    # Example 3: Get the employee roles from DataFrame df1 which are valid at 31st Dec 2026.
                 Include valid time dimension column.
    >>> df1.as_of(valid_time="2026-12-31", include_valid_time_column=True)
               EmployeeName Department  Salary      role_validity_period
    EmployeeID
    2            Jane Smith         DA   200.0  ('20/01/01', '99/12/31')
    3                   Bob  Marketing   330.0  ('25/01/01', '99/12/31')
 
    # Example 4: Get the employee roles from DataFrame df1 which are valid at 31st Dec 2026.
    #            Also include valid time dimension column. Use date object instead of string
    #            to specify the date.
    >>> from datetime import date
    >>> d = date(2026, 12, 31)
    >>> df1.as_of(valid_time=d, include_valid_time_column=True)
               EmployeeName Department  Salary      role_validity_period
    EmployeeID
    2            Jane Smith         DA   200.0  ('20/01/01', '99/12/31')
    3                   Bob  Marketing   330.0  ('25/01/01', '99/12/31')
 
    # Example 5: Get the employee roles which are valid between 20th Jan 2018 and 5th March 2024.
    #            Include valid time dimension column.
    >>> df1.as_of(valid_time=("2018-01-20", "2024-03-05"), include_valid_time_column=True)
               EmployeeName Department  Salary                 VALIDTIME
    EmployeeID
    2            Jane Smith         DA   200.0  ('20/01/01', '24/03/05')
    1              John Doe         IT   100.0  ('20/01/01', '24/03/05')
    3                   Bob      Sales   300.0  ('24/01/01', '24/03/05')
 
    # Example 6: Get the employee roles which are valid between 20th Jan 2018 and 5th March 2024.
    #            Include valid time dimension column. Then again get the records which are valid
    #            at 1st Jan 2023.
    >>> df1.as_of(valid_time=(date(2018, 1, 20), "2024-03-05")).as_of(valid_time=date(2023,1, 1))
               EmployeeName Department  Salary
    EmployeeID
    2            Jane Smith         DA   200.0
    1              John Doe         IT   100.0
 
    # Example 7: Get the employee roles which are valid between 1st Jan 0001 and 1st Jun 2024.
    >>> df1.as_of(valid_time=(None, date(2024, 3, 5)))
               EmployeeName Department  Salary                 VALIDTIME
    EmployeeID
    2            Jane Smith         DA   200.0  ('20/01/01', '24/03/05')
    1              John Doe         IT   100.0  ('20/01/01', '24/03/05')
    3                   Bob      Sales   300.0  ('24/01/01', '24/03/05')
 
    # Example 8: Get the employee roles which are valid between 1st Jun 2024 and 31st Dec 9999.
    >>> df1.as_of(valid_time=("2024-06-01", None))
               EmployeeName Department  Salary                 VALIDTIME
    EmployeeID
    1              John Doe         IT   100.0  ('24/06/01', '24/12/31')
    2            Jane Smith         DA   200.0  ('24/06/01', '99/12/31')
    3                   Bob  Marketing   330.0  ('25/01/01', '99/12/31')
    3                   Bob      Sales   300.0  ('24/06/01', '24/12/31')
 
    # Example 9: Consider df1 as regular DataFrame and retrieve all the records irrespective
    #            whether records are valid or not.
    >>> df1.as_of(valid_time=None)
               EmployeeName Department  Salary
    EmployeeID
    1              John Doe         IT   100.0
    2            Jane Smith         DA   200.0
    3                   Bob  Marketing   330.0
    3                   Bob      Sales   300.0
 
    # Example 10. Consider df1 as regular DataFrame and retrieve all the records irrespective
    #              whether records are valid or not. Also include additional period and valid time
    #              dimension column.
    >>> df1.as_of(valid_time=None, additional_period=("2024-01-01", "2024-03-05"), include_valid_time_column=True)
               EmployeeName Department  Salary      role_validity_period                 VALIDTIME
    EmployeeID
    1              John Doe         IT   100.0  ('20/01/01', '24/12/31')  ('24/01/01', '24/03/05')
    2            Jane Smith         DA   200.0  ('20/01/01', '99/12/31')  ('24/01/01', '24/03/05')
    3                   Bob  Marketing   330.0  ('25/01/01', '99/12/31')  ('24/01/01', '24/03/05')
    3                   Bob      Sales   300.0  ('24/01/01', '24/12/31')  ('24/01/01', '24/03/05')
 
    >>> df2 = DataFrame("Employee_Address")
               EmployeeName      address                                                           validity_period
    EmployeeID
    2            Jane Smith   456 Elm St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    1              John Doe  123 Main St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3           Bob Johnson   789 Oak St  ('2025-03-04 15:41:44.610001+00:00', '9999-12-31 23:59:59.999999+00:00')
 
    # Example 11: Consider df2 as regular DataFrame and retrieve all the records including historic
    #             records. Also include transaction time dimension column.
    >>> df2.as_of(transaction_time=None, include_transaction_time_column=True)
               EmployeeName         address                                                           validity_period
    EmployeeID
    1              John Doe     123 Main St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    2            Jane Smith      456 Elm St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3           Bob Johnson  789 Oak Street  ('2025-03-04 15:41:44.610000+00:00', '2025-03-04 15:41:44.610001+00:00')
    3           Bob Johnson      789 Oak St  ('2025-03-04 15:41:44.610001+00:00', '9999-12-31 23:59:59.999999+00:00')
 
    # Example 12: Get the employee address which are valid at current time from DataFrame df2.
    #             Also include transaction time dimension column.
    >>> df2.as_of(transaction_time="current", include_transaction_time_column=True)
               EmployeeName      address                                                           validity_period
    EmployeeID
    2            Jane Smith   456 Elm St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    1              John Doe  123 Main St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3           Bob Johnson   789 Oak St  ('2025-03-04 15:41:44.610001+00:00', '9999-12-31 23:59:59.999999+00:00')
 
    # Example 13: Get the employee address which are valid at current time from DataFrame df2.
    #             Do not include transaction time dimension column.
    >>> df2.as_of(transaction_time="current", include_transaction_time_column=False)
               EmployeeName      address
    EmployeeID
    2            Jane Smith   456 Elm St
    1              John Doe  123 Main St
    3           Bob Johnson   789 Oak St
 
    # Example 14: Get the employee address which are valid at 2025-03-04 15:41:44.610000+00:00 from DataFrame df2.
    #             Include transaction time dimension column.
    >>> df2.as_of(transaction_time="2025-03-04 15:41:44.610000+00:00", include_transaction_time_column=True)
               EmployeeName         address                                                           validity_period
    EmployeeID
    2            Jane Smith      456 Elm St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    1              John Doe     123 Main St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3           Bob Johnson  789 Oak Street  ('2025-03-04 15:41:44.610000+00:00', '2025-03-04 15:41:44.610001+00:00')
 
    # Example 15: Get the employee address which are valid at 2025-03-04 15:41:44.610001+00:00 from DataFrame df2.
    #             Include transaction time dimension column.
    >>> from datetime import datetime, timezone, timedelta
    >>> dt = datetime(2025, 3, 4, 15, 41, 44, 610001)
    >>> dt_with_tz = dt.replace(tzinfo=timezone(timedelta(hours=0)))
    >>> df2.as_of(transaction_time=dt_with_tz, include_transaction_time_column=True)
               EmployeeName      address                                                           validity_period
    EmployeeID
    2            Jane Smith   456 Elm St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    1              John Doe  123 Main St  ('2025-03-04 15:41:44.610000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3           Bob Johnson   789 Oak St  ('2025-03-04 15:41:44.610001+00:00', '9999-12-31 23:59:59.999999+00:00')
 
    >>> df3 = DataFrame("Employee")
               EmployeeName      address Department  Salary             role_validity                                                           validity_period
    EmployeeID
    1              John Doe  123 Main St         IT   100.0  ('20/01/01', '24/12/31')  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')
    2            Jane Smith   456 Elm St         DA   200.0  ('20/01/01', '99/12/31')  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3                   Bob   789 OAK St  Marketing   330.0  ('25/01/01', '99/12/31')  ('2025-05-06 11:39:25.580000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3                   Bob   789 Oak St      Sales   300.0  ('24/01/01', '24/12/31')  ('2025-03-04 18:09:08.830000+00:00', '9999-12-31 23:59:59.999999+00:00')
 
    # Example 16: Get all the records from DataFrame df3 by considering the DataFrame as
    #             regular DataFrame. Include both valid time and transaction time dimension columns.
    >>> df3.as_of(valid_time=None,
    ...           transaction_time=None,
    ...           include_valid_time_column=True,
    ...           include_transaction_time_column=True
    ...           )
               EmployeeName         address Department  Salary             role_validity                                                           validity_period
    EmployeeID
    3                   Bob  789 Oak Street      Sales   300.0  ('24/01/01', '24/12/31')  ('2025-03-04 18:08:58.720000+00:00', '2025-03-04 18:09:08.830000+00:00')
    3                   Bob      789 Oak St  Marketing   330.0  ('25/01/01', '99/12/31')  ('2025-03-04 18:09:08.830000+00:00', '2025-05-06 11:39:25.580000+00:00')
    1              John Doe     123 Main St         IT   100.0  ('20/01/01', '24/12/31')  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')
    2            Jane Smith      456 Elm St         DA   200.0  ('20/01/01', '99/12/31')  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3                   Bob  789 Oak Street  Marketing   330.0  ('25/01/01', '99/12/31')  ('2025-03-04 18:08:58.720000+00:00', '2025-03-04 18:09:08.830000+00:00')
    3                   Bob      789 OAK St  Marketing   330.0  ('25/01/01', '99/12/31')  ('2025-05-06 11:39:25.580000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3                   Bob      789 Oak St      Sales   300.0  ('24/01/01', '24/12/31')  ('2025-03-04 18:09:08.830000+00:00', '9999-12-31 23:59:59.999999+00:00')
 
    # Example 17: Get the employee address from DataFrame df3 which are valid at 1st Jun 2024 from
    #             valid time dimension and valid at '2025-03-04 18:09:08.720001+00:00' from transaction
    #             time dimension. Include both valid time and transaction time dimension columns.
    >>> df3.as_of(valid_time="2024-06-01",
    ...           transaction_time="2025-03-04 18:09:08.720001+00:00",
    ...           include_valid_time_column=True,
    ...           include_transaction_time_column=True
    ...           )
               EmployeeName         address Department  Salary             role_validity                                                           validity_period
    EmployeeID
    2            Jane Smith      456 Elm St         DA   200.0  ('20/01/01', '99/12/31')  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')
    1              John Doe     123 Main St         IT   100.0  ('20/01/01', '24/12/31')  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3                   Bob  789 Oak Street      Sales   300.0  ('24/01/01', '24/12/31')  ('2025-03-04 18:08:58.720000+00:00', '2025-03-04 18:09:08.830000+00:00')
 
    # Example 18: Get the employee address from DataFrame df3 which are valid at 25th Jan 2024
    #             from valid time dimension and valid at current time from transaction time dimension.
    #             Include only transaction time dimension column.
    >>> df3.as_of(valid_time=date(2024, 1, 25),
    ...           transaction_time="current",
    ...           include_transaction_time_column=True)
               EmployeeName      address Department  Salary                                                           validity_period
    EmployeeID
    2            Jane Smith   456 Elm St         DA   200.0  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')
    1              John Doe  123 Main St         IT   100.0  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')
    3                   Bob   789 Oak St      Sales   300.0  ('2025-03-04 18:09:08.830000+00:00', '9999-12-31 23:59:59.999999+00:00')
 
    # Example 19: Get the employee address from DataFrame df3 which are valid between 1st Jan 2025
    #             and 30th June 2025 from valid time dimension and valid at
    #             '2025-03-04 18:08:59.720000+00:00' from transaction time dimension.
    #             Include both valid time and transaction time dimension columns.
    >>> from datetime import datetime, timezone
    >>>df3.as_of(valid_time=("2025-01-01", date(2025, 6, 30)),
    ...          transaction_time=datetime(2025, 3, 4, 18, 8, 59, 720000).astimezone(timezone.utc),
    ...          include_transaction_time_column=True)
               EmployeeName     address Department  Salary                                                           validity_period                 VALIDTIME
    EmployeeID
    2            Jane Smith  456 Elm St         DA   200.0  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')  ('25/01/01', '25/06/30')
    3                   Bob  789 Oak St  Marketing   330.0  ('2025-03-04 18:09:08.830000+00:00', '2025-05-06 11:39:25.580000+00:00')  ('25/01/01', '25/06/30')
 
    # Example 20: Get the employee address from DataFrame df3 by considering the DataFrame as regular
    #             DataFrame from valid time dimension and valid at current time from transaction time dimension.
    #             Add additional period and include both valid time and transaction time dimension columns.
    >>> df3.as_of(valid_time=None,
    ...           transaction_time="current",
    ...           additional_period=("2024-01-01", "2024-03-05"),
    ...           include_valid_time_column=True,
    ...           include_transaction_time_column=True
    ...           )
               EmployeeName      address Department  Salary             role_validity                                                           validity_period                 VALIDTIME
    EmployeeID
    1              John Doe  123 Main St         IT   100.0  ('20/01/01', '24/12/31')  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')  ('24/01/01', '24/03/05')
    2            Jane Smith   456 Elm St         DA   200.0  ('20/01/01', '99/12/31')  ('2025-03-04 18:08:58.720000+00:00', '9999-12-31 23:59:59.999999+00:00')  ('24/01/01', '24/03/05')
    3                   Bob   789 OAK St  Marketing   330.0  ('25/01/01', '99/12/31')  ('2025-05-06 11:39:25.580000+00:00', '9999-12-31 23:59:59.999999+00:00')  ('24/01/01', '24/03/05')
    3                   Bob   789 Oak St      Sales   300.0  ('24/01/01', '24/12/31')  ('2025-03-04 18:09:08.830000+00:00', '9999-12-31 23:59:59.999999+00:00')  ('24/01/01', '24/03/05')