Mutations#

A mutation is a query and a patch together. The query selects the entities, and the patch gives the new state of each one. Stardust commits every change in one transaction. Each example reads the same five entities as Queries.

The document#

A mutation document has query and patch. The query is an ordinary query, and the patch follows the form in Patches.

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 64657074	txt "dept"
1C	3C 6F7073	txt "ops"
20	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
35	0E 0D 00 0100 010000 00 20000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20
42	5C 7768657265	txt "where"
48	0F 0A 42000000 3500 0000	map leaf, size 10: @42 → @35
52	4C 66696E64	txt "find"
57	0F 0A 52000000 0700 0000	map leaf, size 10: @52 → @7
61	07 0E 0A000000 4800 0000 57000000	map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57
6F	6C 737461747573	txt "status"
76	6C 616374697665	txt "active"
7D	0F 0A 6F000000 7600 0000	map leaf, size 10: @6F → @76
87	2C 3F65	txt "?e"
8A	0F 0A 87000000 7D00 0000	map leaf, size 10: @87 → @7D
94	5C 7175657279	txt "query"
9A	0F 0A 94000000 6100 0000	map leaf, size 10: @94 → @61
A4	5C 7061746368	txt "patch"
AA	0F 0A A4000000 8A00 0000	map leaf, size 10: @A4 → @8A
B4	07 0E 40020000 9A00 0000 AA000000	map branch, size 14, depth 2, slots 6, 9: @9A → @AA
C2	07 0A 01000000 B400 0000	map branch, size 10, depth 1, slots 0: @B4
CC	07 0A 80000000 C200 0000	map branch, size 10, depth 0 (root), slots 7: @C2
D6	CC000000 00000000	root → @CC; previous: none

Each key of the patch is a target. A key that begins with ? uses an entity variable bound by the query. A key that begins with _ makes a new entity.

Preview and commit#

The native mutation run commits the selection and resolved patch together. The core also has a preview path that validates the same selection, resolution and store rules without writing facts. The public ABI does not currently expose that preview.

The result blocks on this page show the core report's status and counts. The public mutation result uses lowercase status names and also gives the commit time and generated entity ids.

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	9C 436F6D6D697474 6564	txt "Committed"
15	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1F	BC 7472616E736163 74696F6E	txt "transaction"
2B	02 07000000000000 00	i64 7
34	0F 0A 1F000000 2B00 0000	map leaf, size 10: @1F → @2B
3E	9C 67656E65726174 6564	txt "generated"
48	02 00000000000000 00	i64 0
51	0F 0A 3E000000 4800 0000	map leaf, size 10: @3E → @48
5B	5C 6661637473	txt "facts"
61	02 01000000000000 00	i64 1
6A	0F 0A 5B000000 6100 0000	map leaf, size 10: @5B → @61
74	07 16 01620000 1500 0000 34000000 5100 0000 6A000000	map branch, size 22, depth 0 (root), slots 0, 9, 13, 14: @15 → @34 → @51 → @6A
8A	74000000 00000000	root → @74; previous: none

The three statuses#

A second run of the same mutation changes nothing, so Stardust commits no new transaction.

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	9C 4E6F5F4368616E 6765	txt "No_Change"
15	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1F	BC 7472616E736163 74696F6E	txt "transaction"
2B	02 00000000000000 00	i64 0
34	0F 0A 1F000000 2B00 0000	map leaf, size 10: @1F → @2B
3E	9C 67656E65726174 6564	txt "generated"
48	02 00000000000000 00	i64 0
51	0F 0A 3E000000 4800 0000	map leaf, size 10: @3E → @48
5B	5C 6661637473	txt "facts"
61	02 00000000000000 00	i64 0
6A	0F 0A 5B000000 6100 0000	map leaf, size 10: @5B → @61
74	07 16 01620000 1500 0000 34000000 5100 0000 6A000000	map branch, size 22, depth 0 (root), slots 0, 9, 13, 14: @15 → @34 → @51 → @6A
8A	74000000 00000000	root → @74; previous: none

