Cursor pagination

Cursor pagination

Cursor pagination là một chiến lược phân trang sử dụng một token mờ (một "cursor") để đánh dấu vị trí trong tập kết quả thay vì dựa vào các offset số như page=2 hoặc offset=100. Client gửi cursor trở lại server (ví dụ qua tham số after_cursor) để yêu cầu trang tiếp theo. Server trả về một cursor mới cho trang kế tiếp trong phản hồi.

In context

Polymarket's Gamma /markets endpoint yêu cầu phân trang theo cursor: các cuộc gọi phải sử dụng giá trị after_cursor trả về từ yêu cầu trước thay vì tham số offset. Cách tiếp cận kiểu keyset này cải thiện hiệu năng và tính nhất quán trên các tập kết quả lớn hoặc thay đổi thường xuyên vì server có thể tiếp tục từ một vị trí ổn định mà không phải quét lại từ đầu cho mỗi trang. Gamma trả về một next_cursor trong mỗi phản hồi phân trang; cung cấp giá trị đó làm after_cursor để lấy trang tiếp theo.

Practical notes

• Opaque token: Xem cursor như một chuỗi không được kiểm tra. Đừng cố gắng phân tích hay tạo nó ở phía client.
• No numeric offset: Gamma API từ chối offset số; dùng after_cursor để phân trang với /markets. Endpoint hỗ trợ limit (tối đa 1000) cùng với after_cursor.
• Ordering matters: Phân trang bằng cursor phụ thuộc vào thứ tự truy vấn. Nếu bạn thay đổi các trường sắp xếp, bạn có thể không tiếp tục được bằng cursor trước đó.
• Robust clients: Lưu các cursor nếu bạn định tiếp tục một quét dài, và xử lý trường hợp một cursor trước đó trở nên cũ hoặc không trả về kết quả.

See also

• /glossary/gamma-api