Open History to see the last commit
1---
2id: BTreeIndex
3title: BTreeIndex
4---
5
6# Class: BTreeIndex\<TKey\>
7
8Defined in: [packages/db/src/indexes/btree-index.ts:35](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L35)
9
10B+Tree index for sorted data with range queries
11This maintains items in sorted order and provides efficient range operations
12
13## Extends
14
15- [`BaseIndex`](BaseIndex.md)\<`TKey`\>
16
17## Type Parameters
18
19### TKey
20
21`TKey` *extends* `string` \| `number` = `string` \| `number`
22
23## Constructors
24
25### Constructor
26
27```ts
28new BTreeIndex<TKey>(
29 id,
30 expression,
31 name?,
32options?): BTreeIndex<TKey>;
33```
34
35Defined in: [packages/db/src/indexes/btree-index.ts:55](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L55)
36
37#### Parameters
38
39##### id
40
41`number`
42
43##### expression
44
45[`BasicExpression`](../@tanstack/namespaces/IR/type-aliases/BasicExpression.md)
46
47##### name?
48
49`string`
50
51##### options?
52
53`any`
54
55#### Returns
56
57`BTreeIndex`\<`TKey`\>
58
59#### Overrides
60
61[`BaseIndex`](BaseIndex.md).[`constructor`](BaseIndex.md#constructor)
62
63## Properties
64
65### compareOptions
66
67```ts
68protected compareOptions: CompareOptions;
69```
70
71Defined in: [packages/db/src/indexes/base-index.ts:101](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L101)
72
73#### Inherited from
74
75[`BaseIndex`](BaseIndex.md).[`compareOptions`](BaseIndex.md#compareoptions)
76
77***
78
79### expression
80
81```ts
82readonly expression: BasicExpression;
83```
84
85Defined in: [packages/db/src/indexes/base-index.ts:95](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L95)
86
87#### Inherited from
88
89[`BaseIndex`](BaseIndex.md).[`expression`](BaseIndex.md#expression)
90
91***
92
93### hasCustomComparator
94
95```ts
96protected hasCustomComparator: boolean = false;
97```
98
99Defined in: [packages/db/src/indexes/base-index.ts:106](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L106)
100
101Set by subclasses when constructed with a user-supplied comparator, whose
102ordering may not match the WHERE evaluator's relational operators.
103
104#### Inherited from
105
106[`BaseIndex`](BaseIndex.md).[`hasCustomComparator`](BaseIndex.md#hascustomcomparator)
107
108***
109
110### id
111
112```ts
113readonly id: number;
114```
115
116Defined in: [packages/db/src/indexes/base-index.ts:93](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L93)
117
118#### Inherited from
119
120[`BaseIndex`](BaseIndex.md).[`id`](BaseIndex.md#id)
121
122***
123
124### lastUpdated
125
126```ts
127protected lastUpdated: Date;
128```
129
130Defined in: [packages/db/src/indexes/base-index.ts:100](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L100)
131
132#### Inherited from
133
134[`BaseIndex`](BaseIndex.md).[`lastUpdated`](BaseIndex.md#lastupdated)
135
136***
137
138### lookupCount
139
140```ts
141protected lookupCount: number = 0;
142```
143
144Defined in: [packages/db/src/indexes/base-index.ts:98](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L98)
145
146#### Inherited from
147
148[`BaseIndex`](BaseIndex.md).[`lookupCount`](BaseIndex.md#lookupcount)
149
150***
151
152### name?
153
154```ts
155readonly optional name: string;
156```
157
158Defined in: [packages/db/src/indexes/base-index.ts:94](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L94)
159
160#### Inherited from
161
162[`BaseIndex`](BaseIndex.md).[`name`](BaseIndex.md#name)
163
164***
165
166### supportedOperations
167
168```ts
169readonly supportedOperations: Set<"eq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "ilike">;
170```
171
172Defined in: [packages/db/src/indexes/btree-index.ts:38](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L38)
173
174#### Overrides
175
176[`BaseIndex`](BaseIndex.md).[`supportedOperations`](BaseIndex.md#supportedoperations)
177
178***
179
180### totalLookupTime
181
182```ts
183protected totalLookupTime: number = 0;
184```
185
186Defined in: [packages/db/src/indexes/base-index.ts:99](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L99)
187
188#### Inherited from
189
190[`BaseIndex`](BaseIndex.md).[`totalLookupTime`](BaseIndex.md#totallookuptime)
191
192## Accessors
193
194### indexedKeysSet
195
196#### Get Signature
197
198```ts
199get indexedKeysSet(): Set<TKey>;
200```
201
202Defined in: [packages/db/src/indexes/btree-index.ts:410](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L410)
203
204##### Returns
205
206`Set`\<`TKey`\>
207
208#### Overrides
209
210[`BaseIndex`](BaseIndex.md).[`indexedKeysSet`](BaseIndex.md#indexedkeysset)
211
212***
213
214### keyCount
215
216#### Get Signature
217
218```ts
219get keyCount(): number;
220```
221
222Defined in: [packages/db/src/indexes/btree-index.ts:214](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L214)
223
224Gets the number of indexed keys
225
226##### Returns
227
228`number`
229
230#### Overrides
231
232[`BaseIndex`](BaseIndex.md).[`keyCount`](BaseIndex.md#keycount)
233
234***
235
236### orderedEntriesArray
237
238#### Get Signature
239
240```ts
241get orderedEntriesArray(): [any, Set<TKey>][];
242```
243
244Defined in: [packages/db/src/indexes/btree-index.ts:414](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L414)
245
246##### Returns
247
248\[`any`, `Set`\<`TKey`\>\][]
249
250#### Overrides
251
252[`BaseIndex`](BaseIndex.md).[`orderedEntriesArray`](BaseIndex.md#orderedentriesarray)
253
254***
255
256### orderedEntriesArrayReversed
257
258#### Get Signature
259
260```ts
261get orderedEntriesArrayReversed(): [any, Set<TKey>][];
262```
263
264Defined in: [packages/db/src/indexes/btree-index.ts:423](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L423)
265
266##### Returns
267
268\[`any`, `Set`\<`TKey`\>\][]
269
270#### Overrides
271
272[`BaseIndex`](BaseIndex.md).[`orderedEntriesArrayReversed`](BaseIndex.md#orderedentriesarrayreversed)
273
274***
275
276### supportsRangeOptimization
277
278#### Get Signature
279
280```ts
281get supportsRangeOptimization(): boolean;
282```
283
284Defined in: [packages/db/src/indexes/base-index.ts:161](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L161)
285
286Whether range lookups (gt/gte/lt/lte) on this index can be trusted to
287return every matching key. Range traversal relies on the index ordering, so
288it is unsafe when the index uses a custom comparator, whose order may not
289match the WHERE evaluator's relational operators. Callers must fall back to
290a full scan when this is `false`.
291
292##### Returns
293
294`boolean`
295
296#### Inherited from
297
298[`BaseIndex`](BaseIndex.md).[`supportsRangeOptimization`](BaseIndex.md#supportsrangeoptimization)
299
300***
301
302### valueMapData
303
304#### Get Signature
305
306```ts
307get valueMapData(): Map<any, Set<TKey>>;
308```
309
310Defined in: [packages/db/src/indexes/btree-index.ts:430](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L430)
311
312##### Returns
313
314`Map`\<`any`, `Set`\<`TKey`\>\>
315
316#### Overrides
317
318[`BaseIndex`](BaseIndex.md).[`valueMapData`](BaseIndex.md#valuemapdata)
319
320## Methods
321
322### add()
323
324```ts
325add(key, item): void;
326```
327
328Defined in: [packages/db/src/indexes/btree-index.ts:84](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L84)
329
330Adds a value to the index
331
332#### Parameters
333
334##### key
335
336`TKey`
337
338##### item
339
340`any`
341
342#### Returns
343
344`void`
345
346#### Overrides
347
348[`BaseIndex`](BaseIndex.md).[`add`](BaseIndex.md#add)
349
350***
351
352### build()
353
354```ts
355build(entries): void;
356```
357
358Defined in: [packages/db/src/indexes/btree-index.ts:158](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L158)
359
360Builds the index from a collection of entries
361
362#### Parameters
363
364##### entries
365
366`Iterable`\<\[`TKey`, `any`\]\>
367
368#### Returns
369
370`void`
371
372#### Overrides
373
374[`BaseIndex`](BaseIndex.md).[`build`](BaseIndex.md#build)
375
376***
377
378### clear()
379
380```ts
381clear(): void;
382```
383
384Defined in: [packages/db/src/indexes/btree-index.ts:169](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L169)
385
386Clears all data from the index
387
388#### Returns
389
390`void`
391
392#### Overrides
393
394[`BaseIndex`](BaseIndex.md).[`clear`](BaseIndex.md#clear)
395
396***
397
398### equalityLookup()
399
400```ts
401equalityLookup(value): Set<TKey>;
402```
403
404Defined in: [packages/db/src/indexes/btree-index.ts:223](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L223)
405
406Performs an equality lookup
407
408#### Parameters
409
410##### value
411
412`any`
413
414#### Returns
415
416`Set`\<`TKey`\>
417
418#### Overrides
419
420[`BaseIndex`](BaseIndex.md).[`equalityLookup`](BaseIndex.md#equalitylookup)
421
422***
423
424### evaluateIndexExpression()
425
426```ts
427protected evaluateIndexExpression(item): any;
428```
429
430Defined in: [packages/db/src/indexes/base-index.ts:212](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L212)
431
432#### Parameters
433
434##### item
435
436`any`
437
438#### Returns
439
440`any`
441
442#### Inherited from
443
444[`BaseIndex`](BaseIndex.md).[`evaluateIndexExpression`](BaseIndex.md#evaluateindexexpression)
445
446***
447
448### getStats()
449
450```ts
451getStats(): IndexStats;
452```
453
454Defined in: [packages/db/src/indexes/base-index.ts:200](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L200)
455
456#### Returns
457
458[`IndexStats`](../interfaces/IndexStats.md)
459
460#### Inherited from
461
462[`BaseIndex`](BaseIndex.md).[`getStats`](BaseIndex.md#getstats)
463
464***
465
466### inArrayLookup()
467
468```ts
469inArrayLookup(values): Set<TKey>;
470```
471
472Defined in: [packages/db/src/indexes/btree-index.ts:395](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L395)
473
474Performs an IN array lookup
475
476#### Parameters
477
478##### values
479
480`any`[]
481
482#### Returns
483
484`Set`\<`TKey`\>
485
486#### Overrides
487
488[`BaseIndex`](BaseIndex.md).[`inArrayLookup`](BaseIndex.md#inarraylookup)
489
490***
491
492### initialize()
493
494```ts
495protected initialize(_options?): void;
496```
497
498Defined in: [packages/db/src/indexes/btree-index.ts:79](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L79)
499
500#### Parameters
501
502##### \_options?
503
504`BTreeIndexOptions`
505
506#### Returns
507
508`void`
509
510#### Overrides
511
512[`BaseIndex`](BaseIndex.md).[`initialize`](BaseIndex.md#initialize)
513
514***
515
516### lookup()
517
518```ts
519lookup(operation, value): Set<TKey>;
520```
521
522Defined in: [packages/db/src/indexes/btree-index.ts:179](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L179)
523
524Performs a lookup operation
525
526#### Parameters
527
528##### operation
529
530`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
531
532##### value
533
534`any`
535
536#### Returns
537
538`Set`\<`TKey`\>
539
540#### Overrides
541
542[`BaseIndex`](BaseIndex.md).[`lookup`](BaseIndex.md#lookup)
543
544***
545
546### matchesCompareOptions()
547
548```ts
549matchesCompareOptions(compareOptions): boolean;
550```
551
552Defined in: [packages/db/src/indexes/base-index.ts:177](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L177)
553
554Checks if the compare options match the index's compare options.
555The direction is ignored because the index can be reversed if the direction is different.
556
557#### Parameters
558
559##### compareOptions
560
561`CompareOptions`
562
563#### Returns
564
565`boolean`
566
567#### Inherited from
568
569[`BaseIndex`](BaseIndex.md).[`matchesCompareOptions`](BaseIndex.md#matchescompareoptions)
570
571***
572
573### matchesDirection()
574
575```ts
576matchesDirection(direction): boolean;
577```
578
579Defined in: [packages/db/src/indexes/base-index.ts:196](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L196)
580
581Checks if the index matches the provided direction.
582
583#### Parameters
584
585##### direction
586
587[`OrderByDirection`](../@tanstack/namespaces/IR/type-aliases/OrderByDirection.md)
588
589#### Returns
590
591`boolean`
592
593#### Inherited from
594
595[`BaseIndex`](BaseIndex.md).[`matchesDirection`](BaseIndex.md#matchesdirection)
596
597***
598
599### matchesField()
600
601```ts
602matchesField(fieldPath): boolean;
603```
604
605Defined in: [packages/db/src/indexes/base-index.ts:165](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L165)
606
607#### Parameters
608
609##### fieldPath
610
611`string`[]
612
613#### Returns
614
615`boolean`
616
617#### Inherited from
618
619[`BaseIndex`](BaseIndex.md).[`matchesField`](BaseIndex.md#matchesfield)
620
621***
622
623### rangeQuery()
624
625```ts
626rangeQuery(options): Set<TKey>;
627```
628
629Defined in: [packages/db/src/indexes/btree-index.ts:232](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L232)
630
631Performs a range query with options
632This is more efficient for compound queries like "WHERE a > 5 AND a < 10"
633
634#### Parameters
635
636##### options
637
638[`BTreeRangeQueryOptions`](../interfaces/BTreeRangeQueryOptions.md) = `{}`
639
640#### Returns
641
642`Set`\<`TKey`\>
643
644#### Overrides
645
646[`BaseIndex`](BaseIndex.md).[`rangeQuery`](BaseIndex.md#rangequery)
647
648***
649
650### rangeQueryReversed()
651
652```ts
653rangeQueryReversed(options): Set<TKey>;
654```
655
656Defined in: [packages/db/src/indexes/btree-index.ts:279](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L279)
657
658Performs a reversed range query
659
660#### Parameters
661
662##### options
663
664[`BTreeRangeQueryOptions`](../interfaces/BTreeRangeQueryOptions.md) = `{}`
665
666#### Returns
667
668`Set`\<`TKey`\>
669
670#### Overrides
671
672[`BaseIndex`](BaseIndex.md).[`rangeQueryReversed`](BaseIndex.md#rangequeryreversed)
673
674***
675
676### remove()
677
678```ts
679remove(key, item): void;
680```
681
682Defined in: [packages/db/src/indexes/btree-index.ts:115](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L115)
683
684Removes a value from the index
685
686#### Parameters
687
688##### key
689
690`TKey`
691
692##### item
693
694`any`
695
696#### Returns
697
698`void`
699
700#### Overrides
701
702[`BaseIndex`](BaseIndex.md).[`remove`](BaseIndex.md#remove)
703
704***
705
706### supports()
707
708```ts
709supports(operation): boolean;
710```
711
712Defined in: [packages/db/src/indexes/base-index.ts:157](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L157)
713
714#### Parameters
715
716##### operation
717
718`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
719
720#### Returns
721
722`boolean`
723
724#### Inherited from
725
726[`BaseIndex`](BaseIndex.md).[`supports`](BaseIndex.md#supports)
727
728***
729
730### take()
731
732```ts
733take(
734 n,
735 from,
736 filterFn?): TKey[];
737```
738
739Defined in: [packages/db/src/indexes/btree-index.ts:341](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L341)
740
741Returns the next n items after the provided item.
742
743#### Parameters
744
745##### n
746
747`number`
748
749The number of items to return
750
751##### from
752
753`any`
754
755The item to start from (exclusive).
756
757##### filterFn?
758
759(`key`) => `boolean`
760
761#### Returns
762
763`TKey`[]
764
765The next n items after the provided key.
766
767#### Overrides
768
769[`BaseIndex`](BaseIndex.md).[`take`](BaseIndex.md#take)
770
771***
772
773### takeFromStart()
774
775```ts
776takeFromStart(n, filterFn?): TKey[];
777```
778
779Defined in: [packages/db/src/indexes/btree-index.ts:354](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L354)
780
781Returns the first n items from the beginning.
782
783#### Parameters
784
785##### n
786
787`number`
788
789The number of items to return
790
791##### filterFn?
792
793(`key`) => `boolean`
794
795Optional filter function
796
797#### Returns
798
799`TKey`[]
800
801The first n items
802
803#### Overrides
804
805[`BaseIndex`](BaseIndex.md).[`takeFromStart`](BaseIndex.md#takefromstart)
806
807***
808
809### takeReversed()
810
811```ts
812takeReversed(
813 n,
814 from,
815 filterFn?): TKey[];
816```
817
818Defined in: [packages/db/src/indexes/btree-index.ts:366](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L366)
819
820Returns the next n items **before** the provided item (in descending order).
821
822#### Parameters
823
824##### n
825
826`number`
827
828The number of items to return
829
830##### from
831
832`any`
833
834The item to start from (exclusive). Required.
835
836##### filterFn?
837
838(`key`) => `boolean`
839
840#### Returns
841
842`TKey`[]
843
844The next n items **before** the provided key.
845
846#### Overrides
847
848[`BaseIndex`](BaseIndex.md).[`takeReversed`](BaseIndex.md#takereversed)
849
850***
851
852### takeReversedFromEnd()
853
854```ts
855takeReversedFromEnd(n, filterFn?): TKey[];
856```
857
858Defined in: [packages/db/src/indexes/btree-index.ts:383](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L383)
859
860Returns the last n items from the end.
861
862#### Parameters
863
864##### n
865
866`number`
867
868The number of items to return
869
870##### filterFn?
871
872(`key`) => `boolean`
873
874Optional filter function
875
876#### Returns
877
878`TKey`[]
879
880The last n items
881
882#### Overrides
883
884[`BaseIndex`](BaseIndex.md).[`takeReversedFromEnd`](BaseIndex.md#takereversedfromend)
885
886***
887
888### trackLookup()
889
890```ts
891protected trackLookup(startTime): void;
892```
893
894Defined in: [packages/db/src/indexes/base-index.ts:217](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L217)
895
896#### Parameters
897
898##### startTime
899
900`number`
901
902#### Returns
903
904`void`
905
906#### Inherited from
907
908[`BaseIndex`](BaseIndex.md).[`trackLookup`](BaseIndex.md#tracklookup)
909
910***
911
912### update()
913
914```ts
915update(
916 key,
917 oldItem,
918 newItem): void;
919```
920
921Defined in: [packages/db/src/indexes/btree-index.ts:150](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L150)
922
923Updates a value in the index
924
925#### Parameters
926
927##### key
928
929`TKey`
930
931##### oldItem
932
933`any`
934
935##### newItem
936
937`any`
938
939#### Returns
940
941`void`
942
943#### Overrides
944
945[`BaseIndex`](BaseIndex.md).[`update`](BaseIndex.md#update)
946
947***
948
949### updateTimestamp()
950
951```ts
952protected updateTimestamp(): void;
953```
954
955Defined in: [packages/db/src/indexes/base-index.ts:223](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L223)
956
957#### Returns
958
959`void`
960
961#### Inherited from
962
963[`BaseIndex`](BaseIndex.md).[`updateTimestamp`](BaseIndex.md#updatetimestamp)