Skip to content

Commit 8019a2e

Browse files
committed
feat: add pagination support to DatabaseSessionService.list_sessions
Add page_size and page_token parameters to list_sessions across all session service implementations (DatabaseSessionService, InMemorySessionService, SqliteSessionService, VertexAiSessionService). - page_size defaults to 20, clamped to max 100 - page_token is base64-encoded offset for stateless cursor pagination - Results ordered by update_time DESC (most recent first) - ListSessionsResponse gains next_page_token field - Fully backward compatible: existing callers without pagination args get the first page (up to 20 sessions) Closes google#4621
1 parent 8f54281 commit 8019a2e

6 files changed

Lines changed: 328 additions & 27 deletions

File tree

‎src/google/adk/sessions/base_session_service.py‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
from __future__ import annotations
1616

1717
import abc
18+
import base64
1819
from typing import Any
1920
from typing import Optional
2021

@@ -25,6 +26,29 @@
2526
from .session import Session
2627
from .state import State
2728

29+
_DEFAULT_PAGE_SIZE = 20
30+
_MAX_PAGE_SIZE = 100
31+
32+
33+
def _resolve_page_size(page_size: Optional[int]) -> int:
34+
"""Clamp *page_size* to [1, _MAX_PAGE_SIZE], defaulting to _DEFAULT_PAGE_SIZE."""
35+
if page_size is None:
36+
return _DEFAULT_PAGE_SIZE
37+
return max(1, min(page_size, _MAX_PAGE_SIZE))
38+
39+
40+
def _encode_page_token(offset: int) -> str:
41+
return base64.b64encode(str(offset).encode()).decode()
42+
43+
44+
def _decode_page_token(token: Optional[str]) -> int:
45+
if not token:
46+
return 0
47+
try:
48+
return max(0, int(base64.b64decode(token).decode()))
49+
except (ValueError, Exception):
50+
return 0
51+
2852

2953
class GetSessionConfig(BaseModel):
3054
"""The configuration of getting a session."""
@@ -40,6 +64,7 @@ class ListSessionsResponse(BaseModel):
4064
"""
4165

4266
sessions: list[Session] = Field(default_factory=list)
67+
next_page_token: Optional[str] = None
4368

4469

4570
class BaseSessionService(abc.ABC):
@@ -83,17 +108,27 @@ async def get_session(
83108

84109
@abc.abstractmethod
85110
async def list_sessions(
86-
self, *, app_name: str, user_id: Optional[str] = None
111+
self,
112+
*,
113+
app_name: str,
114+
user_id: Optional[str] = None,
115+
page_size: Optional[int] = None,
116+
page_token: Optional[str] = None,
87117
) -> ListSessionsResponse:
88-
"""Lists all the sessions for a user.
118+
"""Lists sessions, optionally filtered by user, with pagination.
89119
90120
Args:
91121
app_name: The name of the app.
92122
user_id: The ID of the user. If not provided, lists all sessions for all
93123
users.
124+
page_size: Maximum number of sessions to return per page. Defaults to 20,
125+
maximum 100.
126+
page_token: Token returned from a previous ``list_sessions`` call to
127+
fetch the next page.
94128
95129
Returns:
96-
A ListSessionsResponse containing the sessions.
130+
A ListSessionsResponse containing the sessions and an optional
131+
``next_page_token`` for fetching subsequent pages.
97132
"""
98133

99134
@abc.abstractmethod

