Ordering & pagination

Ordering

Use the Order builder — you shouldn't have to know the field;DIRECTION grammar. (Planned; entity-handles phase 4.)

from boostspace import Order
bs.spaces.list(order=Order.by("name", "ASC"))                 # name;ASC
bs.spaces.list(order=Order.by("color", "ASC").by("id", "DESC")) # color;ASC,id;DESC

bs.spaces.list({ order: Order.by("color", "ASC").by("id", "DESC") });

$bs->spaces->list(order: (string) Order::by('color', 'ASC')->thenBy('id', 'DESC'));

bs.Spaces.List(ctx, boostspace.ListParams{Order: boostspace.OrderBy("color", "ASC").By("id", "DESC").String()})

A plain string is still accepted, so the raw grammar below stays an escape hatch.

Raw grammar (reference)

order is a comma-separated list of field;DIRECTION pairs (note the semicolon between field and direction, comma between pairs):

order = field ";" ("ASC"|"DESC") ( "," field ";" ("ASC"|"DESC") )*

• DIRECTION defaults to DESC when omitted (order=id = order=id;DESC).
• Multiple keys sort primary, then secondary.

Verified live (GET /space, IDs shown):

> Common mistake: a space (order=id ASC) is not the separator — the > direction is dropped and you get the default DESC. Use order=id;ASC.

Pagination

• offset — zero-based index of the first record (default 0).
• limit — page size (default 100).
• The total match count is not in the body; it comes from the X-BoostSpace-FoundRecords response header. The SDK surfaces it on the page.

You rarely page by hand — every list returns a paginator that fetches pages lazily as you iterate:

for space in bs.spaces.list(order="name;ASC"):   # streams all pages
    print(space.id)

page = bs.spaces.list(limit=50).page()              # one page + total
print(page.items, page.found_records)

for await (const s of bs.spaces.list({ order: "name;ASC" })) { /* … */ }
const page = await bs.spaces.list({ limit: 50 }).page();

foreach ($bs->spaces->list(order: 'name;ASC') as $s) { /* … */ }
$page = $bs->spaces->list(limit: 50)->page();       // ['items'=>…, 'found'=>…]

it := bs.Spaces.List(ctx, boostspace.ListParams{Order: "name;ASC"})
for it.Next(ctx) { c := it.Value(); _ = c }

One API call per page — see each list method's Cost: line.