Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

BTreeIndex.md

963 lines16.6 KB

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)