Ordering and paging

Grouping calculates values over related rows. orderBy sets the order of those rows. distinct removes repeated rows. offset and limit cut a window from the ordered rows. page reads a long result in stable parts. Each example reads the same five entities as Queries.

Order

Each orderBy entry is a variable, or a variable with a direction. A variable without a direction uses ascending order. An entry can also be an expression. Stardust calculates it for each row and sorts the rows by the result.

TRON235 B
Offset (hex)Bytes (hex)Meaning
0054 52 4F 4Emagic TRON
045C 3F6E616D65txt "?name"
0A4C 3F73616Ctxt "?sal"
0F0E 11 00 0300 020000 00 04000000 0A0000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @4 → @A
202C 3F65txt "?e"
236C 73616C617279txt "salary"
2A4C 3F73616Ctxt "?sal"
2F0E 15 00 0700 030000 00 20000000 230000 00 2A000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @20 → @23 → @2A
442C 3F65txt "?e"
474C 6E616D65txt "name"
4C5C 3F6E616D65txt "?name"
520E 15 00 0700 030000 00 44000000 470000 00 4C000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @44 → @47 → @4C
670E 11 00 0300 020000 00 2F000000 520000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @2F → @52
784C 3F73616Ctxt "?sal"
7D4C 64657363txt "desc"
820E 11 00 0300 020000 00 78000000 7D0000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @78 → @7D
930E 0D 00 0100 010000 00 82000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @82
A05C 7768657265txt "where"
A60F 0A A0000000 6700 0000map leaf, size 10: @A0 → @67
B04C 66696E64txt "find"
B50F 0A B0000000 0F00 0000map leaf, size 10: @B0 → @F
BF7C 6F726465724279txt "orderBy"
C70F 0A BF000000 9300 0000map leaf, size 10: @BF → @93
D107 12 2A000000 A600 0000 B5000000 C700 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @A6 → @B5 → @C7
TRON320 B
Offset (hex)Bytes (hex)Meaning
00054 52 4F 4Emagic TRON
0043C 73616Ctxt "sal"
00802 78000000000000 00i64 120
0110F 0A 04000000 0800 0000map leaf, size 10: @4 → @8
01B4C 6E616D65txt "name"
0203C 416461txt "Ada"
0240F 0A 1B000000 2000 0000map leaf, size 10: @1B → @20
02E07 0E 80800000 1100 0000 24000000map branch, size 14, depth 0 (root), slots 7, 15: @11 → @24
03C3C 73616Ctxt "sal"
04002 64000000000000 00i64 100
0490F 0A 3C000000 4000 0000map leaf, size 10: @3C → @40
0534C 6E616D65txt "name"
0583C 426F62txt "Bob"
05C0F 0A 53000000 5800 0000map leaf, size 10: @53 → @58
06607 0E 80800000 4900 0000 5C000000map branch, size 14, depth 0 (root), slots 7, 15: @49 → @5C
0743C 73616Ctxt "sal"
07802 5A000000000000 00i64 90
0810F 0A 74000000 7800 0000map leaf, size 10: @74 → @78
08B4C 6E616D65txt "name"
0902C 4379txt "Cy"
0930F 0A 8B000000 9000 0000map leaf, size 10: @8B → @90
09D07 0E 80800000 8100 0000 93000000map branch, size 14, depth 0 (root), slots 7, 15: @81 → @93
0AB3C 73616Ctxt "sal"
0AF02 50000000000000 00i64 80
0B80F 0A AB000000 AF00 0000map leaf, size 10: @AB → @AF
0C24C 6E616D65txt "name"
0C73C 457665txt "Eve"
0CB0F 0A C2000000 C700 0000map leaf, size 10: @C2 → @C7
0D507 0E 80800000 B800 0000 CB000000map branch, size 14, depth 0 (root), slots 7, 15: @B8 → @CB
0E33C 73616Ctxt "sal"
0E702 46000000000000 00i64 70
0F00F 0A E3000000 E700 0000map leaf, size 10: @E3 → @E7
0FA4C 6E616D65txt "name"
0FF3C 44616Etxt "Dan"
1030F 0A FA000000 FF00 0000map leaf, size 10: @FA → @FF
10D07 0E 80800000 F000 0000 03010000map branch, size 14, depth 0 (root), slots 7, 15: @F0 → @103
11B0E 1D 00 1F00 050000 00 2E000000 660000 00 9D000000 D50000 00 0D010000array leaf, size 29, shift 0, bitmap 001F, count 5 (root): @2E → @66 → @9D → @D5 → @10D