A selection that matches no entity gives the same counts. No entity is in the department legal:

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 64657074	txt "dept"
1C	5C 6C6567616C	txt "legal"
22	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
37	0E 0D 00 0100 010000 00 22000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @22
44	5C 7768657265	txt "where"
4A	0F 0A 44000000 3700 0000	map leaf, size 10: @44 → @37
54	4C 66696E64	txt "find"
59	0F 0A 54000000 0700 0000	map leaf, size 10: @54 → @7
63	07 0E 0A000000 4A00 0000 59000000	map branch, size 14, depth 0 (root), slots 1, 3: @4A → @59
71	6C 737461747573	txt "status"
78	6C 616374697665	txt "active"
7F	0F 0A 71000000 7800 0000	map leaf, size 10: @71 → @78
89	2C 3F65	txt "?e"
8C	0F 0A 89000000 7F00 0000	map leaf, size 10: @89 → @7F
96	5C 7175657279	txt "query"
9C	0F 0A 96000000 6300 0000	map leaf, size 10: @96 → @63
A6	5C 7061746368	txt "patch"
AC	0F 0A A6000000 8C00 0000	map leaf, size 10: @A6 → @8C
B6	07 0E 40020000 9C00 0000 AC000000	map branch, size 14, depth 2, slots 6, 9: @9C → @AC
C4	07 0A 01000000 B600 0000	map branch, size 10, depth 1, slots 0: @B6
CE	07 0A 80000000 C400 0000	map branch, size 10, depth 0 (root), slots 7: @C4
D8	CE000000 00000000	root → @CE; previous: none

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	8C 4E6F5F4D617463 68	txt "No_Match"
14	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1E	BC 7472616E736163 74696F6E	txt "transaction"
2A	02 00000000000000 00	i64 0
33	0F 0A 1E000000 2A00 0000	map leaf, size 10: @1E → @2A
3D	9C 67656E65726174 6564	txt "generated"
47	02 00000000000000 00	i64 0
50	0F 0A 3D000000 4700 0000	map leaf, size 10: @3D → @47
5A	5C 6661637473	txt "facts"
60	02 00000000000000 00	i64 0
69	0F 0A 5A000000 6000 0000	map leaf, size 10: @5A → @60
73	07 16 01620000 1400 0000 33000000 5000 0000 69000000	map branch, size 22, depth 0 (root), slots 0, 9, 13, 14: @14 → @33 → @50 → @69
89	73000000 00000000	root → @73; previous: none

New entities#

A target that begins with _ makes an entity. The selection must give exactly one row, because one new entity needs one parent row.

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 64657074	txt "dept"
1C	3C 6F7073	txt "ops"
20	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
35	0E 0D 00 0100 010000 00 20000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20
42	5C 7768657265	txt "where"
48	0F 0A 42000000 3500 0000	map leaf, size 10: @42 → @35
52	4C 66696E64	txt "find"
57	0F 0A 52000000 0700 0000	map leaf, size 10: @52 → @7
61	5C 6C696D6974	txt "limit"
67	02 01000000000000 00	i64 1
70	0F 0A 61000000 6700 0000	map leaf, size 10: @61 → @67
7A	07 12 2A000000 4800 0000 57000000 7000 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @48 → @57 → @70
8C	6C 737461747573	txt "status"
93	4C 73656564	txt "seed"
98	0F 0A 8C000000 9300 0000	map leaf, size 10: @8C → @93
A2	4C 5F6E6577	txt "_new"
A7	0F 0A A2000000 9800 0000	map leaf, size 10: @A2 → @98
B1	5C 7175657279	txt "query"
B7	0F 0A B1000000 7A00 0000	map leaf, size 10: @B1 → @7A
C1	5C 7061746368	txt "patch"
C7	0F 0A C1000000 A700 0000	map leaf, size 10: @C1 → @A7
D1	07 0E 40020000 B700 0000 C7000000	map branch, size 14, depth 2, slots 6, 9: @B7 → @C7
DF	07 0A 01000000 D100 0000	map branch, size 10, depth 1, slots 0: @D1
E9	07 0A 80000000 DF00 0000	map branch, size 10, depth 0 (root), slots 7: @DF
F3	E9000000 00000000	root → @E9; previous: none

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	9C 436F6D6D697474 6564	txt "Committed"
15	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1F	BC 7472616E736163 74696F6E	txt "transaction"
2B	02 09000000000000 00	i64 9
34	0F 0A 1F000000 2B00 0000	map leaf, size 10: @1F → @2B
3E	9C 67656E65726174 6564	txt "generated"
48	02 01000000000000 00	i64 1
51	0F 0A 3E000000 4800 0000	map leaf, size 10: @3E → @48
5B	5C 6661637473	txt "facts"
61	02 01000000000000 00	i64 1
6A	0F 0A 5B000000 6100 0000	map leaf, size 10: @5B → @61
74	07 16 01620000 1500 0000 34000000 5100 0000 6A000000	map branch, size 22, depth 0 (root), slots 0, 9, 13, 14: @15 → @34 → @51 → @6A
8A	74000000 00000000	root → @74; previous: none

