spice-couchbase 2.0.60 → 2.0.61

package/build/index.auto-optimize.test.js

@@ -0,0 +1,376 @@
+"use strict";
+
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) { try { var info = gen[key](arg); var value = info.value; } catch (error) { reject(error); return; } if (info.done) { resolve(value); } else { Promise.resolve(value).then(_next, _throw); } }
+
+function _asyncToGenerator(fn) { return function () { var self = this, args = arguments; return new Promise(function (resolve, reject) { var gen = fn.apply(self, args); function _next(value) { asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value); } function _throw(err) { asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err); } _next(undefined); }); }; }
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { _defineProperty(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
+
+function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+
+var assert = require("node:assert/strict");
+
+var fs = require("node:fs");
+
+var path = require("node:path");
+
+var vm = require("node:vm");
+
+var {
+  test
+} = require("node:test");
+
+var {
+  buildCoveringIndex,
+  buildCoveringIndexDefinition
+} = require("./utility");
+
+var keyspace = {
+  bucket: "saturn",
+  scope: "test",
+  collection: "users"
+};
+var lookupQuery = "SELECT name, email FROM users WHERE status = 'active'";
+
+function existingIndex(index_key) {
+  var overrides = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  return _objectSpread({
+    name: "legacy_covering_index",
+    using: "gsi",
+    state: "online",
+    index_key
+  }, overrides);
+}
+
+function executionScope() {
+  var indexes = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
+  var {
+    inventoryError,
+    inventoryResponse,
+    plan
+  } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var calls = [];
+  return {
+    calls,
+
+    query(statement, options) {
+      return _asyncToGenerator(function* () {
+        calls.push({
+          statement,
+          options
+        });
+
+        if (statement.startsWith("EXPLAIN ")) {
+          return {
+            rows: [plan || {
+              "#operator": "Fetch"
+            }]
+          };
+        }
+
+        if (statement.includes("FROM system:indexes")) {
+          if (inventoryError) throw inventoryError;
+          return inventoryResponse === undefined ? {
+            rows: indexes
+          } : inventoryResponse;
+        }
+
+        return {
+          rows: []
+        };
+      })();
+    }
+
+  };
+}
+
+function createStatements(scope) {
+  return scope.calls.filter((_ref) => {
+    var {
+      statement
+    } = _ref;
+    return statement.startsWith("CREATE INDEX ");
+  });
+} // Isolate optimizer state and time without connecting to Couchbase or sleeping.
+
+
+function createDatabase(durationMs) {
+  var env = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var tick = BigInt(0);
+  var module = {
+    exports: {}
+  };
+  vm.runInNewContext(fs.readFileSync(path.join(__dirname, "index.js"), "utf8"), {
+    require,
+    module,
+    console,
+    process: {
+      env,
+      hrtime: {
+        bigint: () => {
+          var current = tick;
+          tick += BigInt(durationMs) * BigInt(1000000);
+          return current;
+        }
+      }
+    }
+  });
+  var db = Object.create(module.exports.prototype);
+  db.bucket = "saturn";
+  db.scope_name = "test";
+  db.collection_name = "users";
+  db.cluster = {
+    query: function () {
+      var _query = _asyncToGenerator(function* () {
+        return {
+          rows: []
+        };
+      });
+
+      function query() {
+        return _query.apply(this, arguments);
+      }
+
+      return query;
+    }()
+  };
+  return db;
+}
+
+test("auto-optimization only starts above the default 3-second threshold",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  for (var duration of [1001, 2999, 3000, 3001]) {
+    var db = createDatabase(duration);
+    var optimizations = 0;
+    db.optimize =
+    /*#__PURE__*/
+    _asyncToGenerator(function* () {
+      optimizations += 1;
+    });
+    yield db.query("SELECT name FROM users WHERE status = 'active'");
+    assert.equal(optimizations, duration > 3000 ? 1 : 0, "".concat(duration, "ms"));
+  }
+}));
+test("the explicit slow-query threshold override remains supported",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createDatabase(5001, {
+    SPICE_COUCHBASE_SLOW_QUERY_MS: "5000"
+  });
+  var optimizations = 0;
+  db.optimize =
+  /*#__PURE__*/
+  _asyncToGenerator(function* () {
+    optimizations += 1;
+  });
+  yield db.query("SELECT name FROM users WHERE status = 'active'");
+  assert.equal(optimizations, 1);
+}));
+test("Fetch plans for full-document projections never create indexes",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var _loop = function* _loop(projection) {
+    var db = createDatabase(0);
+    var statements = [];
+    var query = "SELECT ".concat(projection, " FROM users WHERE status = 'active' ORDER BY created_at DESC");
+    yield db.optimize(query, {
+      query: function () {
+        var _query2 = _asyncToGenerator(function* (statement) {
+          statements.push(statement);
+          return {
+            rows: [{
+              "#operator": "Fetch"
+            }]
+          };
+        });
+
+        function query(_x) {
+          return _query2.apply(this, arguments);
+        }
+
+        return query;
+      }()
+    });
+    assert.deepEqual(statements, ["EXPLAIN ".concat(query)]);
+  };
+
+  for (var projection of ["*", "users.*", "`users`.*", "(`users`).*, META(`users`).id AS id"]) {
+    yield* _loop(projection);
+  }
+}));
+test("Fetch plans for explicit fields still create a covering index",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createDatabase(0);
+  var scope = executionScope();
+  yield db.optimize("SELECT name FROM users WHERE status = 'active'", scope);
+  assert.equal(scope.calls.length, 3);
+  assert.match(scope.calls[1].statement, /FROM system:indexes/);
+  assert.equal(JSON.stringify(scope.calls[1].options.parameters), JSON.stringify(keyspace));
+  assert.match(scope.calls[2].statement, /^CREATE INDEX `adv_covered_/);
+  assert.match(scope.calls[2].statement, /`status`, `name`/);
+}));
+test("reordered selected columns and changed literals generate identical DDL", () => {
+  var original = buildCoveringIndex(lookupQuery, keyspace);
+  var reordered = buildCoveringIndex("SELECT email, name FROM users WHERE status = 'pending'", keyspace);
+  assert.equal(original, reordered);
+});
+test("adding explicit ascending order cannot rename an identical definition", () => {
+  var base = "SELECT status, created_at FROM users WHERE status = 'pending'";
+  assert.equal(buildCoveringIndex(base, keyspace), buildCoveringIndex("".concat(base, " ORDER BY created_at ASC"), keyspace));
+});
+test("genuinely different access-key order and direction keep distinct definitions", () => {
+  var base = "SELECT name, email FROM users WHERE status = 'active'";
+  var asc = buildCoveringIndex("".concat(base, " ORDER BY name, email"), keyspace);
+  var desc = buildCoveringIndex("".concat(base, " ORDER BY name DESC, email"), keyspace);
+  var reordered = buildCoveringIndex("".concat(base, " ORDER BY email, name"), keyspace);
+  assert.notEqual(asc, desc);
+  assert.notEqual(asc, reordered);
+  assert.notEqual(asc.match(/adv_covered_\w+/)[0], reordered.match(/adv_covered_\w+/)[0]);
+});
+test("case-distinct document fields are not collapsed", () => {
+  var statement = buildCoveringIndex("SELECT Name, name, Status, status FROM users ORDER BY Name DESC", keyspace);
+  assert.match(statement, /`Name` DESC/);
+  assert.match(statement, /`name`/);
+  assert.match(statement, /`Status`/);
+  assert.match(statement, /`status`/);
+  assert.doesNotMatch(statement, /`name` DESC/);
+});
+
+var _loop2 = function _loop2(state) {
+  test("an existing ".concat(state, " index with reordered projection keys prevents creation"),
+  /*#__PURE__*/
+  _asyncToGenerator(function* () {
+    var scope = executionScope([existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`"], {
+      state
+    })]);
+    yield createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(scope.calls.length, 2);
+    assert.equal(createStatements(scope).length, 0);
+  }));
+};
+
+for (var state of ["online", "deferred", "pending", "building", "offline"]) {
+  _loop2(state);
+}
+
+test("a wider existing index covers a projection subset without another index",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var scope = executionScope([existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`phone`", "`email` DESC"])]);
+  yield createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(createStatements(scope).length, 0);
+}));
+test("catalog key formatting, explicit ASC and attribute order are normalized",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  for (var leadingKey of ["((`deleted`)) ASC INCLUDE MISSING", "deleted INCLUDE MISSING ASC"]) {
+    var scope = executionScope([existingIndex([leadingKey, "(status) ASC", "`name`", "email ASC"])]);
+    yield createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 0, leadingKey);
+  }
+}));
+var incompatibleIndexes = [["missing a projection field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`"])], ["different access prefix", existingIndex(["`deleted` INCLUDE MISSING", "`name`", "`status`", "`email`"])], ["missing-leading-key exclusion", existingIndex(["`deleted`", "`status`", "`name`", "`email`"])], ["case-distinct field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`Name`", "`email`"])], ["expression instead of the field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "LOWER(`name`)", "`email`"])], ["array key", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`", "DISTINCT ARRAY v FOR v IN tags END"])], ["partial index", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`"], {
+  condition: "(`status` = 'pending')"
+})], ["primary index", existingIndex([], {
+  is_primary: true
+})]];
+
+var _loop3 = function _loop3(reason, index) {
+  test("does not mistake ".concat(reason, " for a compatible covering index"),
+  /*#__PURE__*/
+  _asyncToGenerator(function* () {
+    var scope = executionScope([index]);
+    yield createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 1);
+  }));
+};
+
+for (var [reason, index] of incompatibleIndexes) {
+  _loop3(reason, index);
+}
+
+test("existing opposite sort direction does not satisfy the requested sort",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var query = "".concat(lookupQuery, " ORDER BY created_at DESC");
+  var scope = executionScope([existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`created_at`", "`name`", "`email`"])]);
+  yield createDatabase(0).optimize(query, scope);
+  assert.equal(createStatements(scope).length, 1);
+  assert.match(createStatements(scope)[0].statement, /`created_at` DESC/);
+}));
+test("same generated name is never recreated even if its keys are unavailable",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var candidate = buildCoveringIndexDefinition(lookupQuery, keyspace);
+  var scope = executionScope([{
+    name: candidate.name,
+    state: "building"
+  }]);
+  yield createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(createStatements(scope).length, 0);
+}));
+test("catalog failure or incomplete results prevent creation and trigger cooldown",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var _loop4 = function* _loop4(options) {
+    var db = createDatabase(3001);
+    var scope = executionScope([], options);
+    yield db.optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 0);
+    var retries = 0;
+    db.optimize =
+    /*#__PURE__*/
+    _asyncToGenerator(function* () {
+      retries++;
+    });
+    yield db.query("SELECT email FROM users WHERE status = 'pending'");
+    assert.equal(retries, 0);
+  };
+
+  for (var options of [{
+    inventoryError: new Error("query service unavailable")
+  }, {
+    inventoryResponse: {}
+  }, {
+    inventoryResponse: {
+      rows: [],
+      meta: {
+        warnings: [{
+          message: "partial inventory"
+        }]
+      }
+    }
+  }]) {
+    yield* _loop4(options);
+  }
+}));
+test("already-covered plans need neither an inventory lookup nor creation",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var scope = executionScope([], {
+    plan: {
+      "#operator": "IndexScan3"
+    }
+  });
+  yield createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(scope.calls.length, 1);
+}));
+test("a default collection uses default names in its inventory lookup",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createDatabase(0);
+  db.scope_name = undefined;
+  db.collection_name = undefined;
+  var scope = executionScope();
+  yield db.optimize("SELECT name FROM saturn WHERE status = 'active'", scope);
+  assert.equal(JSON.stringify(scope.calls[1].options.parameters), JSON.stringify({
+    bucket: "saturn",
+    scope: "_default",
+    collection: "_default"
+  }));
+  assert.match(createStatements(scope)[0].statement, /`saturn`\.`_default`\.`_default`/);
+}));

package/build/index.js

@@ -35,13 +35,13 @@ if (!Promise.allSettled) {
 } // Couchbase lookupIn has a limit of 16 operations per call
 
 
-var LOOKUP_IN_MAX_SPECS = 16; // Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN plus
-// a possible CREATE INDEX) for any statement slower than SLOW_QUERY_MS. When
+var LOOKUP_IN_MAX_SPECS = 16; // Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN,
+// index inventory check, and possible CREATE INDEX) above SLOW_QUERY_MS. When
 // the cluster is degraded every statement is slow, so without limits each
 // query spawned two more heavy ones and deepened the outage. These caps make it
 // a bounded, once-per-statement background task that backs off on failure.
 
-var SLOW_QUERY_MS = Number(process.env.SPICE_COUCHBASE_SLOW_QUERY_MS || 1000);
+var SLOW_QUERY_MS = Number(process.env.SPICE_COUCHBASE_SLOW_QUERY_MS || 3000);
 var AUTO_OPTIMIZE_ENABLED = !["0", "false", "no", "off"].includes(String((_process$env$SPICE_CO = process.env.SPICE_COUCHBASE_AUTO_OPTIMIZE) !== null && _process$env$SPICE_CO !== void 0 ? _process$env$SPICE_CO : "true").trim().toLowerCase());
 var OPTIMIZE_MAX_INFLIGHT = Number(process.env.SPICE_COUCHBASE_OPTIMIZE_MAX_INFLIGHT || 1);
 var OPTIMIZE_FAILURE_COOLDOWN_MS = Number(process.env.SPICE_COUCHBASE_OPTIMIZE_COOLDOWN_MS || 5 * 60 * 1000); // Statements already optimised in this process. Bounded so it cannot grow
@@ -904,10 +904,11 @@ module.exports = class Database {
       optimizeState.inFlight += 1;
 
       try {
-        var _explainResponse$rows;
+        var _explainResponse$rows, _indexResponse$meta, _indexResponse$meta$w;
 
         var {
-          buildCoveringIndex
+          buildCoveringIndexDefinition,
+          indexSatisfiesCoveringDefinition
         } = require("./utility"); // 1. Run EXPLAIN to get the query plan
 
 
@@ -922,15 +923,34 @@ module.exports = class Database {
         } // 3. Build covering index from the query
 
 
-        var indexStatement = buildCoveringIndex(query, {
+        var candidate = buildCoveringIndexDefinition(query, {
           bucket: _this19.bucket,
           scope: _this19.scope_name,
           collection: _this19.collection_name
-        }); // 4. Execute the index creation if we got a valid statement
+        });
+        if (!candidate) return; // EXPLAIN only describes the chosen plan. An equivalent or wider index
+        // may already exist under an older name, or still be deferred/building.
+        // Include both catalog representations of the default collection.
+
+        var indexResponse = yield exec_scope.query("SELECT RAW i FROM system:indexes AS i\n         WHERE i.namespace_id = 'default'\n           AND ((i.bucket_id = $bucket AND i.scope_id = $scope AND i.keyspace_id = $collection)\n             OR ($scope = '_default' AND $collection = '_default'\n               AND i.bucket_id IS MISSING AND i.scope_id IS MISSING AND i.keyspace_id = $bucket))", {
+          parameters: {
+            bucket: candidate.bucket,
+            scope: candidate.scope,
+            collection: candidate.collection
+          }
+        }); // A failed or incomplete inventory is not evidence that no index exists.
 
-        if (indexStatement) {
-          yield exec_scope.query(indexStatement);
+        if (!Array.isArray(indexResponse === null || indexResponse === void 0 ? void 0 : indexResponse.rows) || (indexResponse === null || indexResponse === void 0 ? void 0 : (_indexResponse$meta = indexResponse.meta) === null || _indexResponse$meta === void 0 ? void 0 : (_indexResponse$meta$w = _indexResponse$meta.warnings) === null || _indexResponse$meta$w === void 0 ? void 0 : _indexResponse$meta$w.length)) {
+          throw new Error("Cannot verify existing indexes before auto-optimization");
         }
+
+        if (indexResponse.rows.some(index => index.name === candidate.name || indexSatisfiesCoveringDefinition(index, candidate))) {
+          return;
+        } // Identical definitions use the same name across processes. Couchbase's
+        // per-keyspace name uniqueness also prevents a concurrent duplicate.
+
+
+        yield exec_scope.query(candidate.statement);
       } catch (e) {
         // A failure here (timeout, index already exists, cluster busy) almost
         // always means the cluster is struggling. Stop adding EXPLAIN and

package/build/utility.js

@@ -235,7 +235,7 @@ function buildOrderDirectionMap(orderByIndexFields) {
     direction
   } of orderByIndexFields) {
     if (direction === "DESC") {
-      directionMap.set(name.toLowerCase(), direction);
+      directionMap.set(name, direction);
     }
   }
 
@@ -243,14 +243,9 @@ function buildOrderDirectionMap(orderByIndexFields) {
 }
 
 function formatIndexField(field, orderDirectionMap) {
-  var direction = orderDirectionMap.get(field.toLowerCase());
+  var direction = orderDirectionMap.get(field);
   return "`".concat(field, "`").concat(direction ? " ".concat(direction) : "");
 }
-
-function formatIndexKey(field, orderDirectionMap) {
-  var direction = orderDirectionMap.get(field.toLowerCase());
-  return "".concat(field).concat(direction ? " ".concat(direction) : "");
-}
 /**
  * Splits SELECT clause by commas, respecting parentheses
  * @param {string} clause - The SELECT clause content
@@ -284,21 +279,8 @@ function splitSelectClause(clause) {
 
   return parts;
 }
-
-function hasQualifiedWildcardProjection(query) {
-  var selectMatch = query.match(/\bSELECT\b([\s\S]+?)\bFROM\b/i);
-
-  if (!selectMatch) {
-    return false;
-  }
-
-  return splitSelectClause(selectMatch[1].trim()).some(part => {
-    var trimmedPart = part.trim();
-    return /^\(\s*`?\w+`?\s*\)\s*\.\s*\*$/.test(trimmedPart) || /^`?\w+`?\s*\.\s*\*$/.test(trimmedPart);
-  });
-}
 /**
- * Builds a covering or fallback non-covering index CREATE statement from a query
+ * Builds a covering index CREATE statement from a query
  * @param {string} query - The N1QL query to analyze
  * @param {Object} options - Configuration options
  * @param {string} options.bucket - The bucket name
@@ -309,6 +291,14 @@ function hasQualifiedWildcardProjection(query) {
 
 
 function buildCoveringIndex(query, options) {
+  var _ref, _buildCoveringIndexDe;
+
+  return (_ref = (_buildCoveringIndexDe = buildCoveringIndexDefinition(query, options)) === null || _buildCoveringIndexDe === void 0 ? void 0 : _buildCoveringIndexDe.statement) !== null && _ref !== void 0 ? _ref : null;
+} // Keep the access keys separate from projection-only keys so an older, wider
+// index can satisfy the same request without depending on its generated name.
+
+
+function buildCoveringIndexDefinition(query, options) {
   var {
     bucket,
     scope = "_default",
@@ -321,9 +311,10 @@ function buildCoveringIndex(query, options) {
 
 
   var selectFields = extractSelectFields(query);
-  var isNonCoveringFallback = selectFields === null && hasQualifiedWildcardProjection(query);
 
-  if (selectFields === null && !isNonCoveringFallback) {
+  if (selectFields === null) {
+    // Full-document projections cannot be covered by the extracted fields.
+    // Skip them instead of creating a non-covering fallback index.
     return null;
   } // Extract fields from WHERE clause
 
@@ -336,42 +327,36 @@ function buildCoveringIndex(query, options) {
   var orderDirectionMap = buildOrderDirectionMap(orderByIndexFields);
   var orderByFields = orderByIndexFields.map(field => field.name); // Remove 'deleted' from whereFields as it will be added first with INCLUDE MISSING
 
-  var filteredWhereFields = whereFields.filter(f => f.toLowerCase() !== "deleted"); // Track fields already added to avoid duplicates
+  var filteredWhereFields = whereFields.filter(f => f !== "deleted"); // Track fields already added to avoid duplicates
 
-  var addedFields = new Set(filteredWhereFields.map(f => f.toLowerCase())); // Filter GROUP BY fields (remove duplicates from WHERE, remove deleted)
+  var addedFields = new Set(filteredWhereFields); // Filter GROUP BY fields (remove duplicates from WHERE, remove deleted)
 
   var filteredGroupByFields = groupByFields.filter(f => {
-    var lower = f.toLowerCase();
-
-    if (addedFields.has(lower) || lower === "deleted") {
+    if (addedFields.has(f) || f === "deleted") {
       return false;
     }
 
-    addedFields.add(lower);
+    addedFields.add(f);
     return true;
   }); // Filter ORDER BY fields (remove duplicates from WHERE and GROUP BY, remove deleted)
 
   var filteredOrderByFields = orderByFields.filter(f => {
-    var lower = f.toLowerCase();
-
-    if (addedFields.has(lower) || lower === "deleted") {
+    if (addedFields.has(f) || f === "deleted") {
       return false;
     }
 
-    addedFields.add(lower);
+    addedFields.add(f);
     return true;
   }); // Filter SELECT fields (remove duplicates from WHERE, GROUP BY, and ORDER BY, remove deleted)
 
-  var selectFieldsFiltered = (selectFields || []).filter(f => {
-    var lower = f.toLowerCase();
-
-    if (addedFields.has(lower) || lower === "deleted") {
+  var selectFieldsFiltered = selectFields.filter(f => {
+    if (addedFields.has(f) || f === "deleted") {
       return false;
     }
 
-    addedFields.add(lower);
+    addedFields.add(f);
     return true;
-  }); // All fields for the index: WHERE -> GROUP BY -> ORDER BY -> SELECT
+  }).sort(); // Projection order has no effect on coverage. Keep access-key order intact.
 
   var allFields = [...filteredWhereFields, ...filteredGroupByFields, ...filteredOrderByFields, ...selectFieldsFiltered];
 
@@ -381,22 +366,80 @@ function buildCoveringIndex(query, options) {
   } // Build the field list with deleted INCLUDE MISSING first
 
 
-  var fieldList = ["`deleted` INCLUDE MISSING", ...allFields.map(f => formatIndexField(f, orderDirectionMap))].join(", "); // Generate unique index name based on bucket, scope, collection, and fields
-  // This ensures multiple queries covered by the same index get the same hash
+  var keys = ["`deleted` INCLUDE MISSING", ...allFields.map(f => formatIndexField(f, orderDirectionMap))]; // Hash the actual ordered definition, not query syntax. In particular, an
+  // explicit ORDER BY ... ASC must not rename an otherwise identical index.
 
-  var indexFieldsKey = allFields.map(field => formatIndexKey(field, orderDirectionMap)).sort().join(",");
-  var orderFieldsKey = orderByIndexFields.map(field => formatIndexKey(field.name, orderDirectionMap)).join(",");
-  var indexMode = isNonCoveringFallback ? "noncovered" : "covered";
-  var indexKey = "".concat(bucket, "|").concat(scope, "|").concat(collection, "|mode:").concat(indexMode, "|fields:").concat(indexFieldsKey, "|order:").concat(orderFieldsKey);
+  var indexKey = JSON.stringify([bucket, scope, collection, keys]);
   var hash = generateHash(indexKey);
-  var indexName = "adv_".concat(indexMode, "_").concat(hash); // Build the CREATE INDEX statement
+  var indexName = "adv_covered_".concat(hash); // Build the CREATE INDEX statement
+
+  var quote = identifier => "`".concat(identifier.replace(/`/g, "``"), "`");
+
+  var indexStatement = "CREATE INDEX `".concat(indexName, "` ON `default`:").concat(quote(bucket), ".").concat(quote(scope), ".").concat(quote(collection), "(").concat(keys.join(", "), ")");
+  return {
+    name: indexName,
+    statement: indexStatement,
+    keys,
+    accessKeyCount: 1 + filteredWhereFields.length + filteredGroupByFields.length + filteredOrderByFields.length,
+    bucket,
+    scope,
+    collection
+  };
+} // Only compare simple scalar keys. Do not treat expressions, array indexes,
+// partial indexes, or case-distinct document fields as equivalent.
+
+
+function normalizeIndexKey(key) {
+  if (typeof key !== "string") return null;
+  var match = key.trim().match(/^(\(*[\t-\r \xA0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]*(?:`(?:[\0-_a-\uFFFF]|``)+`|[A-Z_a-z][0-9A-Z_a-z]*)[\t-\r \xA0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]*\)*)([\s\S]*?)$/);
+  if (!match) return null;
+  var expression = match[1].trim();
+
+  while (expression.startsWith("(") && expression.endsWith(")")) {
+    expression = expression.slice(1, -1).trim();
+  }
+
+  var identifier = expression.match(/^(?:`((?:[^`]|``)+)`|([A-Za-z_]\w*))$/);
+  if (!identifier) return null;
+  var attributes = match[2].trim().toUpperCase();
+
+  if (!/^(?:(?:ASC|DESC)(?:\s+INCLUDE\s+MISSING)?|INCLUDE\s+MISSING(?:\s+(?:ASC|DESC))?)?$/.test(attributes)) {
+    return null;
+  }
+
+  return {
+    field: identifier[1] !== undefined ? identifier[1].replace(/``/g, "`") : identifier[2],
+    direction: /\bDESC\b/.test(attributes) ? "DESC" : "ASC",
+    includeMissing: /\bINCLUDE\s+MISSING\b/.test(attributes)
+  };
+} // Call with indexes from the candidate's exact bucket/scope/collection. State
+// is deliberately not filtered: a matching deferred/building index is already
+// committed work, even though EXPLAIN cannot use it yet.
+
+
+function indexSatisfiesCoveringDefinition(index, candidate) {
+  if (index.is_primary || index.condition || index.using !== "gsi" || !Array.isArray(index.index_key)) {
+    return false;
+  }
+
+  var existingKeys = index.index_key.map(normalizeIndexKey);
+  var requiredKeys = candidate.keys.map(normalizeIndexKey);
+  if (existingKeys.some(key => !key) || requiredKeys.some(key => !key)) return false;
+
+  for (var i = 0; i < candidate.accessKeyCount; i++) {
+    var existing = existingKeys[i];
+    var required = requiredKeys[i];
+    if (!existing || existing.field !== required.field || existing.direction !== required.direction || existing.includeMissing !== required.includeMissing) return false;
+  }
 
-  var indexStatement = "CREATE INDEX `".concat(indexName, "` ON `default`:`").concat(bucket, "`.`").concat(scope, "`.`").concat(collection, "`(").concat(fieldList, ")");
-  return indexStatement;
+  var existingFields = new Set(existingKeys.map(key => key.field));
+  return requiredKeys.slice(candidate.accessKeyCount).every(key => existingFields.has(key.field));
 }
 
 module.exports = {
   buildCoveringIndex,
+  buildCoveringIndexDefinition,
+  indexSatisfiesCoveringDefinition,
   extractWhereFields,
   extractSelectFields,
   extractGroupByFields,

package/build/utility.test.js

@@ -504,21 +504,21 @@ test("returns null when missing bucket option", () => {
   });
   assert.strictEqual(result, null);
 });
