GuestLoyaltyTask

The GuestLoyaltyTask computes comprehensive guest loyalty metrics based on booking and stay history. It calculates key performance indicators like lifetime value, stay counts, and booking patterns.

Overview

This task analyzes guest behavior across all their reservations to:

Calculate total stays and lifetime values
Identify returning guests and loyalty categories
Track booking patterns and preferences
Compute time between bookings
Assign loyalty segments

Flow Diagram

Data Transformations

Calculated Metrics

Guest-Level Metrics

Metric	Description	Type
`stays`	Total number of completed stays	Integer
`total_stay_nights`	Total nights across all stays	Integer
`avg_stay_nights`	Average nights per stay	Float
`max_booking_window`	Longest lead time in days	Integer
`avg_booking_window`	Average booking lead time	Float
`nunique_properties_visited`	Number of different properties stayed at	Integer
`first_booking_date`	Date of first booking	Date
`last_booking_date`	Date of most recent booking	Date
`first_check_in_date`	Date of first check-in	Date
`last_check_in_date`	Date of last check-in	Date
`last_check_out_date`	Date of last check-out (past only)	Date
`next_check_out_date`	Date of next check-out (future)	Date
`future_checkins`	Number of future check-ins	Integer
`next_check_in_date`	Date of next check-in	Date
`lifetime_total_value`	Sum of all revenue (room + F&B + other)	Decimal
`avg_total_net_revenue_per_stay`	Average total revenue per stay	Decimal
`lifetime_room_value`	Sum of room revenue only	Decimal
`avg_room_net_revenue_per_stay`	Average room revenue per stay	Decimal
`last_stayed_property_id`	Property ID of last stay	String
`last_booked_property_id`	Property ID of last booking	String
`last_booked_channel`	Channel of last booking	String
`last_booked_source`	Source of last booking	String
`last_booked_travel_agent`	Travel agent of last booking	String
`last_booked_market_segment`	Market segment of last booking	String
`last_booked_rate_code`	Rate code of last booking	String
`properties_visited`	Comma-separated list of property IDs	String
`returning_guest`	True if stays > 1	Boolean
`stays_category`	Loyalty category based on stay count	String

Reservation-Level Metrics

Metric	Description	Type
`nth_booking`	Sequential booking number for this guest cluster	Integer
`time_between_bookings`	Days since previous booking	Integer

Loyalty Categories

Guests are assigned to categories based on their stay count:

Models

Requires

ProcessedGuestModel - Guest data from previous processing steps
ProcessedReservationModel - Reservation data with metrics

Provides

ProcessedGuestModel - Guest data enriched with loyalty metrics
ProcessedReservationModel - Reservations enriched with nth_booking

Incremental Behavior

When running in incremental mode the task calculates loyalty metrics based on the full dataset, and then extracts only newly added guest_id/res_id records. These are written to ProcessedAddedGuestModel and ProcessedAddedReservationModel respectively.
During merge the added models are unioned into the existing Processed* models and deduplicated by guest_id and res_id.

Dependencies

This task must run after:

GuestMatchingTask (or GuestMatchingCheckTask) - Requires guest_cluster_id
ReservationMetricsTask - Requires stay_nights and booking_window

ProcessingTask - Parent orchestrator
GuestMatchingTask - Provides guest clusters
GuestLoyaltyReportTask - Uses loyalty metrics
ReservationMetricsTask - Prerequisite

Best Practices

Always run after guest matching to ensure accurate guest_cluster_id values
Monitor memory usage when processing large guest databases
Use checkpointing to prevent stack overflow with complex lineage
Validate stay counts match business expectations
Consider revenue columns may be optional depending on data source