document-dataply 0.0.9-alpha.14 → 0.0.9-alpha.15

package/dist/cjs/index.js

@@ -1669,28 +1669,28 @@ var require_cjs = __commonJS({
       searchConfigs = {
         gt: {
           asc: {
-            start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
             end: () => null,
             direction: 1,
             earlyTerminate: false
           },
           desc: {
             start: (tx) => tx.rightestNode(),
-            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
             direction: -1,
             earlyTerminate: true
           }
         },
         gte: {
           asc: {
-            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
             end: () => null,
             direction: 1,
             earlyTerminate: false
           },
           desc: {
             start: (tx) => tx.rightestNode(),
-            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
             direction: -1,
             earlyTerminate: true
           }
@@ -1698,12 +1698,12 @@ var require_cjs = __commonJS({
         lt: {
           asc: {
             start: (tx) => tx.leftestNode(),
-            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
             direction: 1,
             earlyTerminate: true
           },
           desc: {
-            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
             end: () => null,
             direction: -1,
             earlyTerminate: false
@@ -1712,12 +1712,12 @@ var require_cjs = __commonJS({
         lte: {
           asc: {
             start: (tx) => tx.leftestNode(),
-            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
             direction: 1,
             earlyTerminate: true
           },
           desc: {
-            start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
             end: () => null,
             direction: -1,
             earlyTerminate: false
@@ -1725,14 +1725,14 @@ var require_cjs = __commonJS({
         },
         equal: {
           asc: {
-            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
-            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
             direction: 1,
             earlyTerminate: true
           },
           desc: {
-            start: (tx, v) => tx.insertableEndNode(v[0], 1),
-            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            start: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
             direction: -1,
             earlyTerminate: true
           }
@@ -1753,42 +1753,42 @@ var require_cjs = __commonJS({
         },
         or: {
           asc: {
-            start: (tx, v) => tx.insertableNodeByPrimary(tx.lowestValue(v)),
-            end: (tx, v) => tx.insertableEndNode(tx.highestValue(v), 1),
+            start: (tx, v) => tx.findLowerBoundLeaf(tx.lowestValue(v)),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(tx.highestValue(v), 1),
             direction: 1,
             earlyTerminate: false
           },
           desc: {
-            start: (tx, v) => tx.insertableEndNode(tx.highestValue(v), 1),
-            end: (tx, v) => tx.insertableEndNode(tx.lowestValue(v), -1),
+            start: (tx, v) => tx.findOuterBoundaryLeaf(tx.highestValue(v), 1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(tx.lowestValue(v), -1),
             direction: -1,
             earlyTerminate: false
           }
         },
         primaryGt: {
           asc: {
-            start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
             end: () => null,
             direction: 1,
             earlyTerminate: false
           },
           desc: {
             start: (tx) => tx.rightestNode(),
-            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
             direction: -1,
             earlyTerminate: true
           }
         },
         primaryGte: {
           asc: {
-            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
             end: () => null,
             direction: 1,
             earlyTerminate: false
           },
           desc: {
             start: (tx) => tx.rightestNode(),
-            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
             direction: -1,
             earlyTerminate: true
           }
@@ -1796,12 +1796,12 @@ var require_cjs = __commonJS({
         primaryLt: {
           asc: {
             start: (tx) => tx.leftestNode(),
-            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
             direction: 1,
             earlyTerminate: true
           },
           desc: {
-            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
             end: () => null,
             direction: -1,
             earlyTerminate: false
@@ -1810,12 +1810,12 @@ var require_cjs = __commonJS({
         primaryLte: {
           asc: {
             start: (tx) => tx.leftestNode(),
-            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
             direction: 1,
             earlyTerminate: true
           },
           desc: {
-            start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
             end: () => null,
             direction: -1,
             earlyTerminate: false
@@ -1823,14 +1823,14 @@ var require_cjs = __commonJS({
         },
         primaryEqual: {
           asc: {
-            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
-            end: (tx, v) => tx.insertableRightestEndNodeByPrimary(v[0]),
+            start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
             direction: 1,
             earlyTerminate: true
           },
           desc: {
-            start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
-            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
             direction: -1,
             earlyTerminate: true
           }
@@ -1851,14 +1851,14 @@ var require_cjs = __commonJS({
         },
         primaryOr: {
           asc: {
-            start: (tx, v) => tx.insertableNodeByPrimary(tx.lowestPrimaryValue(v)),
-            end: (tx, v) => tx.insertableRightestEndNodeByPrimary(tx.highestPrimaryValue(v)),
+            start: (tx, v) => tx.findLowerBoundLeaf(tx.lowestPrimaryValue(v)),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(tx.highestPrimaryValue(v), 1),
             direction: 1,
             earlyTerminate: false
           },
           desc: {
-            start: (tx, v) => tx.insertableRightestNodeByPrimary(tx.highestPrimaryValue(v)),
-            end: (tx, v) => tx.insertableEndNode(tx.lowestPrimaryValue(v), -1),
+            start: (tx, v) => tx.findUpperBoundLeaf(tx.highestPrimaryValue(v)),
+            end: (tx, v) => tx.findOuterBoundaryLeaf(tx.lowestPrimaryValue(v), -1),
             direction: -1,
             earlyTerminate: false
           }
@@ -2030,17 +2030,19 @@ var require_cjs = __commonJS({
         let endKey = null;
         let startValues = [];
         let endValues = [];
-        for (const key of startCandidates) {
+        for (let i = 0, len = startCandidates.length; i < len; i++) {
+          const key = startCandidates[i];
           if (key in condition) {
             startKey = key;
-            startValues = this.ensureValues(condition[key]);
+            startValues = _BPTreeTransaction._multiValueKeys.includes(key) ? this.ensureValues(condition[key]) : [condition[key]];
             break;
           }
         }
-        for (const key of endCandidates) {
+        for (let i = 0, len = endCandidates.length; i < len; i++) {
+          const key = endCandidates[i];
           if (key in condition) {
             endKey = key;
-            endValues = this.ensureValues(condition[key]);
+            endValues = _BPTreeTransaction._multiValueKeys.includes(key) ? this.ensureValues(condition[key]) : [condition[key]];
             break;
           }
         }
@@ -2070,6 +2072,11 @@ var require_cjs = __commonJS({
         "primaryOr",
         "or"
       ];
+      // Condition keys that accept multiple values (V[]) rather than a single value (V)
+      static _multiValueKeys = [
+        "or",
+        "primaryOr"
+      ];
       constructor(rootTx, mvccRoot, mvcc, strategy, comparator, option) {
         this.rootTx = rootTx === null ? this : rootTx;
         this.mvccRoot = mvccRoot;
@@ -2306,7 +2313,7 @@ var require_cjs = __commonJS({
           this._insertInParent(parentNode, midValue, newSiblingNodeRecursive);
         }
       }
-      insertableNode(value) {
+      locateLeaf(value) {
         let node = this.getNode(this.rootId);
         while (!node.leaf) {
           const { index } = this._binarySearchValues(node.values, value, false, true);
@@ -2314,7 +2321,7 @@ var require_cjs = __commonJS({
         }
         return node;
       }
-      insertableNodeByPrimary(value) {
+      findLowerBoundLeaf(value) {
         let node = this.getNode(this.rootId);
         while (!node.leaf) {
           const { index } = this._binarySearchValues(node.values, value, true, false);
@@ -2322,7 +2329,7 @@ var require_cjs = __commonJS({
         }
         return node;
       }
-      insertableRightestNodeByPrimary(value) {
+      findUpperBoundLeaf(value) {
         let node = this.getNode(this.rootId);
         while (!node.leaf) {
           const { index } = this._binarySearchValues(node.values, value, true, true);
@@ -2330,15 +2337,8 @@ var require_cjs = __commonJS({
         }
         return node;
       }
-      insertableRightestEndNodeByPrimary(value) {
-        const node = this.insertableRightestNodeByPrimary(value);
-        if (!node.next) {
-          return null;
-        }
-        return this.getNode(node.next);
-      }
-      insertableEndNode(value, direction) {
-        const insertableNode = direction === -1 ? this.insertableNodeByPrimary(value) : this.insertableRightestNodeByPrimary(value);
+      findOuterBoundaryLeaf(value, direction) {
+        const insertableNode = direction === -1 ? this.findLowerBoundLeaf(value) : this.findUpperBoundLeaf(value);
         let key;
         switch (direction) {
           case -1:
@@ -2450,7 +2450,7 @@ var require_cjs = __commonJS({
         }
       }
       exists(key, value) {
-        const node = this.insertableNode(value);
+        const node = this.locateLeaf(value);
         const { index, found } = this._binarySearchValues(node.values, value);
         if (found) {
           const keys = node.keys[index];
@@ -2547,7 +2547,7 @@ var require_cjs = __commonJS({
         return map;
       }
       insert(key, value) {
-        let before = this.insertableNode(value);
+        let before = this.locateLeaf(value);
         before = this._insertAtLeaf(before, key, value);
         if (before.values.length === this.order) {
           let after = this._createNode(
@@ -2575,7 +2575,7 @@ var require_cjs = __commonJS({
         let currentLeaf = null;
         let modified = false;
         for (const [key, value] of sorted) {
-          const targetLeaf = this.insertableNode(value);
+          const targetLeaf = this.locateLeaf(value);
           if (currentLeaf !== null && currentLeaf.id === targetLeaf.id) {
           } else {
             if (currentLeaf !== null && modified) {
@@ -2817,7 +2817,7 @@ var require_cjs = __commonJS({
         if (value === void 0) {
           return;
         }
-        let node = this.insertableNodeByPrimary(value);
+        let node = this.findLowerBoundLeaf(value);
         let found = false;
         while (true) {
           let i = node.values.length;
@@ -3399,7 +3399,7 @@ var require_cjs = __commonJS({
           await this._insertInParent(parentNode, midValue, newSiblingNodeRecursive);
         }
       }
-      async insertableNode(value) {
+      async locateLeaf(value) {
         let node = await this.getNode(this.rootId);
         while (!node.leaf) {
           const { index } = this._binarySearchValues(node.values, value, false, true);
@@ -3407,7 +3407,7 @@ var require_cjs = __commonJS({
         }
         return node;
       }
-      async insertableNodeByPrimary(value) {
+      async findLowerBoundLeaf(value) {
         let node = await this.getNode(this.rootId);
         while (!node.leaf) {
           const { index } = this._binarySearchValues(node.values, value, true, false);
@@ -3415,7 +3415,7 @@ var require_cjs = __commonJS({
         }
         return node;
       }
-      async insertableRightestNodeByPrimary(value) {
+      async findUpperBoundLeaf(value) {
         let node = await this.getNode(this.rootId);
         while (!node.leaf) {
           const { index } = this._binarySearchValues(node.values, value, true, true);
@@ -3423,15 +3423,8 @@ var require_cjs = __commonJS({
         }
         return node;
       }
-      async insertableRightestEndNodeByPrimary(value) {
-        const node = await this.insertableRightestNodeByPrimary(value);
-        if (!node.next) {
-          return null;
-        }
-        return await this.getNode(node.next);
-      }
-      async insertableEndNode(value, direction) {
-        const insertableNode = direction === -1 ? await this.insertableNodeByPrimary(value) : await this.insertableRightestNodeByPrimary(value);
+      async findOuterBoundaryLeaf(value, direction) {
+        const insertableNode = direction === -1 ? await this.findLowerBoundLeaf(value) : await this.findUpperBoundLeaf(value);
         let key;
         switch (direction) {
           case -1:
@@ -3552,7 +3545,7 @@ var require_cjs = __commonJS({
         }
       }
       async exists(key, value) {
-        const node = await this.insertableNode(value);
+        const node = await this.locateLeaf(value);
         const { index, found } = this._binarySearchValues(node.values, value);
         if (found) {
           const keys = node.keys[index];
@@ -3650,7 +3643,7 @@ var require_cjs = __commonJS({
       }
       async insert(key, value) {
         return this.writeLock(0, async () => {
-          let before = await this.insertableNode(value);
+          let before = await this.locateLeaf(value);
           before = await this._insertAtLeaf(before, key, value);
           if (before.values.length === this.order) {
             let after = await this._createNode(
@@ -3680,7 +3673,7 @@ var require_cjs = __commonJS({
           let currentLeaf = null;
           let modified = false;
           for (const [key, value] of sorted) {
-            const targetLeaf = await this.insertableNode(value);
+            const targetLeaf = await this.locateLeaf(value);
             if (currentLeaf !== null && currentLeaf.id === targetLeaf.id) {
             } else {
               if (currentLeaf !== null && modified) {
@@ -3924,7 +3917,7 @@ var require_cjs = __commonJS({
           if (value === void 0) {
             return;
           }
-          let node = await this.insertableNodeByPrimary(value);
+          let node = await this.findLowerBoundLeaf(value);
           let found = false;
           while (true) {
             let i = node.values.length;
@@ -6519,7 +6512,7 @@ var require_cjs = __commonJS({
       const threshold = mean + stddev * logN;
       return Math.max(threshold, baseGap * 5, 20);
     }
-    function clusterNumbers(numbers, gapMultiplier) {
+    function clusterNumbers(numbers, maxGap) {
       const n = numbers.length;
       if (n === 0) return [];
       if (n === 1) return [new Float64Array([numbers[0]])];
@@ -6530,10 +6523,8 @@ var require_cjs = __commonJS({
       }
       const sortedGaps = gaps.slice().sort();
       let threshold;
-      if (gapMultiplier !== void 0) {
-        const q3 = sortedGaps[Math.floor((n - 1) * 0.75)];
-        const iqr = q3 - sortedGaps[Math.floor((n - 1) * 0.25)];
-        threshold = q3 + iqr * gapMultiplier;
+      if (maxGap !== void 0) {
+        threshold = maxGap;
       } else {
         threshold = calcThreshold(sortedGaps, n);
       }
@@ -9486,9 +9477,12 @@ var require_cjs = __commonJS({
         for (let i = 0, len = pks.length; i < len; i++) {
           pkIndexMap.set(pks[i], i);
         }
-        const pkRidPairs = new Array(pks.length).fill(null);
+        const validCount = pks.length;
+        const pkArray = new Float64Array(validCount).fill(0);
+        const ridArray = new Float64Array(validCount).fill(0);
+        const indexArray = new Float64Array(validCount).fill(0);
         const btx = await this.getBPTreeTransaction(tx);
-        const clusters = clusterNumbers(pks);
+        const clusters = clusterNumbers(pks, this.order / 2);
         for (let i = 0, len = clusters.length; i < len; i++) {
           const cluster = clusters[i];
           const minPk = cluster[0];
@@ -9499,7 +9493,9 @@ var require_cjs = __commonJS({
               const rid = keys.values().next().value;
               const index = pkIndexMap.get(minPk);
               if (index !== void 0) {
-                pkRidPairs[index] = { pk: minPk, rid, index };
+                pkArray[index] = minPk;
+                ridArray[index] = rid;
+                indexArray[index] = index;
               }
             }
             continue;
@@ -9508,11 +9504,13 @@ var require_cjs = __commonJS({
           for await (const [rid, pk] of stream) {
             const index = pkIndexMap.get(pk);
             if (index !== void 0) {
-              pkRidPairs[index] = { pk, rid, index };
+              pkArray[index] = pk;
+              ridArray[index] = rid;
+              indexArray[index] = index;
             }
           }
         }
-        return this.fetchRowsByRids(pkRidPairs, tx);
+        return this.fetchRowsByRids(validCount, pkArray, ridArray, indexArray, tx);
       }
       /**
        * Fetches multiple rows by their RID and PK combinations, grouping by page ID to minimize I/O.
@@ -9520,19 +9518,21 @@ var require_cjs = __commonJS({
        * @param tx Transaction
        * @returns Array of row data in the same order as input PKs
        */
-      async fetchRowsByRids(pkRidPairs, tx) {
-        const result = new Array(pkRidPairs.length).fill(null);
-        if (pkRidPairs.length === 0) return result;
+      async fetchRowsByRids(validCount, pkArray, ridArray, indexArray, tx) {
+        const result = new Array(validCount).fill(null);
+        if (validCount === 0) return result;
         const pageGroupMap = /* @__PURE__ */ new Map();
-        for (const pair of pkRidPairs) {
-          if (pair === null) continue;
-          const rid = pair.rid;
+        for (let i = 0; i < validCount; i++) {
+          const pk = pkArray[i];
+          const rid = ridArray[i];
+          const index = indexArray[i];
+          if (pk === 0 && rid === 0 && index === 0) continue;
           const slotIndex = rid % 65536;
           const pageId = Math.floor(rid / 65536);
           if (!pageGroupMap.has(pageId)) {
             pageGroupMap.set(pageId, []);
           }
-          pageGroupMap.get(pageId).push({ pk: pair.pk, slotIndex, index: pair.index });
+          pageGroupMap.get(pageId).push({ pk, slotIndex, index });
         }
         const sortedPageIds = Array.from(pageGroupMap.keys()).sort((a, b) => a - b);
         await Promise.all(sortedPageIds.map(async (pageId) => {
@@ -9542,7 +9542,8 @@ var require_cjs = __commonJS({
             throw new Error(`Page ${pageId} is not a data page`);
           }
           const manager = this.factory.getManager(page);
-          for (const item of items) {
+          for (let i = 0, len = items.length; i < len; i++) {
+            const item = items[i];
             const row = manager.getRow(page, item.slotIndex);
             if (this.rowManager.getDeletedFlag(row)) {
               result[item.index] = null;
@@ -11195,6 +11196,191 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     }
     return result;
   }
+  /**
+   * B-Tree 타입 인덱스의 선택도를 평가하고 트리에 부여할 조건을 산출합니다.
+   * 필드 매칭 여부를 검사하고, 연속된(Prefix) 조건에 대해 점수를 부여하며 Start/End 바운드를 구성합니다.
+   * 
+   * @param indexName 평가할 인덱스의 이름 (예: idx_nickname_createdat)
+   * @param config 등록된 인덱스의 설정 객체
+   * @param query 쿼리 객체
+   * @param queryFields 쿼리에 포함된 필드 목록 집합
+   * @param treeTx 조회를 수행할 B-Tree 트랜잭션 객체
+   * @param orderByField 정렬에 사용할 필드명 (옵션)
+   * @returns B-Tree 인덱스 후보 정보 (조건, 점수, 커버된 필드 등), 적합하지 않으면 null
+   */
+  evaluateBTreeCandidate(indexName, config, query, queryFields, treeTx, orderByField) {
+    const primaryField = config.fields[0];
+    if (!queryFields.has(primaryField)) return null;
+    const builtCondition = {};
+    let score = 0;
+    let isConsecutive = true;
+    const coveredFields = [];
+    const compositeVerifyFields = [];
+    const startValues = [];
+    const endValues = [];
+    let startOperator = null;
+    let endOperator = null;
+    for (let i = 0, len = config.fields.length; i < len; i++) {
+      const field = config.fields[i];
+      if (!queryFields.has(field)) {
+        isConsecutive = false;
+        continue;
+      }
+      coveredFields.push(field);
+      score += 1;
+      if (isConsecutive) {
+        const cond = query[field];
+        if (cond !== void 0) {
+          let isBounded = false;
+          if (typeof cond !== "object" || cond === null) {
+            score += 100;
+            startValues.push(cond);
+            endValues.push(cond);
+            startOperator = "primaryGte";
+            endOperator = "primaryLte";
+            isBounded = true;
+          } else if ("primaryEqual" in cond || "equal" in cond) {
+            const val = cond.primaryEqual?.v ?? cond.equal?.v ?? cond.primaryEqual ?? cond.equal;
+            score += 100;
+            startValues.push(val);
+            endValues.push(val);
+            startOperator = "primaryGte";
+            endOperator = "primaryLte";
+            isBounded = true;
+          } else if ("primaryGte" in cond || "gte" in cond) {
+            const val = cond.primaryGte?.v ?? cond.gte?.v ?? cond.primaryGte ?? cond.gte;
+            score += 50;
+            isConsecutive = false;
+            startValues.push(val);
+            startOperator = "primaryGte";
+            if (endValues.length > 0) endOperator = "primaryLte";
+            isBounded = true;
+          } else if ("primaryGt" in cond || "gt" in cond) {
+            const val = cond.primaryGt?.v ?? cond.gt?.v ?? cond.primaryGt ?? cond.gt;
+            score += 50;
+            isConsecutive = false;
+            startValues.push(val);
+            startOperator = "primaryGt";
+            if (endValues.length > 0) endOperator = "primaryLte";
+            isBounded = true;
+          } else if ("primaryLte" in cond || "lte" in cond) {
+            const val = cond.primaryLte?.v ?? cond.lte?.v ?? cond.primaryLte ?? cond.lte;
+            score += 50;
+            isConsecutive = false;
+            endValues.push(val);
+            endOperator = "primaryLte";
+            if (startValues.length > 0) startOperator = "primaryGte";
+            isBounded = true;
+          } else if ("primaryLt" in cond || "lt" in cond) {
+            const val = cond.primaryLt?.v ?? cond.lt?.v ?? cond.primaryLt ?? cond.lt;
+            score += 50;
+            isConsecutive = false;
+            endValues.push(val);
+            endOperator = "primaryLt";
+            if (startValues.length > 0) startOperator = "primaryGte";
+            isBounded = true;
+          } else if ("primaryOr" in cond || "or" in cond) {
+            score += 20;
+            isConsecutive = false;
+          } else if ("like" in cond) {
+            score += 15;
+            isConsecutive = false;
+          } else {
+            score += 10;
+            isConsecutive = false;
+          }
+          if (!isBounded && field !== primaryField) {
+            compositeVerifyFields.push(field);
+          }
+        }
+      } else {
+        if (field !== primaryField) {
+          compositeVerifyFields.push(field);
+        }
+      }
+    }
+    if (coveredFields.length === 1 && config.fields.length === 1) {
+      Object.assign(builtCondition, query[primaryField]);
+    } else {
+      if (startOperator && startValues.length > 0) {
+        builtCondition[startOperator] = { v: startValues.length === 1 ? startValues[0] : startValues };
+      }
+      if (endOperator && endValues.length > 0) {
+        if (startOperator && startValues.length === endValues.length && startValues.every((val, i) => val === endValues[i])) {
+          delete builtCondition[startOperator];
+          builtCondition["primaryEqual"] = { v: startValues.length === 1 ? startValues[0] : startValues };
+        } else {
+          builtCondition[endOperator] = { v: endValues.length === 1 ? endValues[0] : endValues };
+        }
+      }
+      if (Object.keys(builtCondition).length === 0) {
+        Object.assign(builtCondition, query[primaryField] || {});
+      }
+    }
+    let isIndexOrderSupported = false;
+    if (orderByField) {
+      for (let i = 0, len = config.fields.length; i < len; i++) {
+        const field = config.fields[i];
+        if (field === orderByField) {
+          isIndexOrderSupported = true;
+          break;
+        }
+        const cond = query[field];
+        let isExactMatch = false;
+        if (cond !== void 0) {
+          if (typeof cond !== "object" || cond === null) isExactMatch = true;
+          else if ("primaryEqual" in cond || "equal" in cond) isExactMatch = true;
+        }
+        if (!isExactMatch) break;
+      }
+      if (isIndexOrderSupported) {
+        score += 200;
+      }
+    }
+    return {
+      tree: treeTx,
+      condition: builtCondition,
+      field: primaryField,
+      indexName,
+      isFtsMatch: false,
+      score,
+      compositeVerifyFields,
+      coveredFields,
+      isIndexOrderSupported
+    };
+  }
+  /**
+   * FTS (Full Text Search) 타입 인덱스의 선택도를 평가합니다.
+   * 'match' 연산자가 쿼리에 존재하는지 확인하고, 검색용 토큰으로 분해(tokenize)하여 점수를 매깁니다.
+   * 
+   * @param indexName 평가할 인덱스의 이름
+   * @param config 등록된 인덱스의 설정 객체
+   * @param query 쿼리 객체
+   * @param queryFields 쿼리에 포함된 필드 목록 집합
+   * @param treeTx 조회를 수행할 B-Tree 트랜잭션 객체
+   * @returns FTS 인덱스 후보 정보 (조건, 점수, 분석된 토큰 등), 적합하지 않으면 null
+   */
+  evaluateFTSCandidate(indexName, config, query, queryFields, treeTx) {
+    const field = config.fields;
+    if (!queryFields.has(field)) return null;
+    const condition = query[field];
+    if (!condition || typeof condition !== "object" || !("match" in condition)) return null;
+    const ftsConfig = this.getFtsConfig(config);
+    const matchTokens = ftsConfig ? tokenize(condition.match, ftsConfig) : [];
+    return {
+      tree: treeTx,
+      condition,
+      field,
+      indexName,
+      isFtsMatch: true,
+      matchTokens,
+      score: 90,
+      // FTS 쿼리는 기본적인 B-Tree 단일 검색(대략 101점)보다는 우선순위를 조금 낮게 가져가도록 90점 부여
+      compositeVerifyFields: [],
+      coveredFields: [field],
+      isIndexOrderSupported: false
+    };
+  }
   /**
    * Choose the best index (driver) for the given query.
    * Scores each index based on field coverage and condition type.
@@ -11210,161 +11396,26 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       const tree = this.trees.get(indexName);
       if (!tree) continue;
       if (config.type === "btree") {
-        const primaryField = config.fields[0];
-        if (!queryFields.has(primaryField)) continue;
         const treeTx = await tree.createTransaction();
-        const builtCondition = {};
-        let score = 0;
-        let isConsecutive = true;
-        const coveredFields = [];
-        const compositeVerifyFields = [];
-        const startValues = [];
-        const endValues = [];
-        let startOperator = null;
-        let endOperator = null;
-        for (let i = 0, len = config.fields.length; i < len; i++) {
-          const field = config.fields[i];
-          if (!queryFields.has(field)) {
-            isConsecutive = false;
-            continue;
-          }
-          coveredFields.push(field);
-          if (field !== primaryField) {
-            compositeVerifyFields.push(field);
-          }
-          score += 1;
-          if (isConsecutive) {
-            const cond = query[field];
-            if (cond !== void 0) {
-              if (typeof cond !== "object" || cond === null) {
-                score += 100;
-                startValues.push(cond);
-                endValues.push(cond);
-                startOperator = "primaryGte";
-                endOperator = "primaryLte";
-              } else if ("primaryEqual" in cond || "equal" in cond) {
-                const val = cond.primaryEqual?.v ?? cond.equal?.v ?? cond.primaryEqual ?? cond.equal;
-                score += 100;
-                startValues.push(val);
-                endValues.push(val);
-                startOperator = "primaryGte";
-                endOperator = "primaryLte";
-              } else if ("primaryGte" in cond || "gte" in cond) {
-                const val = cond.primaryGte?.v ?? cond.gte?.v ?? cond.primaryGte ?? cond.gte;
-                score += 50;
-                isConsecutive = false;
-                startValues.push(val);
-                startOperator = "primaryGte";
-                if (endValues.length > 0) {
-                  endOperator = "primaryLte";
-                }
-              } else if ("primaryGt" in cond || "gt" in cond) {
-                const val = cond.primaryGt?.v ?? cond.gt?.v ?? cond.primaryGt ?? cond.gt;
-                score += 50;
-                isConsecutive = false;
-                startValues.push(val);
-                startOperator = "primaryGt";
-                if (endValues.length > 0) {
-                  endOperator = "primaryLte";
-                }
-              } else if ("primaryLte" in cond || "lte" in cond) {
-                const val = cond.primaryLte?.v ?? cond.lte?.v ?? cond.primaryLte ?? cond.lte;
-                score += 50;
-                isConsecutive = false;
-                endValues.push(val);
-                endOperator = "primaryLte";
-                if (startValues.length > 0) {
-                  startOperator = "primaryGte";
-                }
-              } else if ("primaryLt" in cond || "lt" in cond) {
-                const val = cond.primaryLt?.v ?? cond.lt?.v ?? cond.primaryLt ?? cond.lt;
-                score += 50;
-                isConsecutive = false;
-                endValues.push(val);
-                endOperator = "primaryLt";
-                if (startValues.length > 0) {
-                  startOperator = "primaryGte";
-                }
-              } else if ("primaryOr" in cond || "or" in cond) {
-                score += 20;
-                isConsecutive = false;
-              } else if ("like" in cond) {
-                score += 15;
-                isConsecutive = false;
-              } else {
-                score += 10;
-                isConsecutive = false;
-              }
-            }
-          }
-        }
-        if (coveredFields.length === 1 && config.fields.length === 1) {
-          Object.assign(builtCondition, query[primaryField]);
-        } else {
-          if (startOperator && startValues.length > 0) {
-            builtCondition[startOperator] = { v: startValues.length === 1 ? startValues[0] : startValues };
-          }
-          if (endOperator && endValues.length > 0) {
-            if (startOperator && startValues.length === endValues.length && startValues.every((val, i) => val === endValues[i])) {
-              delete builtCondition[startOperator];
-              builtCondition["primaryEqual"] = { v: startValues.length === 1 ? startValues[0] : startValues };
-            } else {
-              builtCondition[endOperator] = { v: endValues.length === 1 ? endValues[0] : endValues };
-            }
-          }
-          if (Object.keys(builtCondition).length === 0) {
-            Object.assign(builtCondition, query[primaryField] || {});
-          }
-        }
-        let isIndexOrderSupported = false;
-        if (orderByField) {
-          for (let i = 0, len = config.fields.length; i < len; i++) {
-            const field = config.fields[i];
-            if (field === orderByField) {
-              isIndexOrderSupported = true;
-              break;
-            }
-            const cond = query[field];
-            let isExactMatch = false;
-            if (cond !== void 0) {
-              if (typeof cond !== "object" || cond === null) isExactMatch = true;
-              else if ("primaryEqual" in cond || "equal" in cond) isExactMatch = true;
-            }
-            if (!isExactMatch) break;
-          }
-          if (isIndexOrderSupported) {
-            score += 200;
-          }
-        }
-        candidates.push({
-          tree: treeTx,
-          condition: builtCondition,
-          field: primaryField,
+        const candidate = this.evaluateBTreeCandidate(
           indexName,
-          isFtsMatch: false,
-          score,
-          compositeVerifyFields,
-          isIndexOrderSupported
-        });
+          config,
+          query,
+          queryFields,
+          treeTx,
+          orderByField
+        );
+        if (candidate) candidates.push(candidate);
       } else if (config.type === "fts") {
-        const field = config.fields;
-        if (!queryFields.has(field)) continue;
-        const condition = query[field];
-        if (!condition || typeof condition !== "object" || !("match" in condition)) continue;
         const treeTx = await tree.createTransaction();
-        const ftsConfig = this.getFtsConfig(config);
-        const matchTokens = ftsConfig ? tokenize(condition.match, ftsConfig) : [];
-        candidates.push({
-          tree: treeTx,
-          condition,
-          field,
+        const candidate = this.evaluateFTSCandidate(
           indexName,
-          isFtsMatch: true,
-          matchTokens,
-          score: 90,
-          compositeVerifyFields: [],
-          isIndexOrderSupported: false
-        });
+          config,
+          query,
+          queryFields,
+          treeTx
+        );
+        if (candidate) candidates.push(candidate);
       }
     }
     const rollback = () => {
@@ -11385,7 +11436,8 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       return aFieldCount - bFieldCount;
     });
     const driver = candidates[0];
-    const others = candidates.slice(1).filter((c) => c.field !== driver.field);
+    const driverCoveredFields = new Set(driver.coveredFields);
+    const others = candidates.slice(1).filter((c) => !driverCoveredFields.has(c.field));
     const compositeVerifyConditions = [];
     for (let i = 0, len = driver.compositeVerifyFields.length; i < len; i++) {
       const field = driver.compositeVerifyFields[i];
@@ -11858,12 +11910,13 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * Prefetch 방식으로 키 스트림을 청크 단위로 조회하여 문서를 순회합니다.
    * FTS 검증, 복합 인덱스 검증, others 후보에 대한 tree.verify() 검증을 통과한 문서만 yield 합니다.
    */
-  async *processChunkedKeysWithVerify(keysStream, startIdx, initialChunkSize, ftsConditions, compositeVerifyConditions, others, tx) {
+  async *processChunkedKeysWithVerify(keysStream, startIdx, initialChunkSize, limit, ftsConditions, compositeVerifyConditions, others, tx) {
     const verifyOthers = others.filter((o) => !o.isFtsMatch);
     const isFts = ftsConditions.length > 0;
     const isCompositeVerify = compositeVerifyConditions.length > 0;
     const isVerifyOthers = verifyOthers.length > 0;
-    let currentChunkSize = initialChunkSize;
+    const isInfiniteLimit = isFinite(limit);
+    let currentChunkSize = isInfiniteLimit ? initialChunkSize : limit;
     let chunk = [];
     let chunkSize = 0;
     let dropped = 0;
@@ -11898,7 +11951,9 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         }
         docs.push(doc);
       }
-      currentChunkSize = this.adjustChunkSize(currentChunkSize, chunkTotalSize);
+      if (isInfiniteLimit) {
+        currentChunkSize = this.adjustChunkSize(currentChunkSize, chunkTotalSize);
+      }
       return docs;
     };
     for await (const pk of keysStream) {
@@ -11966,6 +12021,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       const driverResult = await self.getDriverKeys(query, orderByField, sortOrder);
       if (!driverResult) return;
       const { keysStream, others, compositeVerifyConditions, isDriverOrderByField, rollback } = driverResult;
+      const initialChunkSize = self.options.pageSize;
       try {
         if (!isDriverOrderByField && orderByField) {
           const topK = limit === Infinity ? Infinity : offset + limit;
@@ -11982,7 +12038,8 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           for await (const doc of self.processChunkedKeysWithVerify(
             keysStream,
             0,
-            self.options.pageSize,
+            initialChunkSize,
+            limit,
             ftsConditions,
             compositeVerifyConditions,
             others,
@@ -12023,7 +12080,8 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           for await (const doc of self.processChunkedKeysWithVerify(
             keysStream,
             startIdx,
-            self.options.pageSize,
+            initialChunkSize,
+            limit,
             ftsConditions,
             compositeVerifyConditions,
             others,

package/dist/types/core/documentAPI.d.ts

@@ -110,6 +110,31 @@ export declare class DocumentDataplyAPI<T extends DocumentJSON> extends DataplyA
      * @returns The verbose query object
      */
     verboseQuery<U extends Partial<DocumentDataplyQuery<T>>, V extends DataplyTreeValue<U>>(query: Partial<DocumentDataplyQuery<U>>): Partial<DocumentDataplyQuery<V>>;
+    /**
+     * B-Tree 타입 인덱스의 선택도를 평가하고 트리에 부여할 조건을 산출합니다.
+     * 필드 매칭 여부를 검사하고, 연속된(Prefix) 조건에 대해 점수를 부여하며 Start/End 바운드를 구성합니다.
+     *
+     * @param indexName 평가할 인덱스의 이름 (예: idx_nickname_createdat)
+     * @param config 등록된 인덱스의 설정 객체
+     * @param query 쿼리 객체
+     * @param queryFields 쿼리에 포함된 필드 목록 집합
+     * @param treeTx 조회를 수행할 B-Tree 트랜잭션 객체
+     * @param orderByField 정렬에 사용할 필드명 (옵션)
+     * @returns B-Tree 인덱스 후보 정보 (조건, 점수, 커버된 필드 등), 적합하지 않으면 null
+     */
+    private evaluateBTreeCandidate;
+    /**
+     * FTS (Full Text Search) 타입 인덱스의 선택도를 평가합니다.
+     * 'match' 연산자가 쿼리에 존재하는지 확인하고, 검색용 토큰으로 분해(tokenize)하여 점수를 매깁니다.
+     *
+     * @param indexName 평가할 인덱스의 이름
+     * @param config 등록된 인덱스의 설정 객체
+     * @param query 쿼리 객체
+     * @param queryFields 쿼리에 포함된 필드 목록 집합
+     * @param treeTx 조회를 수행할 B-Tree 트랜잭션 객체
+     * @returns FTS 인덱스 후보 정보 (조건, 점수, 분석된 토큰 등), 적합하지 않으면 null
+     */
+    private evaluateFTSCandidate;
     /**
      * Choose the best index (driver) for the given query.
      * Scores each index based on field coverage and condition type.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document-dataply",
-  "version": "0.0.9-alpha.14",
+  "version": "0.0.9-alpha.15",
   "description": "Simple and powerful JSON document database supporting complex queries and flexible indexing policies.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -42,7 +42,7 @@
     "dataply"
   ],
   "dependencies": {
-    "dataply": "^0.0.24-alpha.12"
+    "dataply": "^0.0.24-alpha.13"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",