Pagination Patterns

Tutorial

Pagination Patterns

Navigate large result sets with the PaginatedList API

15 min Beginner

PaginationPaginatedListFilteringSorting

What You'll Learn

• Paginated Responses - Understand PaginatedList properties: items, total, has_more, page_count
• Iteration & Indexing - Iterate, index, and measure pages with Python protocols
• Paging Through Results - Walk through all pages with offset/limit loops
• Filtering, Sorting & Search - Narrow results server-side by status, name, or field order

1

Setup

Connect to the platform and provision tutorial data

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running

# Cell 2 — Connect
from graph_olap import GraphOLAPClient
client = GraphOLAPClient(username=USERNAME)

# Cell 3 — Provision
from notebook_setup import provision
personas, conn = provision(USERNAME)
analyst = personas["analyst"]
admin = personas["admin"]
ops = personas["ops"]
client = analyst

print(f"Connected | {conn.query_scalar('MATCH (n) RETURN count(n)')} nodes")

2

Understanding PaginatedList

Inspect the properties every list endpoint returns

# List mappings with a small page size
page = client.mappings.list(limit=2, offset=0)

print(f"Items on page: {len(page.items)}")
print(f"Total items:   {page.total}")
print(f"Offset:        {page.offset}")
print(f"Limit:         {page.limit}")
print(f"Has more:      {page.has_more}")
print(f"Page count:    {page.page_count}")

3

Iterating and Indexing

Use Python protocols to work with page contents

# Direct iteration
for mapping in page:
    print(f"  [{mapping.id}] {mapping.name}")

# Length
print(f"\nItems in page: {len(page)}")

# Index access
first = page[0]
print(f"First item: {first.name}")

4

Paging Through All Results

Walk every page with an offset/limit loop

# Collect all mappings across pages
all_mappings = []
offset = 0
limit = 10

while True:
    page = client.mappings.list(limit=limit, offset=offset)
    all_mappings.extend(page.items)
    if not page.has_more:
        break
    offset += limit

print(f"Retrieved {len(all_mappings)} mappings across {(len(all_mappings) + limit - 1) // limit} pages")
for m in all_mappings[:5]:
    print(f"  [{m.id}] {m.name}")
if len(all_mappings) > 5:
    print(f"  ... and {len(all_mappings) - 5} more")

5

Filtering and Searching

Narrow results server-side before they reach your code

# Search by name pattern
results = client.mappings.list(search="customer")
print(f"Mappings matching 'customer': {results.total}")
for m in results:
    print(f"  [{m.id}] {m.name}")

# Filter instances by status
running = client.instances.list(status="running", limit=5)
print(f"Running instances: {running.total}")
for inst in running:
    print(f"  [{inst.id}] {inst.name} ({inst.status})")

6

Sorting

Control the order of results with sort_by and sort_order

# Sort mappings by name
sorted_page = client.mappings.list(sort_by="name", sort_order="asc", limit=5)
print("Mappings sorted by name:")
for m in sorted_page:
    print(f"  [{m.id}] {m.name}")

# Sort by creation date (newest first)
recent = client.mappings.list(sort_by="created_at", sort_order="desc", limit=3)
print("\nMost recent mappings:")
for m in recent:
    print(f"  [{m.id}] {m.name} (created {m.created_at})")

Key Takeaways

• All list endpoints return PaginatedList with .items, .total, .has_more, and .page_count
• Use offset and limit to page through large result sets
• Filter by status, search by name, and sort by any field to find what you need
• PaginatedList supports direct iteration, len(), and index access