asc and desc are the two directions. Several entries make several sort keys, and the first entry is the strongest.

TRON285 B
Offset (hex)Bytes (hex)Meaning
00054 52 4F 4Emagic TRON
0045C 3F64657074txt "?dept"
00A5C 3F6E616D65txt "?name"
0100E 11 00 0300 020000 00 04000000 0A0000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @4 → @A
0212C 3F65txt "?e"
0244C 64657074txt "dept"
0295C 3F64657074txt "?dept"
02F0E 15 00 0700 030000 00 21000000 240000 00 29000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @21 → @24 → @29
0442C 3F65txt "?e"
0476C 73616C617279txt "salary"
04E4C 3F73616Ctxt "?sal"
0530E 15 00 0700 030000 00 44000000 470000 00 4E000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @44 → @47 → @4E
0682C 3F65txt "?e"
06B4C 6E616D65txt "name"
0705C 3F6E616D65txt "?name"
0760E 15 00 0700 030000 00 68000000 6B0000 00 70000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @68 → @6B → @70
08B0E 15 00 0700 030000 00 2F000000 530000 00 76000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @2F → @53 → @76
0A04C 3F73616Ctxt "?sal"
0A54C 64657363txt "desc"
0AA0E 11 00 0300 020000 00 A0000000 A50000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @A0 → @A5
0BB5C 3F64657074txt "?dept"
0C10E 11 00 0300 020000 00 BB000000 AA0000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @BB → @AA
0D25C 7768657265txt "where"
0D80F 0A D2000000 8B00 0000map leaf, size 10: @D2 → @8B
0E24C 66696E64txt "find"
0E70F 0A E2000000 1000 0000map leaf, size 10: @E2 → @10
0F17C 6F726465724279txt "orderBy"
0F90F 0A F1000000 C100 0000map leaf, size 10: @F1 → @C1
10307 12 2A000000 D800 0000 E7000000 F900 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @D8 → @E7 → @F9
TRON304 B
Offset (hex)Bytes (hex)Meaning
00054 52 4F 4Emagic TRON
0044C 64657074txt "dept"
0093C 656E67txt "eng"
00D0F 0A 04000000 0900 0000map leaf, size 10: @4 → @9
0174C 6E616D65txt "name"
01C3C 416461txt "Ada"
0200F 0A 17000000 1C00 0000map leaf, size 10: @17 → @1C
02A07 0E 00900000 0D00 0000 20000000map branch, size 14, depth 0 (root), slots 12, 15: @D → @20
0384C 64657074txt "dept"
03D3C 656E67txt "eng"
0410F 0A 38000000 3D00 0000map leaf, size 10: @38 → @3D
04B4C 6E616D65txt "name"
0503C 426F62txt "Bob"
0540F 0A 4B000000 5000 0000map leaf, size 10: @4B → @50
05E07 0E 00900000 4100 0000 54000000map branch, size 14, depth 0 (root), slots 12, 15: @41 → @54
06C4C 64657074txt "dept"
0713C 6F7073txt "ops"
0750F 0A 6C000000 7100 0000map leaf, size 10: @6C → @71
07F4C 6E616D65txt "name"
0843C 457665txt "Eve"
0880F 0A 7F000000 8400 0000map leaf, size 10: @7F → @84
09207 0E 00900000 7500 0000 88000000map branch, size 14, depth 0 (root), slots 12, 15: @75 → @88
0A04C 64657074txt "dept"
0A55C 73616C6573txt "sales"
0AB0F 0A A0000000 A500 0000map leaf, size 10: @A0 → @A5
0B54C 6E616D65txt "name"
0BA2C 4379txt "Cy"
0BD0F 0A B5000000 BA00 0000map leaf, size 10: @B5 → @BA
0C707 0E 00900000 AB00 0000 BD000000map branch, size 14, depth 0 (root), slots 12, 15: @AB → @BD
0D54C 64657074txt "dept"
0DA5C 73616C6573txt "sales"
0E00F 0A D5000000 DA00 0000map leaf, size 10: @D5 → @DA
0EA4C 6E616D65txt "name"
0EF3C 44616Etxt "Dan"
0F30F 0A EA000000 EF00 0000map leaf, size 10: @EA → @EF
0FD07 0E 00900000 E000 0000 F3000000map branch, size 14, depth 0 (root), slots 12, 15: @E0 → @F3
10B0E 1D 00 1F00 050000 00 2A000000 5E0000 00 92000000 C70000 00 FD000000array leaf, size 29, shift 0, bitmap 001F, count 5 (root): @2A → @5E → @92 → @C7 → @FD

