document-dataply 0.0.10-alpha.4 → 0.0.10-alpha.6

package/dist/cjs/index.js

@@ -10466,6 +10466,26 @@ function tokenize(text, options) {
 }
 
 // src/core/Optimizer.ts
+var SELECTIVITY = {
+  /** O(log N) 포인트 룩업 */
+  EQUAL: 0.01,
+  /** 양쪽 바운드(gte+lte) 범위 스캔 */
+  BOUNDED_RANGE: 0.33,
+  /** 한쪽 바운드(gte 또는 lte)만 있을 때, 중간부터 풀스캔 */
+  HALF_RANGE: 0.5,
+  /** Or 조건: B+Tree 내부 풀스캔 */
+  OR: 0.9,
+  /** Like 조건: B+Tree 내부 풀스캔 */
+  LIKE: 0.9,
+  /** 알 수 없는 조건 */
+  UNKNOWN: 0.9,
+  /** FTS 통계 없을 때 보수적 추정 */
+  FTS_DEFAULT: 0.5,
+  /** 정렬 비용 가중치 (orderBy 미지원 시) */
+  SORT_PENALTY: 0.3,
+  /** 인메모리 정렬이 유의미해지는 임계 문서 수 */
+  SORT_THRESHOLD: 1e4
+};
 var Optimizer = class {
   constructor(api) {
     this.api = api;
@@ -10477,7 +10497,7 @@ var Optimizer = class {
     const primaryField = config.fields[0];
     if (!queryFields.has(primaryField)) return null;
     const builtCondition = {};
-    let score = 0;
+    let selectivity = 1;
     let isConsecutive = true;
     const coveredFields = [];
     const compositeVerifyFields = [];
@@ -10492,13 +10512,12 @@ var Optimizer = class {
         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;
+            selectivity *= SELECTIVITY.EQUAL;
             startValues.push(cond);
             endValues.push(cond);
             startOperator = "primaryGte";
@@ -10506,7 +10525,7 @@ var Optimizer = class {
             isBounded = true;
           } else if ("primaryEqual" in cond || "equal" in cond) {
             const val = cond.primaryEqual?.v ?? cond.equal?.v ?? cond.primaryEqual ?? cond.equal;
-            score += 100;
+            selectivity *= SELECTIVITY.EQUAL;
             startValues.push(val);
             endValues.push(val);
             startOperator = "primaryGte";
@@ -10514,7 +10533,7 @@ var Optimizer = class {
             isBounded = true;
           } else if ("primaryGte" in cond || "gte" in cond) {
             const val = cond.primaryGte?.v ?? cond.gte?.v ?? cond.primaryGte ?? cond.gte;
-            score += 50;
+            selectivity *= SELECTIVITY.HALF_RANGE;
             isConsecutive = false;
             startValues.push(val);
             startOperator = "primaryGte";
@@ -10522,7 +10541,7 @@ var Optimizer = class {
             isBounded = true;
           } else if ("primaryGt" in cond || "gt" in cond) {
             const val = cond.primaryGt?.v ?? cond.gt?.v ?? cond.primaryGt ?? cond.gt;
-            score += 50;
+            selectivity *= SELECTIVITY.HALF_RANGE;
             isConsecutive = false;
             startValues.push(val);
             startOperator = "primaryGt";
@@ -10530,7 +10549,7 @@ var Optimizer = class {
             isBounded = true;
           } else if ("primaryLte" in cond || "lte" in cond) {
             const val = cond.primaryLte?.v ?? cond.lte?.v ?? cond.primaryLte ?? cond.lte;
-            score += 50;
+            selectivity *= SELECTIVITY.HALF_RANGE;
             isConsecutive = false;
             endValues.push(val);
             endOperator = "primaryLte";
@@ -10538,20 +10557,20 @@ var Optimizer = class {
             isBounded = true;
           } else if ("primaryLt" in cond || "lt" in cond) {
             const val = cond.primaryLt?.v ?? cond.lt?.v ?? cond.primaryLt ?? cond.lt;
-            score += 50;
+            selectivity *= SELECTIVITY.HALF_RANGE;
             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;
+            selectivity *= SELECTIVITY.OR;
             isConsecutive = false;
           } else if ("like" in cond) {
-            score += 15;
+            selectivity *= SELECTIVITY.LIKE;
             isConsecutive = false;
           } else {
-            score += 10;
+            selectivity *= SELECTIVITY.UNKNOWN;
             isConsecutive = false;
           }
           if (!isBounded && field !== primaryField) {
@@ -10598,9 +10617,6 @@ var Optimizer = class {
         }
         if (!isExactMatch) break;
       }
-      if (isIndexOrderSupported) {
-        score += 200;
-      }
     }
     return {
       tree: treeTx,
@@ -10608,7 +10624,7 @@ var Optimizer = class {
       field: primaryField,
       indexName,
       isFtsMatch: false,
-      score,
+      selectivity,
       compositeVerifyFields,
       coveredFields,
       isIndexOrderSupported
@@ -10616,6 +10632,7 @@ var Optimizer = class {
   }
   /**
    * FTS 타입 인덱스의 선택도를 평가합니다.
+   * FTSTermCount 통계가 있으면 실측 데이터 기반으로 선택도를 산출합니다.
    */
   evaluateFTSCandidate(indexName, config, query, queryFields, treeTx) {
     const field = config.fields;
@@ -10624,6 +10641,16 @@ var Optimizer = class {
     if (!condition || typeof condition !== "object" || !("match" in condition)) return null;
     const ftsConfig = this.api.indexManager.getFtsConfig(config);
     const matchTokens = ftsConfig ? tokenize(condition.match, ftsConfig) : [];
+    let selectivity = SELECTIVITY.FTS_DEFAULT;
+    const termCountProvider = this.api.analysisManager.getProvider("fts_term_count");
+    if (termCountProvider && termCountProvider.hasSampleData && ftsConfig && matchTokens.length > 0) {
+      const strategy = ftsConfig.tokenizer === "ngram" ? `${ftsConfig.gramSize}gram` : ftsConfig.tokenizer;
+      const minCount = termCountProvider.getMinTokenCount(field, strategy, matchTokens);
+      if (minCount >= 0) {
+        const sampleSize = termCountProvider.getSampleSize();
+        selectivity = Math.min(minCount / sampleSize, 1);
+      }
+    }
     return {
       tree: treeTx,
       condition,
@@ -10631,18 +10658,33 @@ var Optimizer = class {
       indexName,
       isFtsMatch: true,
       matchTokens,
-      score: 90,
+      selectivity,
       compositeVerifyFields: [],
       coveredFields: [field],
       isIndexOrderSupported: false
     };
   }
   /**
-   * 실행할 최적의 인덱스를 선택합니다. (최적 드라이버 선택)
+   * 비용 계산: effectiveScanCost + sortPenalty
+   * - effectiveScanCost: 인덱스 순서 지원 + limit 존재 시 조기 종료 이점 반영
+   * - sortPenalty: 인메모리 정렬의 절대 문서 수 기반 비용
    */
-  async getSelectivityCandidate(query, orderByField) {
+  calculateCost(selectivity, isIndexOrderSupported, orderByField, N, topK) {
+    const effectiveScanCost = isIndexOrderSupported && isFinite(topK) && N > 0 ? Math.min(topK / N, selectivity) : selectivity;
+    const estimatedSortDocs = selectivity * N;
+    const sortPenalty = orderByField && !isIndexOrderSupported ? Math.min(estimatedSortDocs / SELECTIVITY.SORT_THRESHOLD, 1) * SELECTIVITY.SORT_PENALTY : 0;
+    return effectiveScanCost + sortPenalty;
+  }
+  /**
+   * 실행할 최적의 인덱스를 선택합니다. (비용 기반 최적 드라이버 선택)
+   * cost = selectivity + sortPenalty (낮을수록 좋음)
+   */
+  async getSelectivityCandidate(query, orderByField, limit = Infinity, offset = 0) {
     const queryFields = new Set(Object.keys(query));
     const candidates = [];
+    const metadata = await this.api.getMetadata();
+    const N = metadata.rowCount;
+    const topK = isFinite(limit) ? offset + limit : Infinity;
     for (const [indexName, config] of this.api.indexManager.registeredIndices) {
       const tree = this.api.trees.get(indexName);
       if (!tree) continue;
@@ -10656,7 +10698,12 @@ var Optimizer = class {
           treeTx,
           orderByField
         );
-        if (candidate) candidates.push(candidate);
+        if (candidate) {
+          candidates.push({
+            ...candidate,
+            cost: this.calculateCost(candidate.selectivity, candidate.isIndexOrderSupported, orderByField, N, topK)
+          });
+        }
       } else if (config.type === "fts") {
         const treeTx = await tree.createTransaction();
         const candidate = this.evaluateFTSCandidate(
@@ -10666,7 +10713,12 @@ var Optimizer = class {
           queryFields,
           treeTx
         );
-        if (candidate) candidates.push(candidate);
+        if (candidate) {
+          candidates.push({
+            ...candidate,
+            cost: this.calculateCost(candidate.selectivity, candidate.isIndexOrderSupported, orderByField, N, topK)
+          });
+        }
       }
     }
     const rollback = () => {
@@ -10679,7 +10731,7 @@ var Optimizer = class {
       return null;
     }
     candidates.sort((a, b) => {
-      if (b.score !== a.score) return b.score - a.score;
+      if (a.cost !== b.cost) return a.cost - b.cost;
       const aConfig = this.api.indexManager.registeredIndices.get(a.indexName);
       const bConfig = this.api.indexManager.registeredIndices.get(b.indexName);
       const aFieldCount = aConfig ? Array.isArray(aConfig.fields) ? aConfig.fields.length : 1 : 0;
@@ -10688,7 +10740,20 @@ var Optimizer = class {
     });
     const driver = candidates[0];
     const driverCoveredFields = new Set(driver.coveredFields);
-    const others = candidates.slice(1).filter((c) => !driverCoveredFields.has(c.field));
+    const nonDriverCandidates = candidates.slice(1).filter((c) => !driverCoveredFields.has(c.field));
+    const others = [];
+    for (let i = 0, len = nonDriverCandidates.length; i < len; i++) {
+      const candidate = nonDriverCandidates[i];
+      let isSubset = false;
+      for (let j = 0, oLen = others.length; j < oLen; j++) {
+        const better = others[j];
+        if (candidate.coveredFields.every((f) => better.coveredFields.includes(f))) {
+          isSubset = true;
+          break;
+        }
+      }
+      if (!isSubset) others.push(candidate);
+    }
     const compositeVerifyConditions = [];
     for (let i = 0, len = driver.compositeVerifyFields.length; i < len; i++) {
       const field = driver.compositeVerifyFields[i];
@@ -10887,12 +10952,14 @@ var QueryManager = class {
     rollback();
     return new Float64Array(Array.from(keys || []));
   }
-  async getDriverKeys(query, orderBy, sortOrder = "asc") {
+  async getDriverKeys(query, orderBy, sortOrder = "asc", limit = Infinity, offset = 0) {
     const isQueryEmpty = Object.keys(query).length === 0;
     const normalizedQuery = isQueryEmpty ? { _id: { gte: 0 } } : query;
     const selectivity = await this.optimizer.getSelectivityCandidate(
       this.verboseQuery(normalizedQuery),
-      orderBy
+      orderBy,
+      limit,
+      offset
     );
     if (!selectivity) return null;
     const { driver, others, compositeVerifyConditions, rollback } = selectivity;
@@ -10981,7 +11048,10 @@ var QueryManager = class {
     const isCompositeVerify = compositeVerifyConditions.length > 0;
     const isVerifyOthers = verifyOthers.length > 0;
     const isInfinityLimit = !isFinite(limit);
-    const isReadQuotaLimited = !isInfinityLimit || !isCompositeVerify || !isVerifyOthers || !isFts;
+    const isReadQuotaLimited = !isInfinityLimit && // limit이 임의의 유한한 값으로 설정되어 있으며
+    !isCompositeVerify && // 문서를 가져온 후 복합 인덱스 기준으로 2차 필터링할 필요가 없고
+    !isVerifyOthers && // 문서를 가져온 후 다른 인덱스 기준으로 2차 필터링할 필요가 없으며
+    !isFts;
     let currentChunkSize = isReadQuotaLimited ? limit : initialChunkSize;
     let chunk = [];
     let chunkSize = 0;
@@ -11002,10 +11072,30 @@ var QueryManager = class {
           let passed = true;
           for (let k = 0, kLen = verifyOthers.length; k < kLen; k++) {
             const other = verifyOthers[k];
-            const fieldValue = flatDoc[other.field];
-            if (fieldValue === void 0) {
-              passed = false;
-              break;
+            const coveredFields = other.coveredFields;
+            let fieldValue;
+            if (coveredFields && coveredFields.length > 1) {
+              const values = [];
+              let hasMissing = false;
+              for (let f = 0, fLen = coveredFields.length; f < fLen; f++) {
+                const v = flatDoc[coveredFields[f]];
+                if (v === void 0) {
+                  hasMissing = true;
+                  break;
+                }
+                values.push(v);
+              }
+              if (hasMissing) {
+                passed = false;
+                break;
+              }
+              fieldValue = values;
+            } else {
+              fieldValue = flatDoc[other.field];
+              if (fieldValue === void 0) {
+                passed = false;
+                break;
+              }
             }
             const treeValue = { k: doc._id, v: fieldValue };
             if (!other.tree.verify(treeValue, other.condition)) {
@@ -11088,12 +11178,13 @@ var QueryManager = class {
           }
         }
       }
-      const driverResult = await self.getDriverKeys(query, orderByField, sortOrder);
+      const driverResult = await self.getDriverKeys(query, orderByField, sortOrder, limit, offset);
       if (!driverResult) return;
       const { keysStream, others, compositeVerifyConditions, isDriverOrderByField, rollback } = driverResult;
       const initialChunkSize = self.api.options.pageSize;
+      const isInMemorySort = !isDriverOrderByField && orderByField;
       try {
-        if (!isDriverOrderByField && orderByField) {
+        if (isInMemorySort) {
           const topK = limit === Infinity ? Infinity : offset + limit;
           let heap = null;
           if (topK !== Infinity) {
@@ -11665,12 +11756,6 @@ var MutationManager = class {
       document: dataplyDocument
     };
   }
-  /**
-   * Insert a document into the database
-   * @param document The document to insert
-   * @param tx The transaction to use
-   * @returns The primary key of the inserted document
-   */
   async insertSingleDocument(document, tx) {
     return this.api.runWithDefaultWrite(async (tx2) => {
       const { pk: dpk, document: dataplyDocument } = await this.insertDocumentInternal(document, tx2);
@@ -11697,15 +11782,10 @@ var MutationManager = class {
           if (error) throw error;
         }
       }
+      await this.api.analysisManager.notifyInsert([flattenDocument], tx2);
       return dataplyDocument._id;
     }, tx);
   }
-  /**
-   * Insert a batch of documents into the database
-   * @param documents The documents to insert
-   * @param tx The transaction to use
-   * @returns The primary keys of the inserted documents
-   */
   async insertBatchDocuments(documents, tx) {
     return this.api.runWithDefaultWrite(async (tx2) => {
       const metadata = await this.api.getDocumentInnerMetadata(tx2);
@@ -11765,19 +11845,18 @@ var MutationManager = class {
           throw res.error;
         }
       }
+      const flatDocs = [];
+      for (let i = 0, len = flattenedData.length; i < len; i++) {
+        flatDocs.push(flattenedData[i].data);
+      }
+      await this.api.analysisManager.notifyInsert(flatDocs, tx2);
       return ids;
     }, tx);
   }
-  /**
-   * Internal update method used by both fullUpdate and partialUpdate
-   * @param query The query to use
-   * @param computeUpdatedDoc Function that computes the updated document from the original
-   * @param tx The transaction to use
-   * @returns The number of updated documents
-   */
   async updateInternal(query, computeUpdatedDoc, tx) {
     const pks = await this.api.queryManager.getKeys(query);
     let updatedCount = 0;
+    const updatePairs = [];
     const treeTxs = /* @__PURE__ */ new Map();
     for (const [indexName, tree] of this.api.trees) {
       treeTxs.set(indexName, await tree.createTransaction());
@@ -11825,6 +11904,7 @@ var MutationManager = class {
           }
         }
       }
+      updatePairs.push({ oldDocument: oldFlatDoc, newDocument: newFlatDoc });
       await this.api.update(pk, JSON.stringify(updatedDoc), tx);
       updatedCount++;
     }
@@ -11837,15 +11917,9 @@ var MutationManager = class {
         throw result.error;
       }
     }
+    await this.api.analysisManager.notifyUpdate(updatePairs, tx);
     return updatedCount;
   }
-  /**
-   * Fully update documents from the database that match the query
-   * @param query The query to use
-   * @param newRecord Complete document to replace with, or function that receives current document and returns new document
-   * @param tx The transaction to use
-   * @returns The number of updated documents
-   */
   async fullUpdate(query, newRecord, tx) {
     return this.api.runWithDefaultWrite(async (tx2) => {
       return this.updateInternal(query, (doc) => {
@@ -11854,13 +11928,6 @@ var MutationManager = class {
       }, tx2);
     }, tx);
   }
-  /**
-   * Partially update documents from the database that match the query
-   * @param query The query to use
-   * @param newRecord Partial document to merge, or function that receives current document and returns partial update
-   * @param tx The transaction to use
-   * @returns The number of updated documents
-   */
   async partialUpdate(query, newRecord, tx) {
     return this.api.runWithDefaultWrite(async (tx2) => {
       return this.updateInternal(query, (doc) => {
@@ -11871,16 +11938,11 @@ var MutationManager = class {
       }, tx2);
     }, tx);
   }
-  /**
-   * Delete documents from the database that match the query
-   * @param query The query to use
-   * @param tx The transaction to use
-   * @returns The number of deleted documents
-   */
   async deleteDocuments(query, tx) {
     return this.api.runWithDefaultWrite(async (tx2) => {
       const pks = await this.api.queryManager.getKeys(query);
       let deletedCount = 0;
+      const deletedFlatDocs = [];
       for (let i = 0, len = pks.length; i < len; i++) {
         const pk = pks[i];
         const doc = await this.api.getDocument(pk, tx2);
@@ -11904,9 +11966,11 @@ var MutationManager = class {
             await tree.delete(pk, { k: pk, v: indexVal });
           }
         }
+        deletedFlatDocs.push(flatDoc);
         await this.api.delete(pk, true, tx2);
         deletedCount++;
       }
+      await this.api.analysisManager.notifyDelete(deletedFlatDocs, tx2);
       return deletedCount;
     }, tx);
   }
@@ -11945,13 +12009,6 @@ var MetadataManager = class {
   async updateDocumentInnerMetadata(metadata, tx) {
     await this.api.update(1, JSON.stringify(metadata), tx);
   }
-  /**
-   * Run a migration if the current schemeVersion is lower than the target version.
-   * After the callback completes, schemeVersion is updated to the target version.
-   * @param version The target scheme version
-   * @param callback The migration callback
-   * @param tx Optional transaction
-   */
   async migration(version, callback, tx) {
     await this.api.runWithDefaultWrite(async (tx2) => {
       const innerMetadata = await this.getDocumentInnerMetadata(tx2);
@@ -11980,16 +12037,392 @@ var DocumentFormatter = class {
     }
     return result;
   }
-  /**
-   * returns flattened document
-   * @param document
-   * @returns
-   */
   flattenDocument(document) {
     return this.flattenInternal(document, "", {});
   }
 };
 
+// src/core/AnalysisProvider.ts
+var AnalysisProvider = class {
+  constructor(api) {
+    this.api = api;
+  }
+  /** Overflow row PK assigned by AnalysisManager during initialization. */
+  storageKey = -1;
+};
+
+// src/core/RealtimeAnalysisProvider.ts
+var RealtimeAnalysisProvider = class extends AnalysisProvider {
+};
+
+// src/core/IntervalAnalysisProvider.ts
+var IntervalAnalysisProvider = class extends AnalysisProvider {
+  /**
+   * Sample random documents from the entire dataset.
+   * Fetches only PK index, then reads only the selected documents from disk.
+   * @param sampleOptions Sampling strategy — either `{ rate }` or `{ count }`
+   * @param tx Optional transaction
+   * @returns Randomly selected documents
+   */
+  async sample(sampleOptions, tx) {
+    const pks = await this.api.queryManager.getKeys({});
+    const total = pks.length;
+    if (total === 0) return [];
+    const k = "rate" in sampleOptions && sampleOptions.rate != null ? Math.ceil(total * Math.min(Math.max(sampleOptions.rate, 0), 1)) : sampleOptions.count;
+    const sampleCount = Math.min(Math.max(k, 0), total);
+    if (sampleCount === 0) return [];
+    for (let i = 0; i < sampleCount; i++) {
+      const j = i + Math.floor(Math.random() * (total - i));
+      const tmp = pks[i];
+      pks[i] = pks[j];
+      pks[j] = tmp;
+    }
+    const selectedPks = pks.slice(0, sampleCount);
+    const rawResults = await this.api.selectMany(selectedPks, false, tx);
+    const docs = [];
+    for (let i = 0, len = rawResults.length; i < len; i++) {
+      const raw = rawResults[i];
+      if (raw) docs.push(JSON.parse(raw));
+    }
+    return docs;
+  }
+};
+
+// src/core/analysis/FTSTermCount.ts
+var FTSTermCount = class extends IntervalAnalysisProvider {
+  name = "fts_term_count";
+  termCount = {};
+  sampleSize = 0;
+  async serialize(tx) {
+    const docs = await this.sample({ count: 1e3 }, tx);
+    this.termCount = {};
+    this.sampleSize = docs.length;
+    if (docs.length === 0) return JSON.stringify({ _sampleSize: 0 });
+    const ftsIndices = /* @__PURE__ */ new Map();
+    for (const [indexName, config] of this.api.indexManager.registeredIndices) {
+      if (config.type === "fts") {
+        ftsIndices.set(indexName, config);
+      }
+    }
+    if (ftsIndices.size === 0) return JSON.stringify({ _sampleSize: this.sampleSize });
+    for (let i = 0, len = docs.length; i < len; i++) {
+      const doc = docs[i];
+      const flatDoc = this.api.flattenDocument(doc);
+      for (const [indexName, config] of ftsIndices) {
+        const primaryField = this.api.indexManager.getPrimaryField(config);
+        const v = flatDoc[primaryField];
+        if (typeof v === "string" && v.length > 0) {
+          const ftsConfig = this.api.indexManager.getFtsConfig(config);
+          const tokens = ftsConfig ? tokenize(v, ftsConfig) : [v];
+          const tokenizerStrategy = ftsConfig ? ftsConfig.tokenizer === "ngram" ? `${ftsConfig.gramSize}gram` : ftsConfig.tokenizer : "whitespace";
+          if (!this.termCount[primaryField]) {
+            this.termCount[primaryField] = {};
+          }
+          if (!this.termCount[primaryField][tokenizerStrategy]) {
+            this.termCount[primaryField][tokenizerStrategy] = {};
+          }
+          const targetMap = this.termCount[primaryField][tokenizerStrategy];
+          for (let j = 0, len2 = tokens.length; j < len2; j++) {
+            const token = tokens[j];
+            targetMap[token] = (targetMap[token] || 0) + 1;
+          }
+        }
+      }
+    }
+    const optimizedTermCount = {};
+    for (const field in this.termCount) {
+      optimizedTermCount[field] = {};
+      for (const strategy in this.termCount[field]) {
+        const tokenMap = this.termCount[field][strategy];
+        const sorted = Object.entries(tokenMap).sort((a, b) => b[1] - a[1]).slice(0, 1e3);
+        optimizedTermCount[field][strategy] = {};
+        for (let i = 0, len = sorted.length; i < len; i++) {
+          optimizedTermCount[field][strategy][sorted[i][0]] = sorted[i][1];
+        }
+      }
+    }
+    this.termCount = optimizedTermCount;
+    return JSON.stringify({ _sampleSize: this.sampleSize, ...this.termCount });
+  }
+  async load(data, tx) {
+    this.termCount = {};
+    this.sampleSize = 0;
+    if (!data) {
+      return;
+    }
+    try {
+      const parsed = JSON.parse(data);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        const { _sampleSize, ...rest } = parsed;
+        this.sampleSize = typeof _sampleSize === "number" ? _sampleSize : 0;
+        this.termCount = rest;
+      }
+    } catch (e) {
+    }
+  }
+  /**
+   * 특정 field/strategy/token의 문서 빈도를 반환합니다.
+   * 통계에 없으면 0을 반환합니다.
+   */
+  getTermCount(field, strategy, token) {
+    return this.termCount[field]?.[strategy]?.[token] ?? 0;
+  }
+  /**
+   * 쿼리 토큰 배열에서 최소 빈도(AND 시맨틱스 상한선)를 반환합니다.
+   * 통계가 없거나 sampleSize가 0이면 -1을 반환합니다.
+   */
+  getMinTokenCount(field, strategy, tokens) {
+    if (this.sampleSize === 0 || tokens.length === 0) return -1;
+    let minCount = Infinity;
+    for (let i = 0, len = tokens.length; i < len; i++) {
+      const count = this.getTermCount(field, strategy, tokens[i]);
+      if (count < minCount) minCount = count;
+    }
+    return minCount === Infinity ? -1 : minCount;
+  }
+  /**
+   * 통계가 유효한지 여부를 반환합니다.
+   */
+  get hasSampleData() {
+    return this.sampleSize > 0;
+  }
+  /**
+   * 통계 수집 시 사용된 샘플 크기를 반환합니다.
+   */
+  getSampleSize() {
+    return this.sampleSize;
+  }
+};
+
+// src/core/analysis/index.ts
+var BuiltinAnalysisProviders = [
+  FTSTermCount
+];
+
+// src/core/AnalysisManager.ts
+var AnalysisManager = class {
+  constructor(api) {
+    this.api = api;
+  }
+  providers = /* @__PURE__ */ new Map();
+  /**
+   * Register all built-in analysis providers.
+   * Each provider class is instantiated with the API reference and registered.
+   */
+  registerBuiltinProviders() {
+    for (const Provider of BuiltinAnalysisProviders) {
+      const instance = new Provider(this.api);
+      this.registerProvider(instance);
+    }
+  }
+  /**
+   * Register an analysis provider.
+   * @param provider The provider instance to register
+   */
+  registerProvider(provider) {
+    if (this.providers.has(provider.name)) {
+      throw new Error(`Analysis provider "${provider.name}" is already registered.`);
+    }
+    this.providers.set(provider.name, provider);
+  }
+  /**
+   * Get a registered analysis provider by name.
+   * @param name The provider name
+   * @returns The provider instance, or null if not found
+   */
+  getProvider(name) {
+    return this.providers.get(name) ?? null;
+  }
+  /**
+   * Initialize all registered providers by loading existing data from disk.
+   * Should be called after database initialization.
+   * @param tx The transaction to use
+   */
+  async initializeProviders(tx) {
+    const header = await this.getOrCreateAnalysisHeader(tx);
+    const metadata = await this.api.getDocumentInnerMetadata(tx);
+    for (const [name, provider] of this.providers) {
+      if (header[name] !== null) {
+        provider.storageKey = header[name];
+        const raw = await this.api.select(header[name], false, tx);
+        await provider.load(raw, tx);
+      } else {
+        const pk = await this.api.insertAsOverflow(JSON.stringify(null), false, tx);
+        provider.storageKey = pk;
+        header[name] = pk;
+        await this.api.update(metadata.analysis, JSON.stringify(header), tx);
+        await provider.load(null, tx);
+      }
+    }
+  }
+  /**
+   * Notify all realtime providers that documents were inserted.
+   * Data is persisted immediately after each provider processes the mutation.
+   * @param documents The flattened documents that were inserted
+   * @param tx The transaction to use
+   */
+  async notifyInsert(documents, tx) {
+    if (documents.length === 0) return;
+    for (const [name, provider] of this.providers) {
+      if (provider instanceof RealtimeAnalysisProvider) {
+        await provider.onInsert(documents);
+        await this.setAnalysisData(name, await provider.serialize(tx), tx);
+      }
+    }
+  }
+  /**
+   * Notify all realtime providers that documents were deleted.
+   * Data is persisted immediately after each provider processes the mutation.
+   * @param documents The flattened documents that were deleted
+   * @param tx The transaction to use
+   */
+  async notifyDelete(documents, tx) {
+    if (documents.length === 0) return;
+    for (const [name, provider] of this.providers) {
+      if (provider instanceof RealtimeAnalysisProvider) {
+        await provider.onDelete(documents);
+        await this.setAnalysisData(name, await provider.serialize(tx), tx);
+      }
+    }
+  }
+  /**
+   * Notify all realtime providers that documents were updated.
+   * Data is persisted immediately after each provider processes the mutation.
+   * @param pairs Array of { oldDocument, newDocument } pairs
+   * @param tx The transaction to use
+   */
+  async notifyUpdate(pairs, tx) {
+    if (pairs.length === 0) return;
+    for (const [name, provider] of this.providers) {
+      if (provider instanceof RealtimeAnalysisProvider) {
+        await provider.onUpdate(pairs);
+        await this.setAnalysisData(name, await provider.serialize(tx), tx);
+      }
+    }
+  }
+  /**
+   * Flush all interval providers' data to disk.
+   * @param tx The transaction to use (must be a write transaction)
+   */
+  async flush(tx) {
+    for (const [name, provider] of this.providers) {
+      if (provider instanceof IntervalAnalysisProvider) {
+        await this.setAnalysisData(name, await provider.serialize(tx), tx);
+      }
+    }
+  }
+  /**
+   * Get the analysis header row.
+   * Returns null if no analysis header exists yet.
+   * @param tx The transaction to use
+   */
+  async getAnalysisHeader(tx) {
+    const metadata = await this.api.getDocumentInnerMetadata(tx);
+    if (metadata.analysis == null) {
+      return null;
+    }
+    const row = await this.api.select(metadata.analysis, false, tx);
+    if (!row) {
+      return null;
+    }
+    return JSON.parse(row);
+  }
+  /**
+   * Get the analysis header row, creating it if it doesn't exist.
+   * @param tx The transaction to use (must be a write transaction)
+   */
+  async getOrCreateAnalysisHeader(tx) {
+    const metadata = await this.api.getDocumentInnerMetadata(tx);
+    if (metadata.analysis != null) {
+      const row = await this.api.select(metadata.analysis, false, tx);
+      if (row) {
+        return JSON.parse(row);
+      }
+    }
+    const header = {};
+    const pk = await this.api.insertAsOverflow(JSON.stringify(header), false, tx);
+    metadata.analysis = pk;
+    await this.api.updateDocumentInnerMetadata(metadata, tx);
+    return header;
+  }
+  /**
+   * Get analysis data for a specific type as a raw string.
+   * Returns null if the type doesn't exist in the analysis header.
+   * @param type The analysis type name
+   * @param tx The transaction to use
+   */
+  async getAnalysisData(type, tx) {
+    const header = await this.getAnalysisHeader(tx);
+    if (!header || header[type] == null) {
+      return null;
+    }
+    const row = await this.api.select(header[type], false, tx);
+    if (!row) {
+      return null;
+    }
+    return row;
+  }
+  /**
+   * Set analysis data for a specific type.
+   * Creates a new overflow row if the type doesn't exist yet,
+   * or updates the existing row if it does.
+   * @param type The analysis type name
+   * @param data The raw string data to store
+   * @param tx The transaction to use (must be a write transaction)
+   */
+  async setAnalysisData(type, data, tx) {
+    const header = await this.getOrCreateAnalysisHeader(tx);
+    const metadata = await this.api.getDocumentInnerMetadata(tx);
+    if (header[type] != null) {
+      await this.api.update(header[type], data, tx);
+    } else {
+      const pk = await this.api.insertAsOverflow(data, false, tx);
+      header[type] = pk;
+      await this.api.update(metadata.analysis, JSON.stringify(header), tx);
+    }
+  }
+  /**
+   * Delete analysis data for a specific type.
+   * Removes the type entry from the analysis header.
+   * @param type The analysis type name
+   * @param tx The transaction to use (must be a write transaction)
+   */
+  async deleteAnalysisData(type, tx) {
+    const metadata = await this.api.getDocumentInnerMetadata(tx);
+    if (metadata.analysis == null) {
+      return false;
+    }
+    const header = await this.getAnalysisHeader(tx);
+    if (!header || header[type] == null) {
+      return false;
+    }
+    await this.api.delete(header[type], false, tx);
+    delete header[type];
+    await this.api.update(metadata.analysis, JSON.stringify(header), tx);
+    return true;
+  }
+  /**
+   * Check if analysis data exists for a specific type.
+   * @param type The analysis type name
+   * @param tx The transaction to use
+   */
+  async hasAnalysisData(type, tx) {
+    const header = await this.getAnalysisHeader(tx);
+    return header != null && header[type] != null;
+  }
+  /**
+   * Get all registered analysis type names.
+   * @param tx The transaction to use
+   */
+  async getAnalysisTypes(tx) {
+    const header = await this.getAnalysisHeader(tx);
+    if (!header) {
+      return [];
+    }
+    return Object.keys(header);
+  }
+};
+
 // src/core/documentAPI.ts
 var DocumentDataplyAPI = class extends import_dataply4.DataplyAPI {
   comparator = new DocumentValueComparator();
@@ -12000,6 +12433,7 @@ var DocumentDataplyAPI = class extends import_dataply4.DataplyAPI {
   mutationManager;
   metadataManager;
   documentFormatter;
+  analysisManager;
   constructor(file, options) {
     super(file, options);
     this.optimizer = new Optimizer(this);
@@ -12008,6 +12442,7 @@ var DocumentDataplyAPI = class extends import_dataply4.DataplyAPI {
     this.mutationManager = new MutationManager(this);
     this.metadataManager = new MetadataManager(this);
     this.documentFormatter = new DocumentFormatter();
+    this.analysisManager = new AnalysisManager(this);
     this.hook.onceAfter("init", async (tx, isNewlyCreated) => {
       if (isNewlyCreated) {
         await this.initializeDocumentFile(tx);
@@ -12017,6 +12452,8 @@ var DocumentDataplyAPI = class extends import_dataply4.DataplyAPI {
       }
       const metadata = await this.getDocumentInnerMetadata(tx);
       await this.indexManager.initializeIndices(metadata, isNewlyCreated, tx);
+      this.analysisManager.registerBuiltinProviders();
+      await this.analysisManager.initializeProviders(tx);
       this._initialized = true;
       return tx;
     });
@@ -12036,15 +12473,29 @@ var DocumentDataplyAPI = class extends import_dataply4.DataplyAPI {
   get indexedFields() {
     return this.indexManager.indexedFields;
   }
+  /**
+   * Register an index.
+   * @param name The name of the index
+   * @param option The option of the index
+   * @param tx The transaction to use
+   */
   async registerIndex(name, option, tx) {
     return this.indexManager.registerIndex(name, option, tx);
   }
   /**
    * Drop (remove) a named index.
+   * @param name The name of the index
+   * @param tx The transaction to use
    */
   async dropIndex(name, tx) {
     return this.indexManager.dropIndex(name, tx);
   }
+  /**
+   * Get a document by its primary key.
+   * @param pk The primary key of the document
+   * @param tx The transaction to use
+   * @returns The document
+   */
   async getDocument(pk, tx) {
     return this.runWithDefault(async (tx2) => {
       const row = await this.select(pk, false, tx2);
@@ -12061,6 +12512,16 @@ var DocumentDataplyAPI = class extends import_dataply4.DataplyAPI {
   async backfillIndices(tx) {
     return this.indexManager.backfillIndices(tx);
   }
+  /**
+   * Flush all interval analysis providers, forcing statistics to be recalculated.
+   * Call this after bulk inserts or periodically to keep statistics fresh.
+   * @param tx The transaction to use
+   */
+  async flushAnalysis(tx) {
+    return this.runWithDefaultWrite(async (tx2) => {
+      await this.analysisManager.flush(tx2);
+    }, tx);
+  }
   createDocumentInnerMetadata(indices) {
     return {
       magicString: "document-dataply",
@@ -12072,16 +12533,28 @@ var DocumentDataplyAPI = class extends import_dataply4.DataplyAPI {
       indices
     };
   }
+  /**
+   * Initialize the document database file.
+   * @param tx The transaction to use
+   */
   async initializeDocumentFile(tx) {
     const metadata = await this.select(1, false, tx);
     if (metadata) {
       throw new Error("Document metadata already exists");
     }
     const metaObj = this.createDocumentInnerMetadata({
-      _id: [-1, { type: "btree", fields: ["_id"] }]
+      _id: [-1, {
+        type: "btree",
+        fields: ["_id"]
+      }]
     });
     await this.insertAsOverflow(JSON.stringify(metaObj), false, tx);
   }
+  /**
+   * Verify the document database file.
+   * @param tx The transaction to use
+   * @returns True if the document database file is valid, false otherwise
+   */
   async verifyDocumentFile(tx) {
     const row = await this.select(1, false, tx);
     if (!row) {
@@ -12098,12 +12571,27 @@ var DocumentDataplyAPI = class extends import_dataply4.DataplyAPI {
   flattenDocument(document) {
     return this.documentFormatter.flattenDocument(document);
   }
+  /**
+   * Get the document metadata.
+   * @param tx The transaction to use
+   * @returns The document metadata
+   */
   async getDocumentMetadata(tx) {
     return this.metadataManager.getDocumentMetadata(tx);
   }
+  /**
+   * Get the document inner metadata.
+   * @param tx The transaction to use
+   * @returns The document inner metadata
+   */
   async getDocumentInnerMetadata(tx) {
     return this.metadataManager.getDocumentInnerMetadata(tx);
   }
+  /**
+   * Update the document inner metadata.
+   * @param metadata The document inner metadata
+   * @param tx The transaction to use
+   */
   async updateDocumentInnerMetadata(metadata, tx) {
     return this.metadataManager.updateDocumentInnerMetadata(metadata, tx);
   }
@@ -12255,6 +12743,14 @@ var DocumentDataply = class _DocumentDataply {
     await this.api.init();
     await this.api.backfillIndices();
   }
+  /**
+   * Flush all interval analysis providers, forcing statistics to be recalculated.
+   * Call this after bulk inserts or periodically to keep FTS statistics fresh.
+   * @param tx Optional transaction
+   */
+  async flushAnalysis(tx) {
+    return this.api.flushAnalysis(tx);
+  }
   /**
    * Run a migration if the current schemeVersion is lower than the target version.
    * The callback is only executed when the database's schemeVersion is below the given version.