Skip to content

API Reference

Health water intake module for managing user hydration data.

This module provides CRUD operations and data models for user water intake tracking including daily consumption amounts and data sources.

Exports
  • CRUD: get_health_water_number_by_user_id, get_health_water_by_id_and_user_id, get_health_water_by_user_id, get_health_water_by_date_and_user_id, create_health_water, edit_health_water, delete_health_water
  • Schemas: HealthWaterBase, HealthWaterCreate, HealthWaterUpdate, HealthWaterRead, HealthWaterListResponse
  • Enums: Source
  • Models: HealthWater (ORM model)

HealthWaterBase

Bases: BaseModel

Base model for health water intake data.

Attributes:

Name Type Description
date date | None

Calendar date of the water intake record.
amount_ml StrictFloat | None

Water consumed in milliliters.
source Source | None

Source of the water intake data.
Source code in backend/app/health/health_water/schema.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
class HealthWaterBase(BaseModel):
    """
    Base model for health water intake data.

    Attributes:
        date: Calendar date of the water intake record.
        amount_ml: Water consumed in milliliters.
        source: Source of the water intake data.
    """

    date: datetime_date | None = Field(
        default=None,
        description="Calendar date of the water intake",
    )
    amount_ml: StrictFloat | None = Field(
        default=None,
        ge=0,
        le=20000,
        description="Water consumed in milliliters",
    )
    source: Source | None = Field(
        default=None,
        description="Source of the water intake data",
    )

    model_config = ConfigDict(
        from_attributes=True,
        extra="forbid",
        validate_assignment=True,
        use_enum_values=True,
    )

HealthWaterCreate

Bases: HealthWaterBase

Schema for creating a new water intake record.

Automatically sets the date to today if not provided.

Source code in backend/app/health/health_water/schema.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
class HealthWaterCreate(HealthWaterBase):
    """
    Schema for creating a new water intake record.

    Automatically sets the date to today if not provided.
    """

    @model_validator(mode="after")
    def set_default_date(self) -> "HealthWaterCreate":
        """
        Set date to today if not provided.

        Returns:
            The validated model instance with date set.
        """
        if self.date is None:
            self.date = datetime_date.today()
        return self

set_default_date 

set_default_date()

Set date to today if not provided.

Returns:

Type Description
HealthWaterCreate

The validated model instance with date set.
Source code in backend/app/health/health_water/schema.py 
75
76
77
78
79
80
81
82
83
84
85
@model_validator(mode="after")
def set_default_date(self) -> "HealthWaterCreate":
    """
    Set date to today if not provided.

    Returns:
        The validated model instance with date set.
    """
    if self.date is None:
        self.date = datetime_date.today()
    return self

HealthWaterListResponse

Bases: HealthListResponse

Response model for listing health water intake records.

Attributes:

Name Type Description
records list[HealthWaterRead]

A list of HealthWaterRead objects representing individual water intake records.
Source code in backend/app/health/health_water/schema.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
class HealthWaterListResponse(health_schema.HealthListResponse):
    """
    Response model for listing health water intake records.

    Attributes:
        records: A list of HealthWaterRead objects representing
            individual water intake records.
    """

    records: list[HealthWaterRead] = Field(
        ...,
        description="List of health water intake records",
    )

HealthWaterModel

Bases: Base

User daily water intake tracking data.

Attributes:

Name Type Description
id Mapped[int]

Primary key, auto-incremented unique identifier.
user_id Mapped[int]

Foreign key referencing users.id.
date Mapped[date]

Calendar date for the water intake record.
amount_ml Mapped[Decimal]

Total water consumed in milliliters.
source Mapped[str | None]

Source of the water intake data.
user Mapped[str | None]

Relationship to the Users model.
Table

health_water

Relationships
  • Many-to-One with Users model through user_id