The engine rejects the same patch against a selection of two rows. Two entities are in the department eng:

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 64657074	txt "dept"
1C	3C 656E67	txt "eng"
20	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
35	0E 0D 00 0100 010000 00 20000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20
42	5C 7768657265	txt "where"
48	0F 0A 42000000 3500 0000	map leaf, size 10: @42 → @35
52	4C 66696E64	txt "find"
57	0F 0A 52000000 0700 0000	map leaf, size 10: @52 → @7
61	07 0E 0A000000 4800 0000 57000000	map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57
6F	6C 737461747573	txt "status"
76	4C 73656564	txt "seed"
7B	0F 0A 6F000000 7600 0000	map leaf, size 10: @6F → @76
85	4C 5F6E6577	txt "_new"
8A	0F 0A 85000000 7B00 0000	map leaf, size 10: @85 → @7B
94	5C 7175657279	txt "query"
9A	0F 0A 94000000 6100 0000	map leaf, size 10: @94 → @61
A4	5C 7061746368	txt "patch"
AA	0F 0A A4000000 8A00 0000	map leaf, size 10: @A4 → @8A
B4	07 0E 40020000 9A00 0000 AA000000	map branch, size 14, depth 2, slots 6, 9: @9A → @AA
C2	07 0A 01000000 B400 0000	map branch, size 10, depth 1, slots 0: @B4
CC	07 0A 80000000 C200 0000	map branch, size 10, depth 0 (root), slots 7: @C2
D6	CC000000 00000000	root → @CC; previous: none

Patch values and variables#

The body for each target is a merge patch. It accepts every Stardust value: numbers, text, booleans, lists, maps, links and the other typed values. A null removes the field.

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	3C 616765	txt "age"
08	02 05000000000000 00	i64 5
11	0F 0A 04000000 0800 0000	map leaf, size 10: @4 → @8
1B	2C 3F65	txt "?e"
1E	0F 0A 1B000000 1100 0000	map leaf, size 10: @1B → @11
28	5C 7061746368	txt "patch"
2E	0F 0A 28000000 1E00 0000	map leaf, size 10: @28 → @1E
38	2E000000 00000000	root → @2E; previous: none

This sets age to 5 on every entity bound to ?e.

The query may bind a patch variable in where or expose it through find. Both forms refer to the same row binding. A variable used as a patch target must bind an entity. A variable used as a field value substitutes its complete bound value.

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	7C 3F737461747573	txt "?status"
00C	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
019	2C 3F65	txt "?e"
01C	6C 737461747573	txt "status"
023	7C 3F737461747573	txt "?status"
02B	0E 15 00 0700 030000 00 19000000 1C0000 00 23000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @19 → @1C → @23
040	1C 3D	txt "="
042	7C 3F737461747573	txt "?status"
04A	7C 70656E64696E67	txt "pending"
052	0E 15 00 0700 030000 00 40000000 420000 00 4A000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @40 → @42 → @4A
067	6C 3F6F776E6572	txt "?owner"
06E	4C 6E616D65	txt "name"
073	3C 416461	txt "Ada"
077	0E 15 00 0700 030000 00 67000000 6E0000 00 73000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @67 → @6E → @73
08C	0E 15 00 0700 030000 00 2B000000 520000 00 77000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @2B → @52 → @77
0A1	5C 7768657265	txt "where"
0A7	0F 0A A1000000 8C00 0000	map leaf, size 10: @A1 → @8C
0B1	4C 66696E64	txt "find"
0B6	0F 0A B1000000 0C00 0000	map leaf, size 10: @B1 → @C
0C0	07 0E 0A000000 A700 0000 B6000000	map branch, size 14, depth 0 (root), slots 1, 3: @A7 → @B6
0CE	6C 737461747573	txt "status"
0D5	6C 616374697665	txt "active"
0DC	0F 0A CE000000 D500 0000	map leaf, size 10: @CE → @D5
0E6	5C 6F776E6572	txt "owner"
0EC	6C 3F6F776E6572	txt "?owner"
0F3	0F 0A E6000000 EC00 0000	map leaf, size 10: @E6 → @EC
0FD	07 0E 03000000 DC00 0000 F3000000	map branch, size 14, depth 0 (root), slots 0, 1: @DC → @F3
10B	2C 3F65	txt "?e"
10E	0F 0A 0B010000 FD00 0000	map leaf, size 10: @10B → @FD
118	5C 7175657279	txt "query"
11E	0F 0A 18010000 C000 0000	map leaf, size 10: @118 → @C0
128	5C 7061746368	txt "patch"
12E	0F 0A 28010000 0E01 0000	map leaf, size 10: @128 → @10E
138	07 0E 40020000 1E01 0000 2E010000	map branch, size 14, depth 2, slots 6, 9: @11E → @12E
146	07 0A 01000000 3801 0000	map branch, size 10, depth 1, slots 0: @138
150	07 0A 80000000 4601 0000	map branch, size 10, depth 0 (root), slots 7: @146
15A	50010000 00000000	root → @150; previous: none

Stardust rejects a mutation with a malformed patch or an unbound variable. It also rejects a target that does not bind an entity or writes a protected stardust/* field. An invalid typed value or a result that violates the selected schema also causes rejection.

A mutation cannot write a definition. Stardust rejects a definition target with Definition_Target. Definitions include schemas, queries and mutations. A patch that writes stardust/type also gives Definition_Target. The preview gives the same error, and no fact changes. Use the definition API to change a definition.

Run it#

mutation run.