RoomMetricsTask — Developer Reference

Developer-focused implementation examples and performance notes for RoomMetricsTask.

Calculated Metrics

Length of Stay


room_length_of_stay = abs(datediff(room_check_out_date, room_check_in_date))

Total Net Revenue


room_stay_date_total_net = (
    room_stay_date_rate_net +
    room_stay_date_fnb_net +
    room_stay_date_other_net
)

Stay Flags Implementation


# Check-in day
df = df.withColumn(
    "room_stay_date_is_check_in_day",
    F.when(
        F.col("room_stay_date") == F.col("room_check_in_date"),
        F.lit(1)
    ).otherwise(F.lit(0))
)
 
# Check-out day
df = df.withColumn(
    "room_stay_date_is_check_out_day",
    F.when(
        F.col("room_stay_date") == F.col("room_check_out_date"),
        F.lit(1)
    ).otherwise(F.lit(0))
)
 
# Stay day
df = df.withColumn(
    "room_stay_date_is_stay_day",
    F.when(
        F.col("status").isin("cancelled", "no_show", "waitlist"),
        0
    ).when(
        F.col("room_pm") == True,
        0
    ).when(
        F.col("booking_type") != BookingTypes.ROOM.value,
        0
    ).when(
        F.col("status").isin("checked_in", "checked_out", "confirmed"),
        1
    ).otherwise(0)
)
 
# Stay night (stay day but not checkout)
df = df.withColumn(
    "room_stay_date_is_stay_night",
    F.when(
        (F.col("room_stay_date_is_stay_day") == 1) &
        (F.col("room_stay_date_is_check_out_day") == 0),
        1
    ).otherwise(0)
)

Occupancy Calculation


# Total rooms by property and date
inventory_df = df.groupBy("property_id", "room_stay_date").agg(
    F.countDistinct("room_id").alias("total_rooms")
)
 
# Occupied rooms
occupied_df = df.filter(
    F.col("room_stay_date_is_stay_night") == 1
).groupBy("property_id", "room_stay_date").agg(
    F.countDistinct("room_id").alias("occupied_rooms")
)
 
# Calculate occupancy percentage
occupancy_df = inventory_df.join(
    occupied_df,
    ["property_id", "room_stay_date"],
    "left"
).withColumn(
    "occupancy",
    F.col("occupied_rooms") / F.col("total_rooms") * 100
)

Back to process documentation: /processes/tasks/processing/room-metrics-task

Requires & Provides

Requires: CleanRoomModel, CleanReservationModel
Provides: ProcessedRoomModel, ProcessedAddedRoomModel (incremental)

Incremental Mode

Runs in incremental mode when job_context.is_incremental is set. In incremental mode it:
- Processes only new/changed rooms
- Writes results to ProcessedAddedRoomModel
- Merges ProcessedAddedRoomModel into ProcessedRoomModel using composite key (res_id, room_stay_date) where the merge keeps the deduplicated row per composite key

Notes

If room_stay_date_total_net is missing we compute it from rate/fnb/other nets.
If room_pm is missing, it is defaulted to False so PM rooms don’t count as stay nights.