Source code in backend/app/health/health_water/models.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
class HealthWater(Base):
    """
    User daily water intake tracking data.

    Attributes:
        id: Primary key, auto-incremented unique identifier.
        user_id: Foreign key referencing users.id.
        date: Calendar date for the water intake record.
        amount_ml: Total water consumed in milliliters.
        source: Source of the water intake data.
        user: Relationship to the Users model.

    Table:
        health_water

    Relationships:
        - Many-to-One with Users model through user_id
    """

    __tablename__ = "health_water"

    id: Mapped[int] = mapped_column(
        primary_key=True,
        autoincrement=True,
    )
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
        comment="User ID that the health_water belongs",
    )
    date: Mapped[date_type] = mapped_column(
        nullable=False,
        index=True,
        comment="Health water intake date (date)",
    )
    amount_ml: Mapped[Decimal] = mapped_column(
        Numeric(precision=10, scale=2),
        nullable=False,
        comment="Water consumed in milliliters",
    )
    source: Mapped[str | None] = mapped_column(
        String(250),
        nullable=True,
        comment="Source of the health water data",
    )

    # Define a relationship to the Users model
    users: Mapped["Users"] = relationship(back_populates="health_water")

HealthWaterRead

Bases: HealthWaterBase

Schema for reading a water intake record.

Attributes:

Name Type Description
id StrictInt

Unique identifier for the water intake record.
user_id StrictInt

Foreign key reference to the user.
Source code in backend/app/health/health_water/schema.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
class HealthWaterRead(HealthWaterBase):
    """
    Schema for reading a water intake record.

    Attributes:
        id: Unique identifier for the water intake record.
        user_id: Foreign key reference to the user.
    """

    id: StrictInt = Field(
        ...,
        description=(
            "Unique identifier for the water"
            " intake record"
        ),
    )
    user_id: StrictInt = Field(
        ...,
        description="Foreign key reference to the user",
    )

HealthWaterUpdate

Bases: HealthWaterRead

Schema for updating a water intake record.

Inherits from HealthWaterRead for consistency with read operations while allowing modifications to water intake data.

Source code in backend/app/health/health_water/schema.py 
110
111
112
113
114
115
116
class HealthWaterUpdate(HealthWaterRead):
    """
    Schema for updating a water intake record.

    Inherits from HealthWaterRead for consistency with read
    operations while allowing modifications to water intake data.
    """

Source

Bases: Enum

Enumeration of data sources for water intake records.

Attributes:

Name Type Description
MANUAL

Manually entered water intake data.
GARMIN

Garmin fitness tracking platform as a data source.
Source code in backend/app/health/health_water/schema.py 
22
23
24
25
26
27
28
29
30
31
32
class Source(Enum):
    """
    Enumeration of data sources for water intake records.

    Attributes:
        MANUAL: Manually entered water intake data.
        GARMIN: Garmin fitness tracking platform as a data source.
    """

    MANUAL = "manual"
    GARMIN = "garmin"

create_health_water 

create_health_water(user_id, health_water, db)

Create a new water intake record for a user.

Parameters:

Name Type Description Default
user_id int

User ID for the record owner.

 required
health_water HealthWaterCreate

Water intake data to create.

 required
db Session

Database session.

 required

Returns:

Type Description
HealthWater

Created water intake record.

Raises:

Type Description
HTTPException

If duplicate entry or database error.
Source code in backend/app/health/health_water/crud.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
@core_decorators.handle_db_errors
def create_health_water(
    user_id: int,
    health_water: health_water_schema.HealthWaterCreate,
    db: Session,
) -> health_water_models.HealthWater:
    """
    Create a new water intake record for a user.

    Args:
        user_id: User ID for the record owner.
        health_water: Water intake data to create.
        db: Database session.

    Returns:
        Created water intake record.

    Raises:
        HTTPException: If duplicate entry or database error.
    """
    try:
        db_health_water = health_water_models.HealthWater(
            **health_water.model_dump(exclude_none=False),
            user_id=user_id,
        )

        db.add(db_health_water)
        db.commit()
        db.refresh(db_health_water)

        return db_health_water
    except IntegrityError as integrity_error:
        db.rollback()

        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail=(
                "Duplicate entry error. Check if there is"
                " already an entry created for"
                f" {health_water.date}"
            ),
        ) from integrity_error

delete_health_water 