Distinct

distinct true keeps the first row of each set of equal rows. It compares the find columns, and it respects the type of each value. The integer 1 and the number 1.0 are two different values.

Stardust can drop a repeated partial result during a where join. No later clause, find column or ordering key can read the distinguishing variables. Aggregates, grouping, windows and projection prevent this optimization. The result rows remain the same. A join that reaches one answer along many paths does the work once.

TRON199 B
Offset (hex)Bytes (hex)Meaning
0054 52 4F 4Emagic TRON
045C 3F64657074txt "?dept"
0A0E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
172C 3F65txt "?e"
1A4C 64657074txt "dept"
1F5C 3F64657074txt "?dept"
250E 15 00 0700 030000 00 17000000 1A0000 00 1F000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A0E 0D 00 0100 010000 00 25000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
475C 3F64657074txt "?dept"
4D0E 0D 00 0100 010000 00 47000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A5C 7768657265txt "where"
600F 0A 5A000000 3A00 0000map leaf, size 10: @5A → @3A
6A4C 66696E64txt "find"
6F0F 0A 6A000000 0A00 0000map leaf, size 10: @6A → @A
798C 64697374696E63 74txt "distinct"
8209bit true
830F 0A 79000000 8200 0000map leaf, size 10: @79 → @82
8D7C 6F726465724279txt "orderBy"
950F 0A 8D000000 4D00 0000map leaf, size 10: @8D → @4D
9F07 0E 00090000 8300 0000 95000000map branch, size 14, depth 1, slots 8, 11: @83 → @95
AD07 12 2A000000 6000 0000 6F000000 9F00 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @9F
TRON92 B
Offset (hex)Bytes (hex)Meaning
0054 52 4F 4Emagic TRON
044C 64657074txt "dept"
093C 656E67txt "eng"
0D0F 0A 04000000 0900 0000map leaf, size 10: @4 → @9
174C 64657074txt "dept"
1C3C 6F7073txt "ops"
200F 0A 17000000 1C00 0000map leaf, size 10: @17 → @1C
2A4C 64657074txt "dept"
2F5C 73616C6573txt "sales"
350F 0A 2A000000 2F00 0000map leaf, size 10: @2A → @2F
3F0E 15 00 0700 030000 00 0D000000 200000 00 35000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @35

Offset and limit

offset and limit are counts of rows, and each one accepts 0 or more. Stardust applies them after orderBy and after distinct.

