document-dataply 0.0.9-alpha.0 → 0.0.9-alpha.1

package/dist/cjs/index.js

@@ -10043,22 +10043,46 @@ var DocumentSerializeStrategyAsync = class extends import_dataply.SerializeStrat
 
 // src/core/bptree/documentComparator.ts
 var import_dataply2 = __toESM(require_cjs());
+function comparePrimitive(a, b) {
+  if (a === b) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  if (typeof a !== typeof b) {
+    const typeOrder = (v) => typeof v === "boolean" ? 0 : typeof v === "number" ? 1 : 2;
+    return typeOrder(a) - typeOrder(b);
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    return a.localeCompare(b);
+  }
+  return +a - +b;
+}
+function compareValue(a, b) {
+  const aArr = Array.isArray(a);
+  const bArr = Array.isArray(b);
+  if (!aArr && !bArr) {
+    return comparePrimitive(a, b);
+  }
+  const aList = aArr ? a : [a];
+  const bList = bArr ? b : [b];
+  const len = Math.min(aList.length, bList.length);
+  for (let i = 0; i < len; i++) {
+    const diff = comparePrimitive(aList[i], bList[i]);
+    if (diff !== 0) return diff;
+  }
+  return aList.length - bList.length;
+}
 var DocumentValueComparator = class extends import_dataply2.ValueComparator {
   primaryAsc(a, b) {
-    if (typeof a.v !== "string" || typeof b.v !== "string") {
-      return +a.v - +b.v;
-    }
-    return a.v.localeCompare(b.v);
+    return compareValue(a.v, b.v);
   }
   asc(a, b) {
-    if (typeof a.v !== "string" || typeof b.v !== "string") {
-      const diff2 = +a.v - +b.v;
-      return diff2 === 0 ? a.k - b.k : diff2;
-    }
-    const diff = a.v.localeCompare(b.v);
+    const diff = compareValue(a.v, b.v);
     return diff === 0 ? a.k - b.k : diff;
   }
   match(value) {
+    if (Array.isArray(value.v)) {
+      return value.v[0] + "";
+    }
     return value.v + "";
   }
 };
@@ -10171,7 +10195,23 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   comparator = new DocumentValueComparator();
   pendingBackfillFields = [];
   lock;
+  _initialized = false;
   indexedFields;
