Calculation

Summary

The Calculation class describes a Calculation feature that is applied to a Realtime Feature View via the features param.

Example

from tecton import Calculation, RealtimeFeatureView

transaction_counts_fv = RealtimeFeatureView(
    name="transaction_counts_features",
    sources=[request_ds, user_transaction_metrics],
    # mode=None implied
    ...
    features = [
        Calculation(
            name="transaction_count_fill_na",
            expr="COALESCE(user_transaction_metrics.transaction_count, request_ds.default_count)",
        ),
        Calculation(
            name="transaction_count_add_1",
            expr="user_transaction_metrics.transaction_count + 1",
            description="a test calculation utilizing addition",
            tags={"tag": "value"}
        ),
    ],
)

Attributes

Name	Data Type	Description
description	Optional[str]	A human-readable description of the feature.
tags	Optional[Dict[str, str]]	Tags associated with the feature (key-value pairs of user-defined metadata).
name	str	The name of this feature. Must be explicitly defined.
expr	str	The calculation string expressing the operations and input operands.

__init__(...)

Parameters

• description: Optional[str] = None A human-readable description of the feature.
• tags: Optional[Dict[str, str]] = None Tags associated with the feature (key-value pairs of user-defined metadata).
• name: str = None The name of this feature. Must be explicitly defined.
• expr: str = None The calculation string expressing the operations and input operands.

SQL Expression Reference

You can use the following SQL functions in Calculation Features:

Arithmetic

Perform simple arithmetic using these operators:

• Addition: +
• Subtraction: -
• Multiplication: *
• Division: /

add_one_rtfv = RealtimeFeatureView(
    name="add_one_example",
    sources=[my_source],
    features=[
        Calculation(
            name="amount_plus_one",
            expr="my_source.amount + 1"
        )
    ]
)

info

Please note the following on arithmetic return types:

• For addition, subtraction, and multiplication: the result of arithmetic operation will be the type required to preserve the precision of the inputs. The precision hierarchy is Float64 -> Float32 -> Int64 -> Int32. For example, a Float32 value + Int64 value will return a value of type Float32 to preserve the float input's precision.
• For division: the result will always be a Float64. If division by zero occurs, the result will be type Float64:
  • +Infinity if the numerator is positive.
  • -Infinity if the numerator is negative.
  • NaN if the numerator is 0.
• Currently, Realtime Feature Views do not support Int32 features. As a workaround for your calculations, you can cast your Int32 value to Int64 using Int32_value + 0.

CASE Statements

Use CASE statements to implement conditional logic with the following syntax:

CASE
    WHEN condition1 THEN result1
    WHEN condition2 THEN result2
    ...
    ELSE default_result
END

Where:

• WHEN clauses contain boolean expressions
• THEN clauses specify the result value for that condition
• ELSE clause (optional) provides a default value if no conditions evaluate to True
• All result values must be of the same data type

amount_category_rtfv = RealtimeFeatureView(
    name="amount_category_example",
    sources=[my_source],
    features=[
        Calculation(
            name="amount_category",
            expr="CASE WHEN my_source.amount > 100 THEN 'high' WHEN my_source.amount > 50 THEN 'medium' ELSE 'low' END"
        )
    ]
)

COALESCE

COALESCE(value1, value2, ..., default_value)

Returns the first non-null value in a list of expressions.

Parameters:

• value1, value2, ...: The expressions to evaluate in order

Type requirements:

• All input values or expressions must have the same data type

coalesce_example = RealtimeFeatureView(
    name="coalesce_example",
    sources=[my_source],
    features=[
        Calculation(
            name="amount_with_default",
            expr="COALESCE(my_source.amount, 0)"
        )
    ]
)

Comparison Operators

Compare values using these operators:

• equals : =
• not equals : != or <>
• less than : <
• less than or equal : <=
• greater than : >
• greater than or equal : >=

Type compatibility:

• Comparisons between Float32, Int32, Float64, Int64, and Bool are supported. For example, you can compare True and 1 (True = 1 returns True).
• If one of the elements is a String element, it can only be compared against another String element. Strings are compared using lexicographical order.

comparison_example = RealtimeFeatureView(
    name="comparison_example",
    sources=[my_source],
    features=[
        Calculation(
            name="amount_above_threshold",
            expr="my_source.amount > 100"
        ),
    ]
)

DATEDIFF

DATEDIFF(datepart, start_date, end_date)

Returns the count of the specified datepart boundaries crossed between two timestamps.

Parameters:

• datepart: The time unit for the difference calculation. Supported values include:
  • Microseconds: microsecond, microseconds, us, usec, usecs, usecond, useconds
  • Milliseconds: millisecond, milliseconds, ms, msec, msecs, msecond, mseconds
  • Seconds: second, seconds, sec, secs, s
  • Minutes: minute, minutes, min, mins, m
  • Hours: hour, hours, hr, hrs, h
  • Days: day, days, d, dayofmonth
  • Weeks: week, weeks, w
  • Months: month, months, mon, mons
  • Quarters: quarter, quarters
  • Years: year, years, yr, y, yrs
  • Decades: decade, decades, dec, decs
  • Centuries: century, centuries, cent, c
  • Millennia: millennium, millenniums, millennia, mil, mils, millennium
• start_date: The starting timestamp
• end_date: The ending timestamp

Returns:

• Int64: The number of datepart boundaries crossed between the two timestamps

Behavior:

• All datetimes are converted to UTC before calculation
• Follows DuckDB convention: difference equals the number of partition boundaries crossed
  • For example, DATEDIFF('days', '2022-01-01 23:59:00', '2022-01-02 00:00:00') returns 1

datediff_example = RealtimeFeatureView(
    name="datediff_example",
    sources=[my_source],
    features=[
        Calculation(
            name="minutes_since_start",
            expr="DATEDIFF('minutes', my_source.start_time, my_source.end_time)"
        )
    ]
)

Logical Operators

Combine boolean expressions using these operators:

• AND: Logical AND operator
• OR: Logical OR operator
• NOT: Logical NOT operator

logical_operators_example = RealtimeFeatureView(
    name="logical_operators_example",
    sources=[my_source],
    features=[
        Calculation(
            name="amount_in_range",
            expr="my_source.amount > 100 AND my_source.amount < 200"
        ),
    ]
)