TRON274 B
Offset (hex)Bytes (hex)Meaning
00054 52 4F 4Emagic TRON
0045C 3F6E616D65txt "?name"
00A0E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
0172C 3F65txt "?e"
01A6C 73616C617279txt "salary"
0214C 3F73616Ctxt "?sal"
0260E 15 00 0700 030000 00 17000000 1A0000 00 21000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @21
03B2C 3F65txt "?e"
03E4C 6E616D65txt "name"
0435C 3F6E616D65txt "?name"
0490E 15 00 0700 030000 00 3B000000 3E0000 00 43000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @3B → @3E → @43
05E0E 11 00 0300 020000 00 26000000 490000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @26 → @49
06F5C 3F6E616D65txt "?name"
0750E 0D 00 0100 010000 00 6F000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @6F
0825C 7768657265txt "where"
0880F 0A 82000000 5E00 0000map leaf, size 10: @82 → @5E
0924C 66696E64txt "find"
0970F 0A 92000000 0A00 0000map leaf, size 10: @92 → @A
0A17C 6F726465724279txt "orderBy"
0A90F 0A A1000000 7500 0000map leaf, size 10: @A1 → @75
0B35C 6C696D6974txt "limit"
0B902 02000000000000 00i64 2
0C20F 0A B3000000 B900 0000map leaf, size 10: @B3 → @B9
0CC07 0E 00280000 A900 0000 C2000000map branch, size 14, depth 1, slots 11, 13: @A9 → @C2
0DA6C 6F6666736574txt "offset"
0E102 02000000000000 00i64 2
0EA0F 0A DA000000 E100 0000map leaf, size 10: @DA → @E1
0F407 16 2A400000 8800 0000 97000000 CC00 0000 EA000000map branch, size 22, depth 0 (root), slots 1, 3, 5, 14: @88 → @97 → @CC → @EA
TRON66 B
Offset (hex)Bytes (hex)Meaning
0054 52 4F 4Emagic TRON
044C 6E616D65txt "name"
092C 4379txt "Cy"
0C0F 0A 04000000 0900 0000map leaf, size 10: @4 → @9
164C 6E616D65txt "name"
1B3C 44616Etxt "Dan"
1F0F 0A 16000000 1B00 0000map leaf, size 10: @16 → @1B
290E 11 00 0300 020000 00 0C000000 1F0000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @C → @1F

Pages

page reads a long result in parts. It has size, the number of rows in one page, and an optional after, the cursor of the page before it.

TRON258 B
Offset (hex)Bytes (hex)Meaning
00054 52 4F 4Emagic TRON
0045C 3F6E616D65txt "?name"
00A0E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
0172C 3F65txt "?e"
01A6C 73616C617279txt "salary"
0214C 3F73616Ctxt "?sal"
0260E 15 00 0700 030000 00 17000000 1A0000 00 21000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @21
03B2C 3F65txt "?e"
03E4C 6E616D65txt "name"
0435C 3F6E616D65txt "?name"
0490E 15 00 0700 030000 00 3B000000 3E0000 00 43000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @3B → @3E → @43
05E0E 11 00 0300 020000 00 26000000 490000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @26 → @49
06F5C 3F6E616D65txt "?name"
0750E 0D 00 0100 010000 00 6F000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @6F
0824C 73697A65txt "size"
08702 02000000000000 00i64 2
0900F 0A 82000000 8700 0000map leaf, size 10: @82 → @87
09A5C 7768657265txt "where"
0A00F 0A 9A000000 5E00 0000map leaf, size 10: @9A → @5E
0AA4C 66696E64txt "find"
0AF0F 0A AA000000 0A00 0000map leaf, size 10: @AA → @A
0B97C 6F726465724279txt "orderBy"
0C10F 0A B9000000 7500 0000map leaf, size 10: @B9 → @75
0CB4C 70616765txt "page"
0D00F 0A CB000000 9000 0000map leaf, size 10: @CB → @90
0DA07 0E 00280000 C100 0000 D0000000map branch, size 14, depth 1, slots 11, 13: @C1 → @D0
0E807 12 2A000000 A000 0000 AF000000 DA00 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @A0 → @AF → @DA
TRON67 B
Offset (hex)Bytes (hex)Meaning
0054 52 4F 4Emagic TRON
044C 6E616D65txt "name"
093C 416461txt "Ada"
0D0F 0A 04000000 0900 0000map leaf, size 10: @4 → @9
174C 6E616D65txt "name"
1C3C 426F62txt "Bob"
200F 0A 17000000 1C00 0000map leaf, size 10: @17 → @1C
2A0E 11 00 0300 020000 00 0D000000 200000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @D → @20

The reply carries hasMore. While more rows exist, it also carries nextCursor. The next page gives that cursor as after.

Copy the first page's cursor into the next query's page.after string. Stardust generates its value at runtime. It is not an entity name. Do not reuse a literal from this article.

A cursor holds the last row of the page and a fingerprint of the query. The fingerprint covers every part of the query except page. A cursor from a different query is Cursor_Mismatch, and a cursor that Stardust cannot open is Invalid_Cursor.

