statedb: Clarify primary index key requirements

[gandro]

The primary index seems to have the requirement that every object must have not less and not more than one key.

[github-actions]

$ make
go build ./...
go: downloading go1.24.0 (linux/amd64)
go: downloading go.yaml.in/yaml/v3 v3.0.3
go: downloading github.com/cilium/hive v0.0.0-20250731144630-28e7a35ed227
go: downloading golang.org/x/time v0.5.0
go: downloading github.com/spf13/cobra v1.8.0
go: downloading github.com/spf13/pflag v1.0.5
go: downloading github.com/cilium/stream v0.0.0-20240209152734-a0792b51812d
go: downloading github.com/liggitt/tabwriter v0.0.0-20181228230101-89fcab3d43de
go: downloading github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc
go: downloading github.com/mitchellh/mapstructure v1.5.0
go: downloading go.uber.org/dig v1.17.1
go: downloading golang.org/x/term v0.16.0
go: downloading github.com/spf13/viper v1.18.2
go: downloading golang.org/x/sys v0.17.0
go: downloading golang.org/x/tools v0.17.0
go: downloading github.com/spf13/cast v1.6.0
go: downloading github.com/fsnotify/fsnotify v1.7.0
go: downloading github.com/sagikazarmark/slog-shim v0.1.0
go: downloading github.com/spf13/afero v1.11.0
go: downloading golang.org/x/text v0.14.0
go: downloading github.com/subosito/gotenv v1.6.0
go: downloading github.com/hashicorp/hcl v1.0.0
go: downloading gopkg.in/ini.v1 v1.67.0
go: downloading github.com/magiconair/properties v1.8.7
go: downloading github.com/pelletier/go-toml/v2 v2.1.0
go: downloading gopkg.in/yaml.v3 v3.0.1
go test ./... -cover -vet=all -test.count 1
go: downloading github.com/stretchr/testify v1.8.4
go: downloading go.uber.org/goleak v1.3.0
go: downloading golang.org/x/exp v0.0.0-20240119083558-1b970713d09a
go: downloading github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2
ok  	github.com/cilium/statedb	21.375s	coverage: 80.9% of statements
ok  	github.com/cilium/statedb/index	0.005s	coverage: 28.7% of statements
ok  	github.com/cilium/statedb/internal	0.012s	coverage: 46.7% of statements
ok  	github.com/cilium/statedb/part	4.344s	coverage: 87.2% of statements
ok  	github.com/cilium/statedb/reconciler	0.246s	coverage: 89.8% of statements
	github.com/cilium/statedb/reconciler/benchmark		coverage: 0.0% of statements
	github.com/cilium/statedb/reconciler/example		coverage: 0.0% of statements