‎src/google/adk/sessions/database_session_service.py‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@
4343
from .base_session_service import BaseSessionService
4444
from .base_session_service import GetSessionConfig
4545
from .base_session_service import ListSessionsResponse
46+
from .base_session_service import _decode_page_token
47+
from .base_session_service import _encode_page_token
48+
from .base_session_service import _resolve_page_size
4649
from .migration import _schema_check_utils
4750
from .schemas.v0 import Base as BaseV0
4851
from .schemas.v0 import StorageAppState as StorageAppStateV0
@@ -453,19 +456,36 @@ async def get_session(
453456

454457
@override
455458
async def list_sessions(
456-
self, *, app_name: str, user_id: Optional[str] = None
459+
self,
460+
*,
461+
app_name: str,
462+
user_id: Optional[str] = None,
463+
page_size: Optional[int] = None,
464+
page_token: Optional[str] = None,
457465
) -> ListSessionsResponse:
458466
await self._prepare_tables()
459467
schema = self._get_schema_classes()
468+
469+
effective_page_size = _resolve_page_size(page_size)
470+
offset = _decode_page_token(page_token)
471+
460472
async with self._rollback_on_exception_session() as sql_session:
461473
stmt = select(schema.StorageSession).filter(
462474
schema.StorageSession.app_name == app_name
463475
)
464476
if user_id is not None:
465477
stmt = stmt.filter(schema.StorageSession.user_id == user_id)
466478

479+
stmt = stmt.order_by(schema.StorageSession.update_time.desc())
480+
# Fetch one extra row to determine if there is a next page.
481+
stmt = stmt.offset(offset).limit(effective_page_size + 1)
482+
467483
result = await sql_session.execute(stmt)
468-
results = result.scalars().all()
484+
results = list(result.scalars().all())
485+
486+
has_next_page = len(results) > effective_page_size
487+
if has_next_page:
488+
results = results[:effective_page_size]
469489

470490
# Fetch app state from storage
471491
storage_app_state = await sql_session.get(
@@ -499,7 +519,15 @@ async def list_sessions(
499519
sessions.append(
500520
storage_session.to_session(state=merged_state, is_sqlite=is_sqlite)
501521
)
502-
return ListSessionsResponse(sessions=sessions)
522+
523+
next_page_token = (
524+
_encode_page_token(offset + effective_page_size)
525+
if has_next_page
526+
else None
527+
)
528+
return ListSessionsResponse(
529+
sessions=sessions, next_page_token=next_page_token
530+
)
503531

504532
@override
505533
async def delete_session(

‎src/google/adk/sessions/in_memory_session_service.py‎

Lines changed: 60 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,9 @@
2828
from .base_session_service import BaseSessionService
2929
from .base_session_service import GetSessionConfig
3030
from .base_session_service import ListSessionsResponse
31+
from .base_session_service import _decode_page_token
32+
from .base_session_service import _encode_page_token
33+
from .base_session_service import _resolve_page_size
3134
from .session import Session
3235
from .state import State
3336

@@ -220,42 +223,86 @@ def _merge_state(
220223

221224
@override
222225
async def list_sessions(
223-
self, *, app_name: str, user_id: Optional[str] = None
226+
self,
227+
*,
228+
app_name: str,
229+
user_id: Optional[str] = None,
230+
page_size: Optional[int] = None,
231+
page_token: Optional[str] = None,
224232
) -> ListSessionsResponse:
225-
return self._list_sessions_impl(app_name=app_name, user_id=user_id)
233+
return self._list_sessions_impl(
234+
app_name=app_name,
235+
user_id=user_id,
236+
page_size=page_size,
237+
page_token=page_token,
238+
)
226239

227240
def list_sessions_sync(
228-
self, *, app_name: str, user_id: Optional[str] = None
241+
self,
242+
*,
243+
app_name: str,
244+
user_id: Optional[str] = None,
245+
page_size: Optional[int] = None,
246+
page_token: Optional[str] = None,
229247
) -> ListSessionsResponse:
230248
logger.warning('Deprecated. Please migrate to the async method.')
231-
return self._list_sessions_impl(app_name=app_name, user_id=user_id)
249+
return self._list_sessions_impl(
250+
app_name=app_name,
251+
user_id=user_id,
252+
page_size=page_size,
253+
page_token=page_token,
254+
)
232255

233256
def _list_sessions_impl(
234-
self, *, app_name: str, user_id: Optional[str] = None
257+
self,
258+
*,
259+
app_name: str,
260+
user_id: Optional[str] = None,
261+
page_size: Optional[int] = None,
262+
page_token: Optional[str] = None,
235263
) -> ListSessionsResponse:
236264
empty_response = ListSessionsResponse()
237265
if app_name not in self.sessions:
238266
return empty_response
239267
if user_id is not None and user_id not in self.sessions[app_name]:
240268
return empty_response
241269

242-
sessions_without_events = []
270+
all_sessions = []
243271

244272
if user_id is None:
245-
for user_id in self.sessions[app_name]:
246-
for session_id in self.sessions[app_name][user_id]:
247-
session = self.sessions[app_name][user_id][session_id]
273+
for uid in self.sessions[app_name]:
274+
for session_id in self.sessions[app_name][uid]:
275+
session = self.sessions[app_name][uid][session_id]
248276
copied_session = copy.deepcopy(session)
249277
copied_session.events = []
250-
copied_session = self._merge_state(app_name, user_id, copied_session)
251-
sessions_without_events.append(copied_session)
278+
copied_session = self._merge_state(app_name, uid, copied_session)
279+
all_sessions.append(copied_session)
252280
else:
253281
for session in self.sessions[app_name][user_id].values():
254282
copied_session = copy.deepcopy(session)
255283
copied_session.events = []
256284
copied_session = self._merge_state(app_name, user_id, copied_session)
257-
sessions_without_events.append(copied_session)
258-
return ListSessionsResponse(sessions=sessions_without_events)
285+
all_sessions.append(copied_session)
286+
287+
# Sort by last_update_time descending (most recently updated first)
288+
all_sessions.sort(
289+
key=lambda s: s.last_update_time if s.last_update_time else 0,
290+
reverse=True,
291+
)
292+
293+
effective_page_size = _resolve_page_size(page_size)
294+
offset = _decode_page_token(page_token)
295+
296+
page = all_sessions[offset : offset + effective_page_size]
297+
has_next_page = (offset + effective_page_size) < len(all_sessions)
298+
next_page_token = (
299+
_encode_page_token(offset + effective_page_size)
300+
if has_next_page
301+
else None
302+
)
303+
return ListSessionsResponse(
304+
sessions=page, next_page_token=next_page_token
305+
)
259306

260307
@override
261308
async def delete_session(

‎src/google/adk/sessions/sqlite_session_service.py‎

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@
3535
from .base_session_service import BaseSessionService
3636
from .base_session_service import GetSessionConfig
3737
from .base_session_service import ListSessionsResponse
38+
from .base_session_service import _decode_page_token
39+
from .base_session_service import _encode_page_token
40+
from .base_session_service import _resolve_page_size
3841
from .session import Session
3942
from .state import State
4043

@@ -292,24 +295,38 @@ async def get_session(
292295

293296
@override
294297
async def list_sessions(
295-
self, *, app_name: str, user_id: Optional[str] = None
298+
self,
299+
*,
300+
app_name: str,
301+
user_id: Optional[str] = None,
302+
page_size: Optional[int] = None,
303+
page_token: Optional[str] = None,
296304
) -> ListSessionsResponse:
305+
effective_page_size = _resolve_page_size(page_size)
306+
offset = _decode_page_token(page_token)
307+
297308
sessions_list = []
298309
async with self._get_db_connection() as db:
299-
# Fetch sessions
310+
# Fetch sessions with ORDER BY / LIMIT / OFFSET
300311
if user_id:
301312
session_rows = await db.execute_fetchall(
302313
"SELECT id, user_id, state, update_time FROM sessions WHERE"
303-
" app_name=? AND user_id=?",
304-
(app_name, user_id),
314+
" app_name=? AND user_id=?"
315+
" ORDER BY update_time DESC LIMIT ? OFFSET ?",
316+
(app_name, user_id, effective_page_size + 1, offset),
305317
)
306318
else:
307319
session_rows = await db.execute_fetchall(
308320
"SELECT id, user_id, state, update_time FROM sessions WHERE"
309-
" app_name=?",
310-
(app_name,),
321+
" app_name=?"
322+
" ORDER BY update_time DESC LIMIT ? OFFSET ?",
323+
(app_name, effective_page_size + 1, offset),
311324
)
312325

326+
has_next_page = len(session_rows) > effective_page_size
327+
if has_next_page:
328+
session_rows = session_rows[:effective_page_size]
329+
313330
# Fetch app state
314331
app_state = await self._get_app_state(db, app_name)
315332

@@ -343,7 +360,15 @@ async def list_sessions(
343360
last_update_time=row["update_time"],
344361
)
345362
)
346-
return ListSessionsResponse(sessions=sessions_list)
363+
364+
next_page_token = (
365+
_encode_page_token(offset + effective_page_size)
366+
if has_next_page
367+
else None
368+
)
369+
return ListSessionsResponse(
370+
sessions=sessions_list, next_page_token=next_page_token
371+
)
347372

348373
@override
349374
async def delete_session(

‎src/google/adk/sessions/vertex_ai_session_service.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,12 @@ async def get_session(
201201

202202
@override
203203
async def list_sessions(
204-
self, *, app_name: str, user_id: Optional[str] = None
204+
self,
205+
*,
206+
app_name: str,
207+
user_id: Optional[str] = None,
208+
page_size: Optional[int] = None,
209+
page_token: Optional[str] = None,
205210
) -> ListSessionsResponse:
206211
reasoning_engine_id = self._get_reasoning_engine_id(app_name)
207212

0 commit comments

Comments
 (0)