delete_health_water(user_id, health_water_id, db)

Delete a water intake record for a user.

Parameters:

Name Type Description Default
user_id int

User ID who owns the record.

 required
health_water_id int

Water intake record ID to delete.

 required
db Session

Database session.

 required

Returns:

Type Description
None

None

Raises:

Type Description
HTTPException

If record not found or database error.
Source code in backend/app/health/health_water/crud.py 
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
@core_decorators.handle_db_errors
def delete_health_water(
    user_id: int, health_water_id: int, db: Session
) -> None:
    """
    Delete a water intake record for a user.

    Args:
        user_id: User ID who owns the record.
        health_water_id: Water intake record ID to delete.
        db: Database session.

    Returns:
        None

    Raises:
        HTTPException: If record not found or database error.
    """
    db_health_water = get_health_water_by_id_and_user_id(
        health_water_id, user_id, db
    )

    if db_health_water is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Health water intake not found",
        ) from None

    db.delete(db_health_water)
    db.commit()

edit_health_water 

edit_health_water(user_id, health_water, db)

Edit water intake record for a user.

Parameters:

Name Type Description Default
user_id int

User ID who owns the record.

 required
health_water HealthWaterUpdate

Water intake data to update.

 required
db Session

Database session.

 required

Returns:

Type Description
HealthWater

Updated HealthWater model.

Raises:

Type Description
HTTPException

403 if editing another user's record, 404 if not found, 500 if database error.
Source code in backend/app/health/health_water/crud.py 
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
@core_decorators.handle_db_errors
def edit_health_water(
    user_id: int,
    health_water: health_water_schema.HealthWaterUpdate,
    db: Session,
) -> health_water_models.HealthWater:
    """
    Edit water intake record for a user.

    Args:
        user_id: User ID who owns the record.
        health_water: Water intake data to update.
        db: Database session.

    Returns:
        Updated HealthWater model.

    Raises:
        HTTPException: 403 if editing another user's record,
            404 if not found, 500 if database error.
    """
    if health_water.user_id != user_id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail=(
                "Cannot edit health water intake"
                " for another user."
            ),
        )

    db_health_water = get_health_water_by_id_and_user_id(
        health_water.id, user_id, db
    )

    if db_health_water is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Health water intake not found",
        ) from None

    health_water_data = health_water.model_dump(
        exclude_unset=True
    )
    for key, value in health_water_data.items():
        setattr(db_health_water, key, value)

    db.commit()
    db.refresh(db_health_water)

    return db_health_water

get_health_water_by_date_and_user_id 

get_health_water_by_date_and_user_id(user_id, date, db)

Retrieve water intake record for a user on a specific date.

Parameters:

Name Type Description Default
user_id int

User ID.

 required
date str

Date string for the water intake record.

 required
db Session

Database session.

 required

Returns:

Type Description
HealthWater | None

HealthWater model if found, None otherwise.

Raises:

Type Description
HTTPException

If database error occurs.
Source code in backend/app/health/health_water/crud.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
@core_decorators.handle_db_errors
def get_health_water_by_date_and_user_id(
    user_id: int, date: str, db: Session
) -> health_water_models.HealthWater | None:
    """
    Retrieve water intake record for a user on a specific date.

    Args:
        user_id: User ID.
        date: Date string for the water intake record.
        db: Database session.

    Returns:
        HealthWater model if found, None otherwise.

    Raises:
        HTTPException: If database error occurs.
    """
    stmt = select(health_water_models.HealthWater).where(
        health_water_models.HealthWater.date
        == func.date(date),
        health_water_models.HealthWater.user_id == user_id,
    )
    return db.execute(stmt).scalar_one_or_none()

get_health_water_by_id_and_user_id 

get_health_water_by_id_and_user_id(health_water_id, user_id, db)

Retrieve water intake record by ID and user ID.

Parameters:

Name Type Description Default
health_water_id int

Water intake record ID to fetch.

 required
user_id int

User ID to fetch record for.

 required
db Session

Database session.

 required

Returns:

Type Description
HealthWater | None