-test("returns null when missing scope option", () => {
+test("uses the default scope when scope option is missing", () => {
   var query = "SELECT name FROM users WHERE status = 'active'";
   var result = buildCoveringIndex(query, {
     bucket: "test",
     collection: "users"
   });
-  assert.strictEqual(result, null);
+  assert.ok(result.includes("`test`.`_default`.`users`"));
 });
-test("returns null when missing collection option", () => {
+test("uses the default collection when collection option is missing", () => {
   var query = "SELECT name FROM users WHERE status = 'active'";
   var result = buildCoveringIndex(query, {
     bucket: "test",
     scope: "scope"
   });
-  assert.strictEqual(result, null);
+  assert.ok(result.includes("`test`.`scope`.`_default`"));
 });
 test("generates unique index name from query hash", () => {
   var query1 = "SELECT name FROM users WHERE status = 'active'";

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "spice-couchbase",
-  "version": "2.0.60",
+  "version": "2.0.61",
   "description": "",
   "main": "build/index.js",
   "scripts": {
     "test": "node src/utility.test.js",
+    "test:auto-optimize": "node --test src/index.auto-optimize.test.js",
     "test:query-consistency": "node src/index.query-consistency.test.js",
     "test:count-query": "node src/index.count-query.test.js"
   },

package/src/index.auto-optimize.test.js

@@ -0,0 +1,237 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const vm = require("node:vm");
+const { test } = require("node:test");
+const { buildCoveringIndex, buildCoveringIndexDefinition } = require("./utility");
+
+const keyspace = { bucket: "saturn", scope: "test", collection: "users" };
+const lookupQuery = "SELECT name, email FROM users WHERE status = 'active'";
+
+function existingIndex(index_key, overrides = {}) {
+  return { name: "legacy_covering_index", using: "gsi", state: "online", index_key, ...overrides };
+}
+
+function executionScope(indexes = [], { inventoryError, inventoryResponse, plan } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(statement, options) {
+      calls.push({ statement, options });
+      if (statement.startsWith("EXPLAIN ")) {
+        return { rows: [plan || { "#operator": "Fetch" }] };
+      }
+      if (statement.includes("FROM system:indexes")) {
+        if (inventoryError) throw inventoryError;
+        return inventoryResponse === undefined ? { rows: indexes } : inventoryResponse;
+      }
+      return { rows: [] };
+    },
+  };
+}
+
+function createStatements(scope) {
+  return scope.calls.filter(({ statement }) => statement.startsWith("CREATE INDEX "));
+}
+
+// Isolate optimizer state and time without connecting to Couchbase or sleeping.
+function createDatabase(durationMs, env = {}) {
+  let tick = BigInt(0);
+  const module = { exports: {} };
+  vm.runInNewContext(fs.readFileSync(path.join(__dirname, "index.js"), "utf8"), {
+    require,
+    module,
+    console,
+    process: {
+      env,
+      hrtime: {
+        bigint: () => {
+          const current = tick;
+          tick += BigInt(durationMs) * BigInt(1000000);
+          return current;
+        },
+      },
+    },
+  });
+  const db = Object.create(module.exports.prototype);
+  db.bucket = "saturn";
+  db.scope_name = "test";
+  db.collection_name = "users";
+  db.cluster = { query: async () => ({ rows: [] }) };
+  return db;
+}
+
+test("auto-optimization only starts above the default 3-second threshold", async () => {
+  for (const duration of [1001, 2999, 3000, 3001]) {
+    const db = createDatabase(duration);
+    let optimizations = 0;
+    db.optimize = async () => { optimizations += 1; };
+    await db.query("SELECT name FROM users WHERE status = 'active'");
+    assert.equal(optimizations, duration > 3000 ? 1 : 0, `${duration}ms`);
+  }
+});
+
+test("the explicit slow-query threshold override remains supported", async () => {
+  const db = createDatabase(5001, { SPICE_COUCHBASE_SLOW_QUERY_MS: "5000" });
+  let optimizations = 0;
+  db.optimize = async () => { optimizations += 1; };
+  await db.query("SELECT name FROM users WHERE status = 'active'");
+  assert.equal(optimizations, 1);
+});
+
+test("Fetch plans for full-document projections never create indexes", async () => {
+  for (const projection of ["*", "users.*", "`users`.*", "(`users`).*, META(`users`).id AS id"]) {
+    const db = createDatabase(0);
+    const statements = [];
+    const query = `SELECT ${projection} FROM users WHERE status = 'active' ORDER BY created_at DESC`;
+    await db.optimize(query, {
+      query: async (statement) => {
+        statements.push(statement);
+        return { rows: [{ "#operator": "Fetch" }] };
+      },
+    });
+    assert.deepEqual(statements, [`EXPLAIN ${query}`]);
+  }
+});
+
+test("Fetch plans for explicit fields still create a covering index", async () => {
+  const db = createDatabase(0);
+  const scope = executionScope();
+  await db.optimize("SELECT name FROM users WHERE status = 'active'", scope);
+  assert.equal(scope.calls.length, 3);
+  assert.match(scope.calls[1].statement, /FROM system:indexes/);
+  assert.equal(JSON.stringify(scope.calls[1].options.parameters), JSON.stringify(keyspace));
+  assert.match(scope.calls[2].statement, /^CREATE INDEX `adv_covered_/);
+  assert.match(scope.calls[2].statement, /`status`, `name`/);
+});
+
+test("reordered selected columns and changed literals generate identical DDL", () => {
+  const original = buildCoveringIndex(lookupQuery, keyspace);
+  const reordered = buildCoveringIndex("SELECT email, name FROM users WHERE status = 'pending'", keyspace);
+  assert.equal(original, reordered);
+});
+
+test("adding explicit ascending order cannot rename an identical definition", () => {
+  const base = "SELECT status, created_at FROM users WHERE status = 'pending'";
+  assert.equal(buildCoveringIndex(base, keyspace), buildCoveringIndex(`${base} ORDER BY created_at ASC`, keyspace));
+});
+
+test("genuinely different access-key order and direction keep distinct definitions", () => {
+  const base = "SELECT name, email FROM users WHERE status = 'active'";
+  const asc = buildCoveringIndex(`${base} ORDER BY name, email`, keyspace);
+  const desc = buildCoveringIndex(`${base} ORDER BY name DESC, email`, keyspace);
+  const reordered = buildCoveringIndex(`${base} ORDER BY email, name`, keyspace);
+  assert.notEqual(asc, desc);
+  assert.notEqual(asc, reordered);
+  assert.notEqual(asc.match(/adv_covered_\w+/)[0], reordered.match(/adv_covered_\w+/)[0]);
+});
+
+test("case-distinct document fields are not collapsed", () => {
+  const statement = buildCoveringIndex("SELECT Name, name, Status, status FROM users ORDER BY Name DESC", keyspace);
+  assert.match(statement, /`Name` DESC/);
+  assert.match(statement, /`name`/);
+  assert.match(statement, /`Status`/);
+  assert.match(statement, /`status`/);
+  assert.doesNotMatch(statement, /`name` DESC/);
+});
+
+for (const state of ["online", "deferred", "pending", "building", "offline"]) {
+  test(`an existing ${state} index with reordered projection keys prevents creation`, async () => {
+    const scope = executionScope([
+      existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`"], { state }),
+    ]);
+    await createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(scope.calls.length, 2);
+    assert.equal(createStatements(scope).length, 0);
+  });
+}
+
+test("a wider existing index covers a projection subset without another index", async () => {
+  const scope = executionScope([
+    existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`phone`", "`email` DESC"]),
+  ]);
+  await createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(createStatements(scope).length, 0);
+});
+
+test("catalog key formatting, explicit ASC and attribute order are normalized", async () => {
+  for (const leadingKey of ["((`deleted`)) ASC INCLUDE MISSING", "deleted INCLUDE MISSING ASC"]) {
+    const scope = executionScope([
+      existingIndex([leadingKey, "(status) ASC", "`name`", "email ASC"]),
+    ]);
+    await createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 0, leadingKey);
+  }
+});
+
+const incompatibleIndexes = [
+  ["missing a projection field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`"])],
+  ["different access prefix", existingIndex(["`deleted` INCLUDE MISSING", "`name`", "`status`", "`email`"])],
+  ["missing-leading-key exclusion", existingIndex(["`deleted`", "`status`", "`name`", "`email`"])],
+  ["case-distinct field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`Name`", "`email`"])],
+  ["expression instead of the field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "LOWER(`name`)", "`email`"])],
+  ["array key", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`", "DISTINCT ARRAY v FOR v IN tags END"])],
+  ["partial index", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`"], { condition: "(`status` = 'pending')" })],
+  ["primary index", existingIndex([], { is_primary: true })],
+];
+for (const [reason, index] of incompatibleIndexes) {
+  test(`does not mistake ${reason} for a compatible covering index`, async () => {
+    const scope = executionScope([index]);
+    await createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 1);
+  });
+}
+
+test("existing opposite sort direction does not satisfy the requested sort", async () => {
+  const query = `${lookupQuery} ORDER BY created_at DESC`;
+  const scope = executionScope([
+    existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`created_at`", "`name`", "`email`"]),
+  ]);
+  await createDatabase(0).optimize(query, scope);
+  assert.equal(createStatements(scope).length, 1);
+  assert.match(createStatements(scope)[0].statement, /`created_at` DESC/);
+});
+
+test("same generated name is never recreated even if its keys are unavailable", async () => {
+  const candidate = buildCoveringIndexDefinition(lookupQuery, keyspace);
+  const scope = executionScope([{ name: candidate.name, state: "building" }]);
+  await createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(createStatements(scope).length, 0);
+});
+
+test("catalog failure or incomplete results prevent creation and trigger cooldown", async () => {
+  for (const options of [
+    { inventoryError: new Error("query service unavailable") },
+    { inventoryResponse: {} },
+    { inventoryResponse: { rows: [], meta: { warnings: [{ message: "partial inventory" }] } } },
+  ]) {
+    const db = createDatabase(3001);
+    const scope = executionScope([], options);
+    await db.optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 0);
+    let retries = 0;
+    db.optimize = async () => { retries++; };
+    await db.query("SELECT email FROM users WHERE status = 'pending'");
+    assert.equal(retries, 0);
+  }
+});
+
+test("already-covered plans need neither an inventory lookup nor creation", async () => {
+  const scope = executionScope([], { plan: { "#operator": "IndexScan3" } });
+  await createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(scope.calls.length, 1);
+});
+
+test("a default collection uses default names in its inventory lookup", async () => {
+  const db = createDatabase(0);
+  db.scope_name = undefined;
+  db.collection_name = undefined;
+  const scope = executionScope();
+  await db.optimize("SELECT name FROM saturn WHERE status = 'active'", scope);
+  assert.equal(JSON.stringify(scope.calls[1].options.parameters), JSON.stringify({
+    bucket: "saturn", scope: "_default", collection: "_default",
+  }));
+  assert.match(createStatements(scope)[0].statement, /`saturn`\.`_default`\.`_default`/);
+});