TRON301 B
Offset (hex)Bytes (hex)Meaning
00054 52 4F 4Emagic TRON
0045C 3F6E616D65txt "?name"
00A0E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
0172C 3F65txt "?e"
01A6C 73616C617279txt "salary"
0214C 3F73616Ctxt "?sal"
0260E 15 00 0700 030000 00 17000000 1A0000 00 21000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @21
03B2C 3F65txt "?e"
03E4C 6E616D65txt "name"
0435C 3F6E616D65txt "?name"
0490E 15 00 0700 030000 00 3B000000 3E0000 00 43000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @3B → @3E → @43
05E0E 11 00 0300 020000 00 26000000 490000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @26 → @49
06F5C 3F6E616D65txt "?name"
0750E 0D 00 0100 010000 00 6F000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @6F
0824C 73697A65txt "size"
08702 02000000000000 00i64 2
0900F 0A 82000000 8700 0000map leaf, size 10: @82 → @87
09A5C 6166746572txt "after"
0A0CC 6E6F742D612D63 7572736F72txt "not-a-cursor"
0AD0F 0A 9A000000 A000 0000map leaf, size 10: @9A → @A0
0B707 0E 00090000 9000 0000 AD000000map branch, size 14, depth 0 (root), slots 8, 11: @90 → @AD
0C55C 7768657265txt "where"
0CB0F 0A C5000000 5E00 0000map leaf, size 10: @C5 → @5E
0D54C 66696E64txt "find"
0DA0F 0A D5000000 0A00 0000map leaf, size 10: @D5 → @A
0E47C 6F726465724279txt "orderBy"
0EC0F 0A E4000000 7500 0000map leaf, size 10: @E4 → @75
0F64C 70616765txt "page"
0FB0F 0A F6000000 B700 0000map leaf, size 10: @F6 → @B7
10507 0E 00280000 EC00 0000 FB000000map branch, size 14, depth 1, slots 11, 13: @EC → @FB
11307 12 2A000000 CB00 0000 DA000000 0501 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @CB → @DA → @105

Error

Invalid_Cursor

When a page is rejected

A page boundary needs a total order, and it cannot share a query with the other window clauses.

ConditionReason
page without orderByA stable boundary needs a total order
page with limitlimit cuts the rows that page divides
page with offsetoffset moves the boundary of each page
page {size 0}size accepts 1 or more
page with projectA projected shape has no row boundary

Each of these conditions gives one error. This query has page and limit:

TRON297 B
Offset (hex)Bytes (hex)Meaning
00054 52 4F 4Emagic TRON
0045C 3F6E616D65txt "?name"
00A0E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
0172C 3F65txt "?e"
01A6C 73616C617279txt "salary"
0214C 3F73616Ctxt "?sal"
0260E 15 00 0700 030000 00 17000000 1A0000 00 21000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @21
03B2C 3F65txt "?e"
03E4C 6E616D65txt "name"
0435C 3F6E616D65txt "?name"
0490E 15 00 0700 030000 00 3B000000 3E0000 00 43000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @3B → @3E → @43
05E0E 11 00 0300 020000 00 26000000 490000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @26 → @49
06F5C 3F6E616D65txt "?name"
0750E 0D 00 0100 010000 00 6F000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @6F
0824C 73697A65txt "size"
08702 02000000000000 00i64 2
0900F 0A 82000000 8700 0000map leaf, size 10: @82 → @87
09A5C 7768657265txt "where"
0A00F 0A 9A000000 5E00 0000map leaf, size 10: @9A → @5E
0AA4C 66696E64txt "find"
0AF0F 0A AA000000 0A00 0000map leaf, size 10: @AA → @A
0B97C 6F726465724279txt "orderBy"
0C10F 0A B9000000 7500 0000map leaf, size 10: @B9 → @75
0CB5C 6C696D6974txt "limit"
0D102 02000000000000 00i64 2
0DA0F 0A CB000000 D100 0000map leaf, size 10: @CB → @D1
0E44C 70616765txt "page"
0E90F 0A E4000000 9000 0000map leaf, size 10: @E4 → @90
0F307 0E 01800000 DA00 0000 E9000000map branch, size 14, depth 2, slots 0, 15: @DA → @E9
10107 0E 00280000 C100 0000 F3000000map branch, size 14, depth 1, slots 11, 13: @C1 → @F3
10F07 12 2A000000 A000 0000 AF000000 0101 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @A0 → @AF → @101

Error

Invalid_Page

Bounds and history covers the limits on the work of a query.

Run it

database query · query run.