go test -race ./... -test.count 1
ok  	github.com/cilium/statedb	100.091s
ok  	github.com/cilium/statedb/index	1.013s
ok  	github.com/cilium/statedb/internal	1.022s
ok  	github.com/cilium/statedb/part	35.063s
ok  	github.com/cilium/statedb/reconciler	1.319s
?   	github.com/cilium/statedb/reconciler/benchmark	[no test files]
?   	github.com/cilium/statedb/reconciler/example	[no test files]
go test ./... -bench . -benchmem -test.run xxx
goos: linux
goarch: amd64
pkg: github.com/cilium/statedb
cpu: AMD EPYC 7763 64-Core Processor                
BenchmarkDB_WriteTxn_1-4                    	  512080	      2204 ns/op	    453781 objects/sec	    1416 B/op	      26 allocs/op
BenchmarkDB_WriteTxn_10-4                   	 1422604	       836.9 ns/op	   1194831 objects/sec	     481 B/op	       9 allocs/op
BenchmarkDB_WriteTxn_100-4                  	 1911850	       626.9 ns/op	   1595094 objects/sec	     400 B/op	       7 allocs/op
BenchmarkDB_WriteTxn_1000-4                 	 1809440	       695.9 ns/op	   1437046 objects/sec	     363 B/op	       7 allocs/op
BenchmarkDB_WriteTxn_100_SecondaryIndex-4   	  543096	      1987 ns/op	    503201 objects/sec	    1212 B/op	      37 allocs/op
BenchmarkDB_NewWriteTxn-4                   	 1517793	       790.3 ns/op	     544 B/op	       8 allocs/op
BenchmarkDB_NewReadTxn-4                    	549283254	         2.204 ns/op	       0 B/op	       0 allocs/op
BenchmarkDB_Modify-4                        	    1683	    719655 ns/op	   1389554 objects/sec	  422364 B/op	    8142 allocs/op
BenchmarkDB_GetInsert-4                     	    1497	    812460 ns/op	   1230830 objects/sec	  403529 B/op	    8139 allocs/op
BenchmarkDB_RandomInsert-4                  	    1737	    701467 ns/op	   1425583 objects/sec	  397914 B/op	    7142 allocs/op
BenchmarkDB_RandomReplace-4                 	     373	   3231665 ns/op	    309438 objects/sec	 1977101 B/op	   49162 allocs/op
BenchmarkDB_SequentialInsert-4              	    1857	    665101 ns/op	   1503532 objects/sec	  363867 B/op	    7113 allocs/op
BenchmarkDB_SequentialInsert_Prefix-4       	     403	   2972803 ns/op	    336383 objects/sec	 3718037 B/op	   58568 allocs/op
BenchmarkDB_Changes_Baseline-4              	    1411	    848138 ns/op	   1179054 objects/sec	  433520 B/op	   10214 allocs/op
BenchmarkDB_Changes-4                       	     805	   1504471 ns/op	    664686 objects/sec	  755643 B/op	   14420 allocs/op
BenchmarkDB_RandomLookup-4                  	   21392	     56142 ns/op	  17811862 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_SequentialLookup-4              	   24859	     48118 ns/op	  20782235 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_Prefix_SecondaryIndex-4         	    6776	    162474 ns/op	   6154814 objects/sec	  125114 B/op	    1031 allocs/op
BenchmarkDB_FullIteration_All-4             	    1174	   1032221 ns/op	  96878456 objects/sec	     320 B/op	      11 allocs/op
BenchmarkDB_FullIteration_Get-4             	     202	   5834902 ns/op	  17138250 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_FullIteration_ReadTxnGet-4      	     186	   6448956 ns/op	  15506386 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_PropagationDelay-4              	  606074	      1986 ns/op	        17.00 50th_µs	        20.00 90th_µs	        41.00 99th_µs	    1070 B/op	      22 allocs/op
BenchmarkWatchSet_4-4                       	 1340059	       894.9 ns/op	     499 B/op	       7 allocs/op
BenchmarkWatchSet_16-4                      	  487068	      2368 ns/op	    1700 B/op	       8 allocs/op
BenchmarkWatchSet_128-4                     	   62210	     19263 ns/op	   13400 B/op	       8 allocs/op
BenchmarkWatchSet_1024-4                    	    6582	    192694 ns/op	  105779 B/op	       8 allocs/op
PASS
ok  	github.com/cilium/statedb	33.731s
PASS
ok  	github.com/cilium/statedb/index	0.003s
PASS
ok  	github.com/cilium/statedb/internal	0.003s
goos: linux
goarch: amd64
pkg: github.com/cilium/statedb/part
cpu: AMD EPYC 7763 64-Core Processor                
Benchmark_Uint64Map_Random-4        	    1303	    893999 ns/op	   1118569 items/sec	 2812267 B/op	   11038 allocs/op
Benchmark_Uint64Map_Sequential-4    	    1424	    833980 ns/op	   1199069 items/sec	 2591251 B/op	   11749 allocs/op
Benchmark_Insert_RootOnlyWatch-4    	    9636	    123885 ns/op	   8071979 objects/sec	   74539 B/op	    2044 allocs/op
Benchmark_Insert-4                  	    6792	    174763 ns/op	   5722020 objects/sec	  190512 B/op	    3076 allocs/op
Benchmark_Modify-4                  	   12092	     99129 ns/op	  10087911 objects/sec	   72133 B/op	    1028 allocs/op
Benchmark_GetInsert-4               	    8284	    141811 ns/op	   7051639 objects/sec	   72101 B/op	    1028 allocs/op
Benchmark_Replace-4                 	27401271	        43.63 ns/op	  22917591 objects/sec	       0 B/op	       0 allocs/op
Benchmark_Replace_RootOnlyWatch-4   	27726579	        43.01 ns/op	  23251809 objects/sec	       0 B/op	       0 allocs/op
Benchmark_txn_1-4                   	 3279399	       368.2 ns/op	   2715710 objects/sec	     280 B/op	       5 allocs/op
Benchmark_txn_10-4                  	 8464184	       140.3 ns/op	   7129599 objects/sec	      97 B/op	       2 allocs/op
Benchmark_txn_100-4                 	10604710	       114.1 ns/op	   8768019 objects/sec	      91 B/op	       2 allocs/op
Benchmark_txn_1000-4                	 9546181	       124.5 ns/op	   8030973 objects/sec	      78 B/op	       2 allocs/op
Benchmark_txn_delete_1-4            	 1544848	       774.8 ns/op	   1290728 objects/sec	    3272 B/op	       8 allocs/op
Benchmark_txn_delete_10-4           	 7209302	       165.9 ns/op	   6026003 objects/sec	     368 B/op	       2 allocs/op
Benchmark_txn_delete_100-4          	11046649	       107.1 ns/op	   9335621 objects/sec	      82 B/op	       1 allocs/op
Benchmark_txn_delete_1000-4         	11863478	       100.6 ns/op	   9939987 objects/sec	      28 B/op	       1 allocs/op
Benchmark_Get-4                     	   33079	     36540 ns/op	  27367413 objects/sec	       0 B/op	       0 allocs/op
Benchmark_Iterate-4                 	  162078	      7502 ns/op	 133291815 objects/sec	     104 B/op	       4 allocs/op
Benchmark_Hashmap_Insert-4          	   14907	     80601 ns/op	  12406812 objects/sec	   74265 B/op	      20 allocs/op
Benchmark_Hashmap_Get_Uint64-4      	  137428	      8694 ns/op	 115015310 objects/sec	       0 B/op	       0 allocs/op
Benchmark_Hashmap_Get_Bytes-4       	  111522	     10750 ns/op	  93026712 objects/sec	       0 B/op	       0 allocs/op
PASS
ok  	github.com/cilium/statedb/part	27.035s
PASS
ok  	github.com/cilium/statedb/reconciler	0.004s
?   	github.com/cilium/statedb/reconciler/benchmark	[no test files]
?   	github.com/cilium/statedb/reconciler/example	[no test files]
go run ./reconciler/benchmark -quiet
1000000 objects reconciled in 2.35 seconds (batch size 1000)
Throughput 424943.94 objects per second
1137MB total allocated, 6011131 in-use objects, 338MB bytes in use

[pippolo84]

Thanks!

I guess we should follow up enforcing this with a panic. Might be worth open an issue?

[gandro]

Something that came to my mind later: Does this restriction also apply to non-primary unique indices? My current superficial understanding is that this restriction exists mainly on the primary index, but not for other unique indices.

[joamaki]

Something that came to my mind later: Does this restriction also apply to non-primary unique indices? My current superficial understanding is that this restriction exists mainly on the primary index, but not for other unique indices.

In non-primary unique indexes you can return multiple keys and they'd all be inserted. We haven't seen a use-case for that yet, but I'm sure there is one.