HealthWater model if found, None otherwise.

Raises:

Type Description
HTTPException

If database error occurs.
Source code in backend/app/health/health_water/crud.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@core_decorators.handle_db_errors
def get_health_water_by_id_and_user_id(
    health_water_id: int, user_id: int, db: Session
) -> health_water_models.HealthWater | None:
    """
    Retrieve water intake record by ID and user ID.

    Args:
        health_water_id: Water intake record ID to fetch.
        user_id: User ID to fetch record for.
        db: Database session.

    Returns:
        HealthWater model if found, None otherwise.

    Raises:
        HTTPException: If database error occurs.
    """
    stmt = select(health_water_models.HealthWater).where(
        health_water_models.HealthWater.id == health_water_id,
        health_water_models.HealthWater.user_id == user_id,
    )
    return db.execute(stmt).scalar_one_or_none()

get_health_water_by_user_id 

get_health_water_by_user_id(user_id, db, page_number=None, num_records=None, interval=None)

Retrieve water intake records for a user with optional pagination and filtering.

Parameters:

Name Type Description Default
user_id int

User ID whose records are to be retrieved.

 required
db Session

Database session used to execute the query.

 required
page_number int | None

Page number for pagination (1-indexed).

 None
num_records int | None

Number of records per page.

 None
interval Interval | None

Time interval to filter records.

 None

Returns:

Type Description
list[HealthWater]

List of HealthWater records sorted by date descending.
Source code in backend/app/health/health_water/crud.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@core_decorators.handle_db_errors
def get_health_water_by_user_id(
    user_id: int,
    db: Session,
    page_number: int | None = None,
    num_records: int | None = None,
    interval: health_constants.Interval | None = None,
) -> list[health_water_models.HealthWater]:
    """
    Retrieve water intake records for a user with optional
    pagination and filtering.

    Args:
        user_id: User ID whose records are to be retrieved.
        db: Database session used to execute the query.
        page_number: Page number for pagination (1-indexed).
        num_records: Number of records per page.
        interval: Time interval to filter records.

    Returns:
        List of HealthWater records sorted by date descending.
    """
    stmt = select(health_water_models.HealthWater).where(
        health_water_models.HealthWater.user_id == user_id
    )

    if interval is not None:
        stmt = stmt.where(
            health_water_models.HealthWater.date
            >= health_utils.get_start_date_for_interval(
                interval.value
            )
        )

    stmt = stmt.order_by(
        desc(health_water_models.HealthWater.date)
    )

    if page_number is not None and num_records is not None:
        stmt = stmt.offset(
            (page_number - 1) * num_records
        ).limit(num_records)

    return db.execute(stmt).scalars().all()

get_health_water_number_by_user_id 

get_health_water_number_by_user_id(user_id, db, interval=None)

Retrieve total count of water intake records for a user.

If interval is provided, count only records starting from the calculated start date.

Parameters:

Name Type Description Default
user_id int

User ID to count records for.

 required
db Session

Database session.

 required
interval Interval | None

Optional filter by goal interval.

 None

Returns:

Type Description
int

Total number of health water intake records.

Raises:

Type Description
HTTPException

If database error occurs.
Source code in backend/app/health/health_water/crud.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@core_decorators.handle_db_errors
def get_health_water_number_by_user_id(
    user_id: int,
    db: Session,
    interval: health_constants.Interval | None = None,
) -> int:
    """
    Retrieve total count of water intake records for a user.

    If interval is provided, count only records starting from
    the calculated start date.

    Args:
        user_id: User ID to count records for.
        db: Database session.
        interval: Optional filter by goal interval.

    Returns:
        Total number of health water intake records.

    Raises:
        HTTPException: If database error occurs.
    """
    stmt = (
        select(func.count())
        .select_from(health_water_models.HealthWater)
        .where(
            health_water_models.HealthWater.user_id == user_id
        )
    )

    if interval is not None:
        stmt = stmt.where(
            health_water_models.HealthWater.date
            >= health_utils.get_start_date_for_interval(
                interval.value
            )
        )

    return db.execute(stmt).scalar_one()