+  /**
+   * Registered indices via createIndex() (before init)
+   * Key: index name, Value: index configuration
+   */
+  pendingCreateIndices = /* @__PURE__ */ new Map();
+  /**
+   * Resolved index configurations after init.
+   * Key: index name, Value: index config (from metadata)
+   */
+  registeredIndices = /* @__PURE__ */ new Map();
+  /**
+   * Maps field name → index names that cover this field.
+   * Used for query resolution.
+   */
+  fieldToIndices = /* @__PURE__ */ new Map();
   operatorConverters = {
     equal: "primaryEqual",
     notEqual: "primaryNotEqual",
@@ -10187,11 +10227,6 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     this.trees = /* @__PURE__ */ new Map();
     this.lock = new import_dataply3.Ryoiki();
     this.indexedFields = /* @__PURE__ */ new Set(["_id"]);
-    if (options?.indices) {
-      for (const field of Object.keys(options.indices)) {
-        this.indexedFields.add(field);
-      }
-    }
     this.hook.onceAfter("init", async (tx, isNewlyCreated) => {
       if (isNewlyCreated) {
         await this.initializeDocumentFile(tx);
@@ -10200,31 +10235,30 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         throw new Error("Document metadata verification failed");
       }
       const metadata = await this.getDocumentInnerMetadata(tx);
-      const optionsIndices = options.indices ?? {};
-      const targetIndices = {
-        ...optionsIndices,
-        _id: true
-      };
+      const targetIndices = /* @__PURE__ */ new Map();
+      targetIndices.set("_id", { type: "btree", fields: ["_id"] });
+      for (const [name, option] of this.pendingCreateIndices) {
+        const config = this.toIndexMetaConfig(option);
+        targetIndices.set(name, config);
+      }
       const backfillTargets = [];
       let isMetadataChanged = false;
-      for (const field in targetIndices) {
-        const isBackfillEnabled = targetIndices[field];
-        const existingIndex = metadata.indices[field];
+      for (const [indexName, config] of targetIndices) {
+        const existingIndex = metadata.indices[indexName];
         if (!existingIndex) {
-          metadata.indices[field] = [-1, isBackfillEnabled];
+          metadata.indices[indexName] = [-1, config];
           isMetadataChanged = true;
-          if (isBackfillEnabled && !isNewlyCreated) {
-            backfillTargets.push(field);
+          if (!isNewlyCreated) {
+            backfillTargets.push(indexName);
           }
         } else {
-          const [_pk, isMetaBackfillEnabled] = existingIndex;
-          if (isBackfillEnabled && !isMetaBackfillEnabled) {
-            metadata.indices[field][1] = isBackfillEnabled;
-            isMetadataChanged = true;
-            backfillTargets.push(field);
-          } else if (!isBackfillEnabled && isMetaBackfillEnabled) {
-            metadata.indices[field][1] = false;
+          const [_pk, existingConfig] = existingIndex;
+          if (JSON.stringify(existingConfig) !== JSON.stringify(config)) {
+            metadata.indices[indexName] = [_pk, config];
             isMetadataChanged = true;
+            if (!isNewlyCreated) {
+              backfillTargets.push(indexName);
+            }
           }
         }
       }
@@ -10232,25 +10266,220 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         await this.updateDocumentInnerMetadata(metadata, tx);
       }
       this.indices = metadata.indices;
-      for (const field in this.indices) {
-        if (field in targetIndices) {
+      this.registeredIndices = /* @__PURE__ */ new Map();
+      this.fieldToIndices = /* @__PURE__ */ new Map();
+      for (const [indexName, config] of targetIndices) {
+        this.registeredIndices.set(indexName, config);
+        const fields = this.getFieldsFromConfig(config);
+        for (const field of fields) {
+          this.indexedFields.add(field);
+          if (!this.fieldToIndices.has(field)) {
+            this.fieldToIndices.set(field, []);
+          }
+          this.fieldToIndices.get(field).push(indexName);
+        }
+      }
+      for (const indexName of targetIndices.keys()) {
+        if (metadata.indices[indexName]) {
           const tree = new import_dataply3.BPTreeAsync(
             new DocumentSerializeStrategyAsync(
               this.rowTableEngine.order,
               this,
               this.txContext,
-              field
+              indexName
             ),
             this.comparator
           );
           await tree.init();
-          this.trees.set(field, tree);
+          this.trees.set(indexName, tree);
         }
       }
       this.pendingBackfillFields = backfillTargets;
+      this._initialized = true;
       return tx;
     });
   }
+  /**
+   * Whether the document database has been initialized.
+   */
+  get isDocInitialized() {
+    return this._initialized;
+  }
+  /**
+   * Register an index. If called before init(), queues it for processing during init.
+   * If called after init(), immediately creates the tree, updates metadata, and backfills.
+   */
+  async registerIndex(name, option, tx) {
+    if (!this._initialized) {
+      this.pendingCreateIndices.set(name, option);
+      return;
+    }
+    await this.registerIndexRuntime(name, option, tx);
+  }
+  /**
+   * Register an index at runtime (after init).
+   * Creates the tree, updates metadata, and backfills existing data.
+   */
+  async registerIndexRuntime(name, option, tx) {
+    const config = this.toIndexMetaConfig(option);
+    if (this.registeredIndices.has(name)) {
+      const existing = this.registeredIndices.get(name);
+      if (JSON.stringify(existing) === JSON.stringify(config)) return;
+    }
+    await this.runWithDefault(async (tx2) => {
+      const metadata = await this.getDocumentInnerMetadata(tx2);
+      metadata.indices[name] = [-1, config];
+      await this.updateDocumentInnerMetadata(metadata, tx2);
+      this.indices = metadata.indices;
+      this.registeredIndices.set(name, config);
+      const fields = this.getFieldsFromConfig(config);
+      for (const field of fields) {
+        this.indexedFields.add(field);
+        if (!this.fieldToIndices.has(field)) {
+          this.fieldToIndices.set(field, []);
+        }
+        this.fieldToIndices.get(field).push(name);
+      }
+      const tree = new import_dataply3.BPTreeAsync(
+        new DocumentSerializeStrategyAsync(
+          this.rowTableEngine.order,
+          this,
+          this.txContext,
+          name
+        ),
+        this.comparator
+      );
+      await tree.init();
+      this.trees.set(name, tree);
+      if (metadata.lastId > 0) {
+        this.pendingBackfillFields = [name];
+        await this.backfillIndices(tx2);
+      }
+    }, tx);
+  }
+  /**
+   * Drop (remove) a named index.
+   * Removes the index from metadata, in-memory maps, and trees.
+   * The '_id' index cannot be dropped.
+   * @param name The name of the index to drop
+   */
+  async dropIndex(name, tx) {
+    if (name === "_id") {
+      throw new Error("Cannot drop the _id index");
+    }
+    if (!this._initialized) {
+      this.pendingCreateIndices.delete(name);
+      return;
+    }
+    if (!this.registeredIndices.has(name)) {
+      throw new Error(`Index '${name}' does not exist`);
+    }
+    await this.runWithDefault(async (tx2) => {
+      const config = this.registeredIndices.get(name);
+      const metadata = await this.getDocumentInnerMetadata(tx2);
+      delete metadata.indices[name];
+      await this.updateDocumentInnerMetadata(metadata, tx2);
+      this.indices = metadata.indices;
+      this.registeredIndices.delete(name);
+      const fields = this.getFieldsFromConfig(config);
+      for (const field of fields) {
+        const indexNames = this.fieldToIndices.get(field);
+        if (indexNames) {
+          const filtered = indexNames.filter((n) => n !== name);
+          if (filtered.length === 0) {
+            this.fieldToIndices.delete(field);
+            if (field !== "_id") {
+              this.indexedFields.delete(field);
+            }
+          } else {
+            this.fieldToIndices.set(field, filtered);
+          }
+        }
+      }
+      this.trees.delete(name);
+    }, tx);
+  }
+  /**
+   * Convert CreateIndexOption to IndexMetaConfig for metadata storage.
+   */
+  toIndexMetaConfig(option) {
+    if (option.type === "btree") {
+      return {
+        type: "btree",
+        fields: option.fields
+      };
+    }
+    if (option.type === "fts") {
+      if (option.tokenizer === "ngram") {
+        return {
+          type: "fts",
+          fields: option.fields,
+          tokenizer: "ngram",
+          gramSize: option.ngram
+        };
+      }
+      return {
+        type: "fts",
+        fields: option.fields,
+        tokenizer: "whitespace"
+      };
+    }
+    throw new Error(`Unknown index type: ${option.type}`);
+  }
+  /**
+   * Get all field names from an IndexMetaConfig.
+   */
+  getFieldsFromConfig(config) {
+    if (config.type === "btree") {
+      return config.fields;
+    }
+    if (config.type === "fts") {
+      return [config.fields];
+    }
+    return [];
+  }
+  /**
+   * Get the primary field of an index (the field used as tree key).
+   * For btree: first field in fields array.
+   * For fts: the single field.
+   */
+  getPrimaryField(config) {
+    if (config.type === "btree") {
+      return config.fields[0];
+    }
+    return config.fields;
+  }
+  /**
+   * 인덱스 config에 따라 B+tree에 저장할 v 값을 생성합니다.
+   * - 단일 필드 btree: Primitive (단일 값)
+   * - 복합 필드 btree: Primitive[] (필드 순서대로 배열)
+   * - fts: 별도 처리 (이 메서드 사용 안 함)
+   * @returns undefined면 해당 문서에 필수 필드가 없으므로 인덱싱 스킵
+   */
+  getIndexValue(config, flatDoc) {
+    if (config.type !== "btree") return void 0;
+    if (config.fields.length === 1) {
+      const v = flatDoc[config.fields[0]];
+      return v === void 0 ? void 0 : v;
+    }
+    const values = [];
+    for (let i = 0, len = config.fields.length; i < len; i++) {
+      const v = flatDoc[config.fields[i]];
+      if (v === void 0) return void 0;
+      values.push(v);
+    }
+    return values;
+  }
+  /**
+   * Get FTSConfig from IndexMetaConfig (for tokenizer compatibility).
+   */
+  getFtsConfig(config) {
+    if (config.type !== "fts") return null;
+    if (config.tokenizer === "ngram") {
+      return { type: "fts", tokenizer: "ngram", gramSize: config.gramSize };
+    }
+    return { type: "fts", tokenizer: "whitespace" };
+  }
   async getDocument(pk, tx) {
     return this.runWithDefault(async (tx2) => {
       const row = await this.select(pk, false, tx2);
@@ -10279,10 +10508,9 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     });
   }
   /**
-   * Backfill indices for fields that were added with `true` option after data was inserted.
-   * This method should be called after `init()` if you want to index existing documents
-   * for newly added index fields.
-   * 
+   * Backfill indices for newly created indices after data was inserted.
+   * This method should be called after `init()`.
+   *
    * @returns Number of documents that were backfilled
    */
   async backfillIndices(tx) {
@@ -10295,12 +10523,12 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       if (metadata.lastId === 0) {
         return 0;
       }
-      const fieldTxMap = {};
-      const fieldMap = /* @__PURE__ */ new Map();
-      for (const field of backfillTargets) {
-        const tree = this.trees.get(field);
-        if (tree && field !== "_id") {
-          fieldTxMap[field] = await tree.createTransaction();
+      const indexTxMap = {};
+      const indexEntryMap = /* @__PURE__ */ new Map();
+      for (const indexName of backfillTargets) {
+        const tree = this.trees.get(indexName);
+        if (tree && indexName !== "_id") {
+          indexTxMap[indexName] = await tree.createTransaction();
         }
       }
       let backfilledCount = 0;
@@ -10315,35 +10543,44 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         const doc = await this.getDocument(k, tx2);
         if (!doc) continue;
         const flatDoc = this.flattenDocument(doc);
-        for (const field of backfillTargets) {
-          if (!(field in flatDoc) || // 문서에 해당 필드가 없음
-          !(field in fieldTxMap)) {
-            continue;
-          }
-          const v = flatDoc[field];
-          const btx = fieldTxMap[field];
-          const indexConfig = metadata.indices[field]?.[1];
-          const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts" && typeof v === "string";
-          let tokens = [v];
-          if (isFts) {
-            tokens = tokenize(v, indexConfig);
-          }
-          const batchInsertData = [];
-          for (let i = 0, len = tokens.length; i < len; i++) {
-            const token = tokens[i];
-            const keyToInsert = isFts ? this.getTokenKey(k, token) : k;
-            const entry = { k, v: token };
-            batchInsertData.push([keyToInsert, entry]);
-            if (!fieldMap.has(btx)) {
-              fieldMap.set(btx, []);
+        for (const indexName of backfillTargets) {
+          if (!(indexName in indexTxMap)) continue;
+          const config = this.registeredIndices.get(indexName);
+          if (!config) continue;
+          const btx = indexTxMap[indexName];
+          if (config.type === "fts") {
+            const primaryField = this.getPrimaryField(config);
+            const v = flatDoc[primaryField];
+            if (v === void 0 || typeof v !== "string") continue;
+            const ftsConfig = this.getFtsConfig(config);
+            const tokens = ftsConfig ? tokenize(v, ftsConfig) : [v];
+            const batchInsertData = [];
+            for (let i = 0, len = tokens.length; i < len; i++) {
+              const token = tokens[i];
+              const keyToInsert = this.getTokenKey(k, token);
+              const entry = { k, v: token };
+              batchInsertData.push([keyToInsert, entry]);
+              if (!indexEntryMap.has(btx)) {
+                indexEntryMap.set(btx, []);
+              }
+              indexEntryMap.get(btx).push({ k: keyToInsert, v: entry });
+            }
+            await btx.batchInsert(batchInsertData);
+          } else {
+            const indexVal = this.getIndexValue(config, flatDoc);
+            if (indexVal === void 0) continue;
+            const entry = { k, v: indexVal };
+            const batchInsertData = [[k, entry]];
+            if (!indexEntryMap.has(btx)) {
+              indexEntryMap.set(btx, []);
             }
-            fieldMap.get(btx).push({ k: keyToInsert, v: entry });
+            indexEntryMap.get(btx).push(entry);
+            await btx.batchInsert(batchInsertData);
           }
-          await btx.batchInsert(batchInsertData);
         }
         backfilledCount++;
       }
-      const btxs = Object.values(fieldTxMap);
+      const btxs = Object.values(indexTxMap);
       const success = [];
       try {
         for (const btx of btxs) {
@@ -10355,7 +10592,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           await btx.rollback();
         }
         for (const btx of success) {
-          const entries = fieldMap.get(btx);
+          const entries = indexEntryMap.get(btx);
           if (!entries) continue;
           for (const entry of entries) {
             await btx.delete(entry.k, entry);
@@ -10374,6 +10611,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       createdAt: Date.now(),
       updatedAt: Date.now(),
       lastId: 0,
+      schemeVersion: 0,
       indices
     };
   }
@@ -10383,7 +10621,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       throw new Error("Document metadata already exists");
     }
     const metaObj = this.createDocumentInnerMetadata({
-      _id: [-1, true]
+      _id: [-1, { type: "btree", fields: ["_id"] }]
     });
     await this.insertAsOverflow(JSON.stringify(metaObj), false, tx);
   }
@@ -10408,18 +10646,27 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   }
   /**
    * returns flattened document
-   * @param document 
-   * @returns 
+   * @param document
+   * @returns
    */
   flattenDocument(document) {
     return this.flatten(document, "", {});
   }
   async getDocumentMetadata(tx) {
     const metadata = await this.getMetadata(tx);
+    const innerMetadata = await this.getDocumentInnerMetadata(tx);
+    const indices = [];
+    for (const name of this.registeredIndices.keys()) {
+      if (name !== "_id") {
+        indices.push(name);
+      }
+    }
     return {
       pageSize: metadata.pageSize,
       pageCount: metadata.pageCount,
-      rowCount: metadata.rowCount
+      rowCount: metadata.rowCount,
+      indices,
+      schemeVersion: innerMetadata.schemeVersion ?? 0
     };
   }
   async getDocumentInnerMetadata(tx) {
@@ -10432,6 +10679,25 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   async updateDocumentInnerMetadata(metadata, tx) {
     await this.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.runWithDefault(async (tx2) => {
+      const innerMetadata = await this.getDocumentInnerMetadata(tx2);
+      const currentVersion = innerMetadata.schemeVersion ?? 0;
+      if (currentVersion < version) {
+        await callback(tx2);
+        innerMetadata.schemeVersion = version;
+        innerMetadata.updatedAt = Date.now();
+        await this.updateDocumentInnerMetadata(innerMetadata, tx2);
+      }
+    }, tx);
+  }
   /**
    * Transforms a query object into a verbose query object
    * @param query The query object to transform
@@ -10470,33 +10736,74 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     return result;
   }
   /**
-   * Get the selectivity candidate for the given query
-   * @param query The query conditions
+   * Choose the best index (driver) for the given query.
+   * Scores each index based on field coverage and condition type.
+   *
+   * @param query The verbose query conditions
    * @param orderByField Optional field name for orderBy optimization
    * @returns Driver and other candidates for query execution
    */
   async getSelectivityCandidate(query, orderByField) {
+    const queryFields = new Set(Object.keys(query));
     const candidates = [];
-    const metadata = await this.getDocumentInnerMetadata(this.txContext.get());
-    for (const field in query) {
-      const tree = this.trees.get(field);
+    for (const [indexName, config] of this.registeredIndices) {
+      const tree = this.trees.get(indexName);
       if (!tree) continue;
-      const condition = query[field];
-      const treeTx = await tree.createTransaction();
-      const indexConfig = metadata.indices[field]?.[1];
-      let isFtsMatch = false;
-      let matchTokens;
-      if (typeof indexConfig === "object" && indexConfig?.type === "fts" && condition.match) {
-        isFtsMatch = true;
-        matchTokens = tokenize(condition.match, indexConfig);
-      }
-      candidates.push({
-        tree: treeTx,
-        condition,
-        field,
-        isFtsMatch,
-        matchTokens
-      });
+      if (config.type === "btree") {
+        const primaryField = config.fields[0];
+        if (!queryFields.has(primaryField)) continue;
+        const condition = query[primaryField];
+        const treeTx = await tree.createTransaction();
+        let score = 0;
+        const coveredFields = config.fields.filter((f) => queryFields.has(f));
+        score += coveredFields.length;
+        if (condition) {
+          if (typeof condition !== "object" || condition === null) {
+            score += 100;
+          } else if ("primaryEqual" in condition || "equal" in condition) {
+            score += 100;
+          } else if ("primaryGte" in condition || "primaryLte" in condition || "primaryGt" in condition || "primaryLt" in condition || "gte" in condition || "lte" in condition || "gt" in condition || "lt" in condition) {
+            score += 50;
+          } else if ("primaryOr" in condition || "or" in condition) {
+            score += 20;
+          } else if ("like" in condition) {
+            score += 15;
+          } else {
+            score += 10;
+          }
+        }
+        if (orderByField && primaryField === orderByField) {
+          score += 200;
+        }
+        const compositeVerifyFields = coveredFields.filter((f) => f !== primaryField);
+        candidates.push({
+          tree: treeTx,
+          condition,
+          field: primaryField,
+          indexName,
+          isFtsMatch: false,
+          score,
+          compositeVerifyFields
+        });
+      } 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,
+          indexName,
+          isFtsMatch: true,
+          matchTokens,
+          score: 90,
+          compositeVerifyFields: []
+        });
+      }
     }
     const rollback = () => {
       for (const { tree } of candidates) {
@@ -10507,41 +10814,19 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       rollback();
       return null;
     }
-    if (orderByField) {
-      const orderByCandidate = candidates.find((c) => c.field === orderByField);
-      if (orderByCandidate) {
-        return {
-          driver: orderByCandidate,
-          others: candidates.filter((c) => c.field !== orderByField),
-          rollback
-        };
-      }
-    }
-    const ftsCandidate = candidates.find(
-      (c) => c.isFtsMatch && c.matchTokens && c.matchTokens.length > 0
-    );
-    if (ftsCandidate) {
-      const hasHigherPriority = candidates.some((c) => {
-        if (c === ftsCandidate) return false;
-        const cond = c.condition;
-        return "equal" in cond || "primaryEqual" in cond;
-      });
-      if (!hasHigherPriority) {
-        return {
-          driver: ftsCandidate,
-          others: candidates.filter((c) => c !== ftsCandidate),
-          rollback
-        };
+    candidates.sort((a, b) => b.score - a.score);
+    const driver = candidates[0];
+    const others = candidates.slice(1);
+    const compositeVerifyConditions = [];
+    for (const field of driver.compositeVerifyFields) {
+      if (query[field]) {
+        compositeVerifyConditions.push({ field, condition: query[field] });
       }
     }
-    let res = import_dataply3.BPTreeAsync.ChooseDriver(candidates);
-    if (!res && candidates.length > 0) {
-      res = candidates[0];
-    }
-    if (!res) return null;
     return {
-      driver: res,
-      others: candidates.filter((c) => c.tree !== res.tree),
+      driver,
+      others,
+      compositeVerifyConditions,
       rollback
     };
   }
@@ -10634,7 +10919,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       orderBy
     );
     if (!selectivity) return null;
-    const { driver, others, rollback } = selectivity;
+    const { driver, others, compositeVerifyConditions, rollback } = selectivity;
     const useIndexOrder = orderBy === void 0 || driver.field === orderBy;
     const currentOrder = useIndexOrder ? sortOrder : void 0;
     let keys;
@@ -10651,6 +10936,8 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     return {
       keys: new Float64Array(Array.from(keys)),
       others,
+      compositeVerifyConditions,
+      isDriverOrderByField: useIndexOrder,
       rollback
     };
   }
@@ -10677,25 +10964,27 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   async insertSingleDocument(document, tx) {
     return this.writeLock(() => this.runWithDefault(async (tx2) => {
       const { pk: dpk, document: dataplyDocument } = await this.insertDocumentInternal(document, tx2);
-      const metadata = await this.getDocumentInnerMetadata(tx2);
       const flattenDocument = this.flattenDocument(dataplyDocument);
-      for (const field in flattenDocument) {
-        const tree = this.trees.get(field);
+      for (const [indexName, config] of this.registeredIndices) {
+        const tree = this.trees.get(indexName);
         if (!tree) continue;
-        const v = flattenDocument[field];
-        const indexConfig = metadata.indices[field]?.[1];
-        let tokens = [v];
-        const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts" && typeof v === "string";
-        if (isFts) {
-          tokens = tokenize(v, indexConfig);
-        }
-        for (let i = 0, len = tokens.length; i < len; i++) {
-          const token = tokens[i];
-          const keyToInsert = isFts ? this.getTokenKey(dpk, token) : dpk;
-          const [error] = await catchPromise(tree.insert(keyToInsert, { k: dpk, v: token }));
-          if (error) {
-            throw error;
+        if (config.type === "fts") {
+          const primaryField = this.getPrimaryField(config);
+          const v = flattenDocument[primaryField];
+          if (v === void 0 || typeof v !== "string") continue;
+          const ftsConfig = this.getFtsConfig(config);
+          const tokens = ftsConfig ? tokenize(v, ftsConfig) : [v];
+          for (let i = 0, len = tokens.length; i < len; i++) {
+            const token = tokens[i];
+            const keyToInsert = this.getTokenKey(dpk, token);
+            const [error] = await catchPromise(tree.insert(keyToInsert, { k: dpk, v: token }));
+            if (error) throw error;
           }
+        } else {
+          const indexVal = this.getIndexValue(config, flattenDocument);
+          if (indexVal === void 0) continue;
+          const [error] = await catchPromise(tree.insert(dpk, { k: dpk, v: indexVal }));
+          if (error) throw error;
         }
       }
       return dataplyDocument._id;
@@ -10731,23 +11020,30 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       for (let i = 0, len = pks.length; i < len; i++) {
         flattenedData[i].pk = pks[i];
       }
-      for (const [field, tree] of this.trees) {
+      for (const [indexName, config] of this.registeredIndices) {
+        const tree = this.trees.get(indexName);
+        if (!tree) continue;
         const treeTx = await tree.createTransaction();
-        const indexConfig = metadata.indices[field]?.[1];
         const batchInsertData = [];
-        for (let i = 0, len = flattenedData.length; i < len; i++) {
-          const item = flattenedData[i];
-          const v = item.data[field];
-          if (v === void 0) continue;
-          const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts" && typeof v === "string";
-          let tokens = [v];
-          if (isFts) {
-            tokens = tokenize(v, indexConfig);
+        if (config.type === "fts") {
+          const primaryField = this.getPrimaryField(config);
+          const ftsConfig = this.getFtsConfig(config);
+          for (let i = 0, len = flattenedData.length; i < len; i++) {
+            const item = flattenedData[i];
+            const v = item.data[primaryField];
+            if (v === void 0 || typeof v !== "string") continue;
+            const tokens = ftsConfig ? tokenize(v, ftsConfig) : [v];
+            for (let j = 0, tLen = tokens.length; j < tLen; j++) {
+              const token = tokens[j];
+              batchInsertData.push([this.getTokenKey(item.pk, token), { k: item.pk, v: token }]);
+            }
           }
-          for (let j = 0, len2 = tokens.length; j < len2; j++) {
-            const token = tokens[j];
-            const keyToInsert = isFts ? this.getTokenKey(item.pk, token) : item.pk;
-            batchInsertData.push([keyToInsert, { k: item.pk, v: token }]);
+        } else {
+          for (let i = 0, len = flattenedData.length; i < len; i++) {
+            const item = flattenedData[i];
+            const indexVal = this.getIndexValue(config, item.data);
+            if (indexVal === void 0) continue;
+            batchInsertData.push([item.pk, { k: item.pk, v: indexVal }]);
           }
         }
         const [error] = await catchPromise(treeTx.batchInsert(batchInsertData));
@@ -10773,8 +11069,8 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     const pks = await this.getKeys(query);
     let updatedCount = 0;
     const treeTxs = /* @__PURE__ */ new Map();
-    for (const [field, tree] of this.trees) {
-      treeTxs.set(field, await tree.createTransaction());
+    for (const [indexName, tree] of this.trees) {
+      treeTxs.set(indexName, await tree.createTransaction());
     }
     treeTxs.delete("_id");
     for (let i = 0, len = pks.length; i < len; i++) {
@@ -10784,42 +11080,45 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       const updatedDoc = computeUpdatedDoc(doc);
       const oldFlatDoc = this.flattenDocument(doc);
       const newFlatDoc = this.flattenDocument(updatedDoc);
-      const metadata = await this.getDocumentInnerMetadata(tx);
-      for (const [field, treeTx] of treeTxs) {
-        const oldV = oldFlatDoc[field];
-        const newV = newFlatDoc[field];
-        if (oldV === newV) continue;
-        const indexConfig = metadata.indices[field]?.[1];
-        const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts";
-        if (field in oldFlatDoc) {
-          let oldTokens = [oldV];
-          if (isFts && typeof oldV === "string") {
-            oldTokens = tokenize(oldV, indexConfig);
+      for (const [indexName, treeTx] of treeTxs) {
+        const config = this.registeredIndices.get(indexName);
+        if (!config) continue;
+        if (config.type === "fts") {
+          const primaryField = this.getPrimaryField(config);
+          const oldV = oldFlatDoc[primaryField];
+          const newV = newFlatDoc[primaryField];
+          if (oldV === newV) continue;
+          const ftsConfig = this.getFtsConfig(config);
+          if (typeof oldV === "string") {
+            const oldTokens = ftsConfig ? tokenize(oldV, ftsConfig) : [oldV];
+            for (let j = 0, jLen = oldTokens.length; j < jLen; j++) {
+              await treeTx.delete(this.getTokenKey(pk, oldTokens[j]), { k: pk, v: oldTokens[j] });
+            }
           }
-          for (let j = 0, len2 = oldTokens.length; j < len2; j++) {
-            const oldToken = oldTokens[j];
-            const keyToDelete = isFts ? this.getTokenKey(pk, oldToken) : pk;
-            await treeTx.delete(keyToDelete, { k: pk, v: oldToken });
+          if (typeof newV === "string") {
+            const newTokens = ftsConfig ? tokenize(newV, ftsConfig) : [newV];
+            const batchInsertData = [];
+            for (let j = 0, jLen = newTokens.length; j < jLen; j++) {
+              batchInsertData.push([this.getTokenKey(pk, newTokens[j]), { k: pk, v: newTokens[j] }]);
+            }
+            await treeTx.batchInsert(batchInsertData);
           }
-        }
-        if (field in newFlatDoc) {
-          let newTokens = [newV];
-          if (isFts && typeof newV === "string") {
-            newTokens = tokenize(newV, indexConfig);
+        } else {
+          const oldIndexVal = this.getIndexValue(config, oldFlatDoc);
+          const newIndexVal = this.getIndexValue(config, newFlatDoc);
+          if (JSON.stringify(oldIndexVal) === JSON.stringify(newIndexVal)) continue;
+          if (oldIndexVal !== void 0) {
+            await treeTx.delete(pk, { k: pk, v: oldIndexVal });
           }
-          const batchInsertData = [];
-          for (let j = 0, len2 = newTokens.length; j < len2; j++) {
-            const newToken = newTokens[j];
-            const keyToInsert = isFts ? this.getTokenKey(pk, newToken) : pk;
-            batchInsertData.push([keyToInsert, { k: pk, v: newToken }]);
+          if (newIndexVal !== void 0) {
+            await treeTx.batchInsert([[pk, { k: pk, v: newIndexVal }]]);
           }
-          await treeTx.batchInsert(batchInsertData);
         }
       }
       await this.update(pk, JSON.stringify(updatedDoc), tx);
       updatedCount++;
     }
-    for (const [field, treeTx] of treeTxs) {
+    for (const [indexName, treeTx] of treeTxs) {
       const result = await treeTx.commit();
       if (!result.success) {
         for (const rollbackTx of treeTxs.values()) {
@@ -10832,7 +11131,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   }
   /**
    * Fully update documents from the database that match the query
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @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
@@ -10847,7 +11146,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   }
   /**
    * Partially update documents from the database that match the query
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @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
@@ -10864,7 +11163,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   }
   /**
    * Delete documents from the database that match the query
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @param query The query to use
    * @param tx The transaction to use
    * @returns The number of deleted documents
    */
@@ -10877,20 +11176,22 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         const doc = await this.getDocument(pk, tx2);
         if (!doc) continue;
         const flatDoc = this.flattenDocument(doc);
-        const metadata = await this.getDocumentInnerMetadata(tx2);
-        for (const [field, tree] of this.trees) {
-          const v = flatDoc[field];
-          if (v === void 0) continue;
-          const indexConfig = metadata.indices[field]?.[1];
-          const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts" && typeof v === "string";
-          let tokens = [v];
-          if (isFts) {
-            tokens = tokenize(v, indexConfig);
-          }
-          for (let j = 0, len2 = tokens.length; j < len2; j++) {
-            const token = tokens[j];
-            const keyToDelete = isFts ? this.getTokenKey(pk, token) : pk;
-            await tree.delete(keyToDelete, { k: pk, v: token });
+        for (const [indexName, tree] of this.trees) {
+          const config = this.registeredIndices.get(indexName);
+          if (!config) continue;
+          if (config.type === "fts") {
+            const primaryField = this.getPrimaryField(config);
+            const v = flatDoc[primaryField];
+            if (v === void 0 || typeof v !== "string") continue;
+            const ftsConfig = this.getFtsConfig(config);
+            const tokens = ftsConfig ? tokenize(v, ftsConfig) : [v];
+            for (let j = 0, jLen = tokens.length; j < jLen; j++) {
+              await tree.delete(this.getTokenKey(pk, tokens[j]), { k: pk, v: tokens[j] });
+            }
+          } else {
+            const indexVal = this.getIndexValue(config, flatDoc);
+            if (indexVal === void 0) continue;
+            await tree.delete(pk, { k: pk, v: indexVal });
           }
         }
         await super.delete(pk, true, tx2);
@@ -10901,7 +11202,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   }
   /**
    * Count documents from the database that match the query
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @param query The query to use
    * @param tx The transaction to use
    * @returns The number of documents that match the query
    */
@@ -10927,6 +11228,51 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     }
     return true;
   }
+  /**
+   * 복합 인덱스의 non-primary 필드에 대해 문서가 유효한지 검증합니다.
+   */
+  verifyCompositeConditions(doc, conditions) {
+    if (conditions.length === 0) return true;
+    const flatDoc = this.flattenDocument(doc);
+    for (let i = 0, len = conditions.length; i < len; i++) {
+      const { field, condition } = conditions[i];
+      const docValue = flatDoc[field];
+      if (docValue === void 0) return false;
+      const treeValue = { k: doc._id, v: docValue };
+      if (!this.verifyValue(docValue, condition)) return false;
+    }
+    return true;
+  }
+  /**
+   * 단일 값에 대해 verbose 조건을 검증합니다.
+   */
+  verifyValue(value, condition) {
+    if (typeof condition !== "object" || condition === null) {
+      return value === condition;
+    }
+    if ("primaryEqual" in condition) {
+      return value === condition.primaryEqual?.v;
+    }
+    if ("primaryNotEqual" in condition) {
+      return value !== condition.primaryNotEqual?.v;
+    }
+    if ("primaryLt" in condition) {
+      return value !== null && condition.primaryLt?.v !== void 0 && value < condition.primaryLt.v;
+    }
+    if ("primaryLte" in condition) {
+      return value !== null && condition.primaryLte?.v !== void 0 && value <= condition.primaryLte.v;
+    }
+    if ("primaryGt" in condition) {
+      return value !== null && condition.primaryGt?.v !== void 0 && value > condition.primaryGt.v;
+    }
+    if ("primaryGte" in condition) {
+      return value !== null && condition.primaryGte?.v !== void 0 && value >= condition.primaryGte.v;
+    }
+    if ("primaryOr" in condition && Array.isArray(condition.primaryOr)) {
+      return condition.primaryOr.some((c) => value === c?.v);
+    }
+    return true;
+  }
   /**
    * 메모리 기반으로 청크 크기를 동적 조절합니다.
    */
@@ -10939,10 +11285,9 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   }
   /**
    * Prefetch 방식으로 키 배열을 청크 단위로 조회하여 문서를 순회합니다.
-   * FTS 검증 및 others 후보에 대한 tree.verify() 검증을 통과한 문서만 yield 합니다.
-   * 교집합 대신 스트리밍 중 검증하여 첫 결과 반환 시간을 단축합니다.
+   * FTS 검증, 복합 인덱스 검증, others 후보에 대한 tree.verify() 검증을 통과한 문서만 yield 합니다.
    */
-  async *processChunkedKeysWithVerify(keys, startIdx, initialChunkSize, ftsConditions, others, tx) {
+  async *processChunkedKeysWithVerify(keys, startIdx, initialChunkSize, ftsConditions, compositeVerifyConditions, others, tx) {
     const verifyOthers = others.filter((o) => !o.isFtsMatch);
     let i = startIdx;
     const totalKeys = keys.length;
@@ -10968,6 +11313,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         const doc = JSON.parse(s);
         chunkTotalSize += s.length * 2;
         if (ftsConditions.length > 0 && !this.verifyFts(doc, ftsConditions)) continue;
+        if (compositeVerifyConditions.length > 0 && this.verifyCompositeConditions(doc, compositeVerifyConditions) === false) continue;
         if (verifyOthers.length > 0) {
           const flatDoc = this.flattenDocument(doc);
           let passed = true;
@@ -10993,7 +11339,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   }
   /**
    * Select documents from the database
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @param query The query to use
    * @param options The options to use
    * @param tx The transaction to use
    * @returns The documents that match the query
@@ -11017,32 +11363,30 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     } = options;
     const self = this;
     const stream = this.streamWithDefault(async function* (tx2) {
-      const metadata = await self.getDocumentInnerMetadata(tx2);
       const ftsConditions = [];
       for (const field in query) {
         const q = query[field];
         if (q && typeof q === "object" && "match" in q && typeof q.match === "string") {
-          const indexConfig = metadata.indices[field]?.[1];
-          if (typeof indexConfig === "object" && indexConfig?.type === "fts") {
-            ftsConditions.push({ field, matchTokens: tokenize(q.match, indexConfig) });
+          const indexNames = self.fieldToIndices.get(field) || [];
+          for (const indexName of indexNames) {
+            const config = self.registeredIndices.get(indexName);
+            if (config && config.type === "fts") {
+              const ftsConfig = self.getFtsConfig(config);
+              if (ftsConfig) {
+                ftsConditions.push({ field, matchTokens: tokenize(q.match, ftsConfig) });
+              }
+              break;
+            }
           }
         }
       }
       const driverResult = await self.getDriverKeys(query, orderByField, sortOrder);
       if (!driverResult) return;
-      const { keys, others, rollback } = driverResult;
+      const { keys, others, compositeVerifyConditions, isDriverOrderByField, rollback } = driverResult;
       if (keys.length === 0) {
         rollback();
         return;
       }
-      const isQueryEmpty = Object.keys(query).length === 0;
-      const normalizedQuery = isQueryEmpty ? { _id: { gte: 0 } } : query;
-      const selectivity = await self.getSelectivityCandidate(
-        self.verboseQuery(normalizedQuery),
-        orderByField
-      );
-      const isDriverOrderByField = orderByField === void 0 || selectivity && selectivity.driver.field === orderByField;
-      if (selectivity) selectivity.rollback();
       try {
         if (!isDriverOrderByField && orderByField) {
           const topK = limit === Infinity ? Infinity : offset + limit;
@@ -11061,6 +11405,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
             0,
             self.options.pageSize,
             ftsConditions,
+            compositeVerifyConditions,
             others,
             tx2
           )) {
@@ -11098,6 +11443,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
             offset,
             self.options.pageSize,
             ftsConditions,
+            compositeVerifyConditions,
             others,
             tx2
           )) {
@@ -11131,8 +11477,7 @@ var DocumentDataply = class _DocumentDataply {
   static Define() {
     return {
       /**
-       * Sets the options for the database, such as index configurations and WAL settings.
-       * @template IC The configuration of indices.
+       * Sets the options for the database, such as WAL settings.
        * @param options The database initialization options.
        */
       Options: (options) => _DocumentDataply.Options(options)
@@ -11160,6 +11505,30 @@ var DocumentDataply = class _DocumentDataply {
   constructor(file, options) {
     this.api = new DocumentDataplyAPI(file, options ?? {});
   }
+  /**
+   * Create a named index on the database.
+   * Can be called before or after init().
+   * If called after init(), the index is immediately created and backfilled.
+   * @param name The name of the index
+   * @param option The index configuration (btree or fts)
+   * @param tx Optional transaction
+   * @returns Promise<this> for chaining
+   */
+  async createIndex(name, option, tx) {
+    await this.api.registerIndex(name, option, tx);
+    return this;
+  }
+  /**
+   * Drop (remove) a named index from the database.
+   * The '_id' index cannot be dropped.
+   * @param name The name of the index to drop
+   * @param tx Optional transaction
+   * @returns Promise<this> for chaining
+   */
+  async dropIndex(name, tx) {
+    await this.api.dropIndex(name, tx);
+    return this;
+  }
   /**
    * Initialize the document database
    */
@@ -11167,6 +11536,17 @@ var DocumentDataply = class _DocumentDataply {
     await this.api.init();
     await this.api.backfillIndices();
   }
+  /**
+   * 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.
+   * After the callback completes, schemeVersion is updated to the target version.
+   * @param version The target scheme version
+   * @param callback The migration callback receiving a transaction
+   * @param tx Optional transaction
+   */
+  async migration(version, callback, tx) {
+    await this.api.migration(version, callback, tx);
+  }
   /**
    * Get the metadata of the document database
    */
@@ -11199,7 +11579,7 @@ var DocumentDataply = class _DocumentDataply {
   }
   /**
    * Fully update documents from the database that match the query
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @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
@@ -11209,7 +11589,7 @@ var DocumentDataply = class _DocumentDataply {
   }
   /**
    * Partially update documents from the database that match the query
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @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
@@ -11219,7 +11599,7 @@ var DocumentDataply = class _DocumentDataply {
   }
   /**
    * Delete documents from the database that match the query
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @param query The query to use
    * @param tx The transaction to use
    * @returns The number of deleted documents
    */
@@ -11228,7 +11608,7 @@ var DocumentDataply = class _DocumentDataply {
   }
   /**
    * Count documents from the database that match the query
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @param query The query to use
    * @param tx The transaction to use
    * @returns The number of documents that match the query
    */
@@ -11237,7 +11617,7 @@ var DocumentDataply = class _DocumentDataply {
   }
   /**
    * Select documents from the database
-   * @param query The query to use (only indexed fields + _id allowed)
+   * @param query The query to use
    * @param options The options to use
    * @param tx The transaction to use
    * @returns The documents that match the query