package/src/index.js

@@ -25,12 +25,12 @@ if (!Promise.allSettled) {
 // Couchbase lookupIn has a limit of 16 operations per call
 const LOOKUP_IN_MAX_SPECS = 16;
 
-// Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN plus
-// a possible CREATE INDEX) for any statement slower than SLOW_QUERY_MS. When
+// Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN,
+// index inventory check, and possible CREATE INDEX) above SLOW_QUERY_MS. When
 // the cluster is degraded every statement is slow, so without limits each
 // query spawned two more heavy ones and deepened the outage. These caps make it
 // a bounded, once-per-statement background task that backs off on failure.
-const SLOW_QUERY_MS = Number(process.env.SPICE_COUCHBASE_SLOW_QUERY_MS || 1000);
+const SLOW_QUERY_MS = Number(process.env.SPICE_COUCHBASE_SLOW_QUERY_MS || 3000);
 const AUTO_OPTIMIZE_ENABLED = !["0", "false", "no", "off"].includes(
   String(process.env.SPICE_COUCHBASE_AUTO_OPTIMIZE ?? "true")
     .trim()
@@ -856,7 +856,10 @@ module.exports = class Database {
   async optimize(query, exec_scope) {
     optimizeState.inFlight += 1;
     try {
-      const { buildCoveringIndex } = require("./utility");
+      const {
+        buildCoveringIndexDefinition,
+        indexSatisfiesCoveringDefinition,
+      } = require("./utility");
 
       // 1. Run EXPLAIN to get the query plan
       const explainQuery = `EXPLAIN ${query}`;
@@ -870,16 +873,48 @@ module.exports = class Database {
       }
 
       // 3. Build covering index from the query
-      const indexStatement = buildCoveringIndex(query, {
+      const candidate = buildCoveringIndexDefinition(query, {
         bucket: this.bucket,
         scope: this.scope_name,
         collection: this.collection_name,
       });
 
-      // 4. Execute the index creation if we got a valid statement
-      if (indexStatement) {
-        await exec_scope.query(indexStatement);
+      if (!candidate) return;
+
+      // EXPLAIN only describes the chosen plan. An equivalent or wider index
+      // may already exist under an older name, or still be deferred/building.
+      // Include both catalog representations of the default collection.
+      const indexResponse = await exec_scope.query(
+        `SELECT RAW i FROM system:indexes AS i
+         WHERE i.namespace_id = 'default'
+           AND ((i.bucket_id = $bucket AND i.scope_id = $scope AND i.keyspace_id = $collection)
+             OR ($scope = '_default' AND $collection = '_default'
+               AND i.bucket_id IS MISSING AND i.scope_id IS MISSING AND i.keyspace_id = $bucket))`,
+        {
+          parameters: {
+            bucket: candidate.bucket,
+            scope: candidate.scope,
+            collection: candidate.collection,
+          },
+        },
+      );
+      // A failed or incomplete inventory is not evidence that no index exists.
+      if (
+        !Array.isArray(indexResponse?.rows) ||
+        indexResponse?.meta?.warnings?.length
+      ) {
+        throw new Error("Cannot verify existing indexes before auto-optimization");
+      }
+      if (indexResponse.rows.some((index) =>
+        index.name === candidate.name ||
+        indexSatisfiesCoveringDefinition(index, candidate),
+      )) {
+        return;
       }
+
+      // Identical definitions use the same name across processes. Couchbase's
+      // per-keyspace name uniqueness also prevents a concurrent duplicate.
+      await exec_scope.query(candidate.statement);
     } catch (e) {
       // A failure here (timeout, index already exists, cluster busy) almost
       // always means the cluster is struggling. Stop adding EXPLAIN and

package/src/utility.js

@@ -245,22 +245,17 @@ function buildOrderDirectionMap(orderByIndexFields) {
   const directionMap = new Map();
   for (const { name, direction } of orderByIndexFields) {
     if (direction === "DESC") {
-      directionMap.set(name.toLowerCase(), direction);
+      directionMap.set(name, direction);
     }
   }
   return directionMap;
 }
 
 function formatIndexField(field, orderDirectionMap) {
-  const direction = orderDirectionMap.get(field.toLowerCase());
+  const direction = orderDirectionMap.get(field);
   return `\`${field}\`${direction ? ` ${direction}` : ""}`;
 }
 
-function formatIndexKey(field, orderDirectionMap) {
-  const direction = orderDirectionMap.get(field.toLowerCase());
-  return `${field}${direction ? ` ${direction}` : ""}`;
-}
-
 /**
  * Splits SELECT clause by commas, respecting parentheses
  * @param {string} clause - The SELECT clause content
@@ -293,23 +288,8 @@ function splitSelectClause(clause) {
   return parts;
 }
 
-function hasQualifiedWildcardProjection(query) {
-  const selectMatch = query.match(/\bSELECT\b(.+?)\bFROM\b/is);
-  if (!selectMatch) {
-    return false;
-  }
-
-  return splitSelectClause(selectMatch[1].trim()).some((part) => {
-    const trimmedPart = part.trim();
-    return (
-      /^\(\s*`?\w+`?\s*\)\s*\.\s*\*$/.test(trimmedPart) ||
-      /^`?\w+`?\s*\.\s*\*$/.test(trimmedPart)
-    );
-  });
-}
-
 /**
- * Builds a covering or fallback non-covering index CREATE statement from a query
+ * Builds a covering index CREATE statement from a query
  * @param {string} query - The N1QL query to analyze
  * @param {Object} options - Configuration options
  * @param {string} options.bucket - The bucket name
@@ -318,6 +298,12 @@ function hasQualifiedWildcardProjection(query) {
  * @returns {string|null} - The CREATE INDEX statement, or null if cannot build
  */
 function buildCoveringIndex(query, options) {
+  return buildCoveringIndexDefinition(query, options)?.statement ?? null;
+}
+
+// Keep the access keys separate from projection-only keys so an older, wider
+// index can satisfy the same request without depending on its generated name.
+function buildCoveringIndexDefinition(query, options) {
   const { bucket, scope = "_default", collection = "_default" } = options;
 
   if (!bucket) {
@@ -326,9 +312,9 @@ function buildCoveringIndex(query, options) {
 
   // Extract fields from SELECT clause
   const selectFields = extractSelectFields(query);
-  const isNonCoveringFallback =
-    selectFields === null && hasQualifiedWildcardProjection(query);
-  if (selectFields === null && !isNonCoveringFallback) {
+  if (selectFields === null) {
+    // Full-document projections cannot be covered by the extracted fields.
+    // Skip them instead of creating a non-covering fallback index.
     return null;
   }
 
@@ -344,44 +330,41 @@ function buildCoveringIndex(query, options) {
   const orderByFields = orderByIndexFields.map((field) => field.name);
 
   // Remove 'deleted' from whereFields as it will be added first with INCLUDE MISSING
-  const filteredWhereFields = whereFields.filter(
-    (f) => f.toLowerCase() !== "deleted",
-  );
+  const filteredWhereFields = whereFields.filter((f) => f !== "deleted");
 
   // Track fields already added to avoid duplicates
-  const addedFields = new Set(filteredWhereFields.map((f) => f.toLowerCase()));
+  const addedFields = new Set(filteredWhereFields);
 
   // Filter GROUP BY fields (remove duplicates from WHERE, remove deleted)
   const filteredGroupByFields = groupByFields.filter((f) => {
-    const lower = f.toLowerCase();
-    if (addedFields.has(lower) || lower === "deleted") {
+    if (addedFields.has(f) || f === "deleted") {
       return false;
     }
-    addedFields.add(lower);
+    addedFields.add(f);
     return true;
   });
 
   // Filter ORDER BY fields (remove duplicates from WHERE and GROUP BY, remove deleted)
   const filteredOrderByFields = orderByFields.filter((f) => {
-    const lower = f.toLowerCase();
-    if (addedFields.has(lower) || lower === "deleted") {
+    if (addedFields.has(f) || f === "deleted") {
       return false;
     }
-    addedFields.add(lower);
+    addedFields.add(f);
     return true;
   });
 
   // Filter SELECT fields (remove duplicates from WHERE, GROUP BY, and ORDER BY, remove deleted)
-  const selectFieldsFiltered = (selectFields || []).filter((f) => {
-    const lower = f.toLowerCase();
-    if (addedFields.has(lower) || lower === "deleted") {
-      return false;
-    }
-    addedFields.add(lower);
-    return true;
-  });
+  const selectFieldsFiltered = selectFields
+    .filter((f) => {
+      if (addedFields.has(f) || f === "deleted") {
+        return false;
+      }
+      addedFields.add(f);
+      return true;
+    })
+    .sort();
 
-  // All fields for the index: WHERE -> GROUP BY -> ORDER BY -> SELECT
+  // Projection order has no effect on coverage. Keep access-key order intact.
   const allFields = [
     ...filteredWhereFields,
     ...filteredGroupByFields,
@@ -395,33 +378,90 @@ function buildCoveringIndex(query, options) {
   }
 
   // Build the field list with deleted INCLUDE MISSING first
-  const fieldList = [
+  const keys = [
     "`deleted` INCLUDE MISSING",
     ...allFields.map((f) => formatIndexField(f, orderDirectionMap)),
-  ].join(", ");
-
-  // Generate unique index name based on bucket, scope, collection, and fields
-  // This ensures multiple queries covered by the same index get the same hash
-  const indexFieldsKey = allFields
-    .map((field) => formatIndexKey(field, orderDirectionMap))
-    .sort()
-    .join(",");
-  const orderFieldsKey = orderByIndexFields
-    .map((field) => formatIndexKey(field.name, orderDirectionMap))
-    .join(",");
-  const indexMode = isNonCoveringFallback ? "noncovered" : "covered";
-  const indexKey = `${bucket}|${scope}|${collection}|mode:${indexMode}|fields:${indexFieldsKey}|order:${orderFieldsKey}`;
+  ];
+
+  // Hash the actual ordered definition, not query syntax. In particular, an
+  // explicit ORDER BY ... ASC must not rename an otherwise identical index.
+  const indexKey = JSON.stringify([bucket, scope, collection, keys]);
   const hash = generateHash(indexKey);
-  const indexName = `adv_${indexMode}_${hash}`;
+  const indexName = `adv_covered_${hash}`;
 
   // Build the CREATE INDEX statement
-  const indexStatement = `CREATE INDEX \`${indexName}\` ON \`default\`:\`${bucket}\`.\`${scope}\`.\`${collection}\`(${fieldList})`;
+  const quote = (identifier) => `\`${identifier.replace(/`/g, "``")}\``;
+  const indexStatement = `CREATE INDEX \`${indexName}\` ON \`default\`:${quote(bucket)}.${quote(scope)}.${quote(collection)}(${keys.join(", ")})`;
+
+  return {
+    name: indexName,
+    statement: indexStatement,
+    keys,
+    accessKeyCount:
+      1 + filteredWhereFields.length + filteredGroupByFields.length + filteredOrderByFields.length,
+    bucket,
+    scope,
+    collection,
+  };
+}
 
-  return indexStatement;
+// Only compare simple scalar keys. Do not treat expressions, array indexes,
+// partial indexes, or case-distinct document fields as equivalent.
+function normalizeIndexKey(key) {
+  if (typeof key !== "string") return null;
+  const match = key.trim().match(
+    /^(\(*\s*(?:`(?:[^`]|``)+`|[A-Za-z_]\w*)\s*\)*)(.*?)$/s,
+  );
+  if (!match) return null;
+  let expression = match[1].trim();
+  while (expression.startsWith("(") && expression.endsWith(")")) {
+    expression = expression.slice(1, -1).trim();
+  }
+  const identifier = expression.match(/^(?:`((?:[^`]|``)+)`|([A-Za-z_]\w*))$/);
+  if (!identifier) return null;
+  const attributes = match[2].trim().toUpperCase();
+  if (!/^(?:(?:ASC|DESC)(?:\s+INCLUDE\s+MISSING)?|INCLUDE\s+MISSING(?:\s+(?:ASC|DESC))?)?$/.test(attributes)) {
+    return null;
+  }
+  return {
+    field: identifier[1] !== undefined
+      ? identifier[1].replace(/``/g, "`")
+      : identifier[2],
+    direction: /\bDESC\b/.test(attributes) ? "DESC" : "ASC",
+    includeMissing: /\bINCLUDE\s+MISSING\b/.test(attributes),
+  };
+}
+
+// Call with indexes from the candidate's exact bucket/scope/collection. State
+// is deliberately not filtered: a matching deferred/building index is already
+// committed work, even though EXPLAIN cannot use it yet.
+function indexSatisfiesCoveringDefinition(index, candidate) {
+  if (
+    index.is_primary || index.condition || index.using !== "gsi" ||
+    !Array.isArray(index.index_key)
+  ) {
+    return false;
+  }
+  const existingKeys = index.index_key.map(normalizeIndexKey);
+  const requiredKeys = candidate.keys.map(normalizeIndexKey);
+  if (existingKeys.some((key) => !key) || requiredKeys.some((key) => !key)) return false;
+  for (let i = 0; i < candidate.accessKeyCount; i++) {
+    const existing = existingKeys[i];
+    const required = requiredKeys[i];
+    if (
+      !existing || existing.field !== required.field ||
+      existing.direction !== required.direction ||
+      existing.includeMissing !== required.includeMissing
+    ) return false;
+  }
+  const existingFields = new Set(existingKeys.map((key) => key.field));
+  return requiredKeys.slice(candidate.accessKeyCount).every((key) => existingFields.has(key.field));
 }
 
 module.exports = {
   buildCoveringIndex,
+  buildCoveringIndexDefinition,
+  indexSatisfiesCoveringDefinition,
   extractWhereFields,
   extractSelectFields,
   extractGroupByFields,

package/src/utility.test.js

@@ -599,16 +599,16 @@ test("returns null when missing bucket option", () => {
   assert.strictEqual(result, null);
 });
 
-test("returns null when missing scope option", () => {
+test("uses the default scope when scope option is missing", () => {
   const query = "SELECT name FROM users WHERE status = 'active'";
   const result = buildCoveringIndex(query, { bucket: "test", collection: "users" });
-  assert.strictEqual(result, null);
+  assert.ok(result.includes("`test`.`_default`.`users`"));
 });
 
-test("returns null when missing collection option", () => {
+test("uses the default collection when collection option is missing", () => {
   const query = "SELECT name FROM users WHERE status = 'active'";
   const result = buildCoveringIndex(query, { bucket: "test", scope: "scope" });
-  assert.strictEqual(result, null);
+  assert.ok(result.includes("`test`.`scope`.`_default`"));
 });
 
 test("generates unique index name from query hash", () => {