spice-couchbase 2.0.63 → 2.0.65

package/build/index.js

@@ -1,39 +1,30 @@
 "use strict";
 
 var _process$env$SPICE_CO;
-
-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; }
-
-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(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, e) { if ("object" != typeof t || !t) return t; var r; if ("undefined" != typeof Symbol && void 0 !== (r = t[Symbol.toPrimitive])) { var i = r.call(t, e || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === e ? String : Number)(t); }
+function asyncGeneratorStep(n, t, e, r, o, a, c) { try { var i = n[a](c), u = i.value; } catch (n) { return void e(n); } i.done ? t(u) : Promise.resolve(u).then(r, o); }
+function _asyncToGenerator(n) { return function () { var t = this, e = arguments; return new Promise(function (r, o) { var a = n.apply(t, e); function _next(n) { asyncGeneratorStep(a, r, o, _next, _throw, "next", n); } function _throw(n) { asyncGeneratorStep(a, r, o, _next, _throw, "throw", n); } _next(void 0); }); }; }
 var _ = require("lodash");
-
 var couchbase = require("couchbase");
-
-var {
-  ConflictResolutionType
-} = require("couchbase");
-
-var {
-  QueryScanConsistency
-} = require("couchbase");
-
-var {
-  parseResourceList,
-  extractStatementResources
-} = require("./utility");
-
-var {
-  createHealthMonitor,
-  openHandles
-} = require("./connectionHealth");
-
+var _require = require("couchbase"),
+  ConflictResolutionType = _require.ConflictResolutionType;
+var _require2 = require("couchbase"),
+  QueryScanConsistency = _require2.QueryScanConsistency;
+var _require3 = require("./utility"),
+  parseResourceList = _require3.parseResourceList,
+  extractStatementResources = _require3.extractStatementResources,
+  statementShape = _require3.statementShape,
+  usesManagedIndex = _require3.usesManagedIndex,
+  renderIndexKey = _require3.renderIndexKey,
+  BASE_INDEX = _require3.BASE_INDEX,
+  MANAGED_INDEX_NAME = _require3.MANAGED_INDEX_NAME;
+var _require4 = require("./connectionHealth"),
+  createHealthMonitor = _require4.createHealthMonitor,
+  openHandles = _require4.openHandles;
 if (!Promise.allSettled) {
   Promise.allSettled = promises => Promise.all(promises.map((promise, i) => promise.then(value => ({
     status: "fulfilled",
@@ -42,27 +33,29 @@ if (!Promise.allSettled) {
     status: "rejected",
     reason
   }))));
-} // Couchbase lookupIn has a limit of 16 operations per call
+}
 
+// Couchbase lookupIn has a limit of 16 operations per call
+var LOOKUP_IN_MAX_SPECS = 16;
 
-var LOOKUP_IN_MAX_SPECS = 16; // Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN,
+// 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 || 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
+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
 // without limit on a workload with many distinct literals.
-
 var OPTIMIZE_SEEN_LIMIT = 1000;
 var optimizeState = {
   inFlight: 0,
   seen: new Set(),
   cooldownUntil: 0
-}; // Auto cover indexing is opt-in per resource. A resource is the collection a
+};
+// Auto cover indexing is opt-in per resource. A resource is the collection a
 // Database instance serves (scoped deployments) or the `type = '...'` literal
 // legacy bucket mode adds to every statement; raw statements also count their
 // FROM / JOIN keyspaces. Names are case-insensitive. A slow statement is
@@ -77,118 +70,118 @@ var optimizeState = {
 //      SPICE_COUCHBASE_OPTIMIZE_RESOURCES (`*` = every resource, which is the
 //      pre-2.0.62 behaviour), or connection config / constructor option
 //      `auto_optimize_resources`.
-
 var OPTIMIZE_ENABLED_RESOURCES = parseResourceList(process.env.SPICE_COUCHBASE_OPTIMIZE_RESOURCES);
-var autoOptimizePolicy = null; // One health monitor per process, shared by every copy of this module that
+var autoOptimizePolicy = null;
+// When the application installs a handler, slow statements are handed to it
+// instead of creating indexes here: it owns every index decision, with its
+// own key rules, caps and build windows. Without one, the legacy covering
+// index path below still runs, so other applications keep their behaviour.
+var slowStatementHandler = null;
+
+// One health monitor per process, shared by every copy of this module that
 // ends up loaded. See connectionHealth.js.
-
 var HEALTH_MONITOR_KEY = Symbol.for("spice-couchbase.health-monitor");
-var health = globalThis[HEALTH_MONITOR_KEY] || (globalThis[HEALTH_MONITOR_KEY] = createHealthMonitor()); // Cluster handles live on the `spice.database` globals, which a reconnect
-// replaces. Instances read them at call time instead of copying them.
+var health = globalThis[HEALTH_MONITOR_KEY] || (globalThis[HEALTH_MONITOR_KEY] = createHealthMonitor());
 
+// Cluster handles live on the `spice.database` globals, which a reconnect
+// replaces. Instances read them at call time instead of copying them.
 var HANDLE_GLOBALS = {
   cluster: "clusters",
   connection: "connections",
   scope: "scopes",
   bucket_handle: "buckets"
 };
-
 function globalHandle(kind, connection_name) {
-  var _spice, _spice$database, _spice$database$HANDL;
-
+  var _spice;
   if (typeof spice === "undefined") return undefined;
-  return (_spice = spice) === null || _spice === void 0 ? void 0 : (_spice$database = _spice.database) === null || _spice$database === void 0 ? void 0 : (_spice$database$HANDL = _spice$database[HANDLE_GLOBALS[kind]]) === null || _spice$database$HANDL === void 0 ? void 0 : _spice$database$HANDL[connection_name];
+  return (_spice = spice) === null || _spice === void 0 || (_spice = _spice.database) === null || _spice === void 0 || (_spice = _spice[HANDLE_GLOBALS[kind]]) === null || _spice === void 0 ? void 0 : _spice[connection_name];
 }
-
 function requestedAutoOptimize(query_options) {
   var _query_options$auto_o;
-
   if (!query_options || typeof query_options !== "object" || Array.isArray(query_options)) {
     return undefined;
   }
-
   var value = (_query_options$auto_o = query_options.auto_optimize) !== null && _query_options$auto_o !== void 0 ? _query_options$auto_o : query_options.optimize;
   return typeof value === "boolean" ? value : undefined;
 }
-
 function shouldOptimize(query) {
   if (!AUTO_OPTIMIZE_ENABLED) return false;
   if (optimizeState.inFlight >= OPTIMIZE_MAX_INFLIGHT) return false;
   if (Date.now() < optimizeState.cooldownUntil) return false;
   if (optimizeState.seen.has(query)) return false;
-
   if (optimizeState.seen.size >= OPTIMIZE_SEEN_LIMIT) {
     optimizeState.seen.delete(optimizeState.seen.values().next().value);
   }
-
   optimizeState.seen.add(query);
   return true;
 }
-
 function normalizeScanConsistency(value) {
   if (value === true || value === QueryScanConsistency.RequestPlus || typeof value === "string" && ["true", "request_plus"].includes(value.toLowerCase())) {
     return QueryScanConsistency.RequestPlus;
   }
-
   if (value === undefined || value === null || value === "" || value === false || value === QueryScanConsistency.NotBounded || typeof value === "string" && ["false", "not_bounded"].includes(value.toLowerCase())) {
     return QueryScanConsistency.NotBounded;
   }
-
   throw new Error("Unsupported query scan consistency: ".concat(value));
 }
-
 function buildQueryOptions() {
-  var _queryOptions$consist, _queryOptions$scanWai;
-
+  var _queryOptions$consist, _queryOptions$scanWai, _queryOptions$clientC;
   var queryOptions = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
-
   if (typeof queryOptions !== "object" || Array.isArray(queryOptions)) {
     queryOptions = {
       scan_consistency: queryOptions
     };
   }
-
   var options = {};
   var consistentWith = (_queryOptions$consist = queryOptions.consistentWith) !== null && _queryOptions$consist !== void 0 ? _queryOptions$consist : queryOptions.consistent_with;
-
   if (consistentWith !== undefined && consistentWith !== null) {
     options.consistentWith = consistentWith;
   } else {
     var _queryOptions$scanCon;
-
     options.scanConsistency = normalizeScanConsistency((_queryOptions$scanCon = queryOptions.scanConsistency) !== null && _queryOptions$scanCon !== void 0 ? _queryOptions$scanCon : queryOptions.scan_consistency);
   }
-
   var scanWait = (_queryOptions$scanWai = queryOptions.scanWait) !== null && _queryOptions$scanWai !== void 0 ? _queryOptions$scanWai : queryOptions.scan_wait;
-
   if (scanWait !== undefined && scanWait !== null && scanWait !== "") {
     var numericScanWait = Number(scanWait);
-
     if (!Number.isFinite(numericScanWait) || numericScanWait < 0) {
       throw new Error("Invalid query scan wait: ".concat(scanWait));
     }
-
     options.scanWait = numericScanWait;
   }
 
+  // Reported as clientContextID in system:completed_requests, which is how a
+  // slow statement is traced back to the route or job that ran it.
+  var clientContextId = (_queryOptions$clientC = queryOptions.clientContextId) !== null && _queryOptions$clientC !== void 0 ? _queryOptions$clientC : queryOptions.client_context_id;
+  if (clientContextId !== undefined && clientContextId !== null && clientContextId !== "") {
+    options.clientContextId = String(clientContextId).slice(0, 64);
+  }
   return options;
 }
+function wantsScanWaitFallback(query_options) {
+  return query_options && typeof query_options === "object" && (query_options.scan_wait_fallback === true || query_options.scanWaitFallback === true);
+}
 
+// The query service reports an expired scan_wait as an index scan timeout
+// (12015), which is a query error, not a connectivity timeout.
+function isScanWaitExpired(error) {
+  var _error$cause$first_er, _error$cause, _error$context, _error$cause2, _error$context2;
+  var code = (_error$cause$first_er = error === null || error === void 0 || (_error$cause = error.cause) === null || _error$cause === void 0 ? void 0 : _error$cause.first_error_code) !== null && _error$cause$first_er !== void 0 ? _error$cause$first_er : error === null || error === void 0 || (_error$context = error.context) === null || _error$context === void 0 ? void 0 : _error$context.first_error_code;
+  var message = (error === null || error === void 0 || (_error$cause2 = error.cause) === null || _error$cause2 === void 0 ? void 0 : _error$cause2.first_error_message) || (error === null || error === void 0 || (_error$context2 = error.context) === null || _error$context2 === void 0 ? void 0 : _error$context2.first_error_message) || (error === null || error === void 0 ? void 0 : error.message) || "";
+  return code === 12015 || /index scan timed out|scan.{0,20}timed? ?out/i.test(message);
+}
 module.exports = class Database {
   constructor(connection) {
-    var {
-      full_text_index,
-      collection,
-      scope,
-      query_scope = "cluster",
-      auto_create_collection,
-      auto_optimize,
-      auto_optimize_resources
-    } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-
+    var _ref = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {},
+      full_text_index = _ref.full_text_index,
+      collection = _ref.collection,
+      scope = _ref.scope,
+      _ref$query_scope = _ref.query_scope,
+      query_scope = _ref$query_scope === void 0 ? "cluster" : _ref$query_scope,
+      auto_create_collection = _ref.auto_create_collection,
+      auto_optimize = _ref.auto_optimize,
+      auto_optimize_resources = _ref.auto_optimize_resources;
     if (connection) {
-      var _spice2, _spice2$db;
-
+      var _spice2;
       this.connection_name = connection;
       this.query_scope = query_scope;
       this.bucket = this.connection._scope._bucket._name;
@@ -201,32 +194,29 @@ module.exports = class Database {
         spice.config.database.connections[connection].collection,
         this.collection_name 
       );*/
-
       this.scope_name = scope || spice.config.database.connections[connection].scope || "_default";
       this.full_text_index = spice.config.database.connections[connection].full_text_index || full_text_index;
       this.N1qlQuery = couchbase.N1qlQuery;
       this.SearchQuery = couchbase.SearchQuery;
-
-      if (!((_spice2 = spice) === null || _spice2 === void 0 ? void 0 : (_spice2$db = _spice2.db) === null || _spice2$db === void 0 ? void 0 : _spice2$db.collections)) {
+      if (!((_spice2 = spice) !== null && _spice2 !== void 0 && (_spice2 = _spice2.db) !== null && _spice2 !== void 0 && _spice2.collections)) {
         spice.db = spice.db || {};
         spice.db.collections = new Set();
       }
-
       if (this.auto_create_collection) {
         this.upsertCollection();
       }
+      this.use_bucket_name = spice.config.database.connections[this.connection_name].scope == undefined;
 
-      this.use_bucket_name = spice.config.database.connections[this.connection_name].scope == undefined; // Auto cover indexing. See OPTIMIZE_ENABLED_RESOURCES for precedence.
-
+      // Auto cover indexing. See OPTIMIZE_ENABLED_RESOURCES for precedence.
       var configured_auto_optimize = auto_optimize !== null && auto_optimize !== void 0 ? auto_optimize : this.db_config.auto_optimize;
       this.auto_optimize = typeof configured_auto_optimize === "boolean" ? configured_auto_optimize : undefined;
       this.enabled_resources = parseResourceList([...parseResourceList(this.db_config.auto_optimize_resources), ...parseResourceList(auto_optimize_resources)]);
     }
-  } // Handles resolve from the globals on every access, so an instance created
+  }
+
+  // Handles resolve from the globals on every access, so an instance created
   // before a reconnect uses the new cluster afterwards. Assigning one pins it
   // on that instance instead (tests, custom wiring).
-
-
   pinHandle(kind, value) {
     if (!Object.prototype.hasOwnProperty.call(this, "_pinned_handles")) {
       Object.defineProperty(this, "_pinned_handles", {
@@ -235,55 +225,44 @@ module.exports = class Database {
         writable: true
       });
     }
-
     this._pinned_handles[kind] = value;
   }
-
   pinnedHandle(kind) {
     var pinned = this._pinned_handles;
     return pinned && kind in pinned ? {
       value: pinned[kind]
     } : null;
   }
-
   handle(kind) {
     var pinned = this.pinnedHandle(kind);
     return pinned ? pinned.value : globalHandle(kind, this.connection_name);
   }
-
   get cluster() {
     return this.handle("cluster");
   }
-
   set cluster(value) {
     this.pinHandle("cluster", value);
   }
-
   get connection() {
     return this.handle("connection");
   }
-
   set connection(value) {
     this.pinHandle("connection", value);
   }
-
   get scope() {
     return this.handle("scope");
   }
-
   set scope(value) {
     this.pinHandle("scope", value);
   }
-
   get collection() {
     var _this$_collection_cac;
-
     var pinned = this.pinnedHandle("collection");
     if (pinned) return pinned.value;
     var scope = this.scope;
-    if (!scope) return undefined; // Collection handles are cheap but not free; cache one per scope object,
+    if (!scope) return undefined;
+    // Collection handles are cheap but not free; cache one per scope object,
     // which changes exactly when the connection is replaced.
-
     if (((_this$_collection_cac = this._collection_cache) === null || _this$_collection_cac === void 0 ? void 0 : _this$_collection_cac.scope) !== scope) {
       Object.defineProperty(this, "_collection_cache", {
         value: {
@@ -295,96 +274,80 @@ module.exports = class Database {
         configurable: true
       });
     }
-
     return this._collection_cache.collection;
   }
-
   set collection(value) {
     this.pinHandle("collection", value);
   }
-
   get collection_manager() {
     var _this$handle;
-
     var pinned = this.pinnedHandle("collection_manager");
     if (pinned) return pinned.value;
     return (_this$handle = this.handle("bucket_handle")) === null || _this$handle === void 0 ? void 0 : _this$handle.collections();
   }
-
   set collection_manager(value) {
     this.pinHandle("collection_manager", value);
   }
-
   get userManager() {
     var _this$cluster;
-
     var pinned = this.pinnedHandle("userManager");
     if (pinned) return pinned.value;
     return (_this$cluster = this.cluster) === null || _this$cluster === void 0 ? void 0 : _this$cluster.users();
   }
-
   set userManager(value) {
     this.pinHandle("userManager", value);
   }
+
   /**
    * Reports a finished operation to the health monitor. Only connectivity
    * errors (timeouts, cancelled requests, service not available) count.
    */
-
-
   recordOutcome(error) {
     health.recordOutcome(this.connection_name, error);
   }
-
   recordSettled(results) {
     for (var result of results) {
       if ((result === null || result === void 0 ? void 0 : result.status) === "rejected") this.recordOutcome(result.reason);
     }
   }
-
   observe(operation) {
     var _this = this;
-
     return _asyncToGenerator(function* () {
       try {
         return yield operation;
       } catch (error) {
         _this.recordOutcome(error);
-
         throw error;
       }
     })();
   }
-  /** Per-connection health: healthy, reconnecting, generation, last error. */
-
 
+  /** Per-connection health: healthy, reconnecting, generation, last error. */
   static healthStatus() {
     return health.status();
   }
-  /** Probes a connection now and reconnects it if the probe fails. */
-
 
+  /** Probes a connection now and reconnects it if the probe fails. */
   static checkHealth() {
     var connection_name = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "default";
     return health.check(connection_name);
   }
-  /** Opens a fresh cluster for a connection and swaps it in. */
-
 
+  /** Opens a fresh cluster for a connection and swaps it in. */
   static forceReconnect() {
     var connection_name = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "default";
     return health.reconnect(connection_name);
   }
+
   /**
    * Stops probing and reconnecting and closes replaced clusters still in
    * their grace period. Call before closing `spice.database.clusters` on
    * shutdown so a reconnect cannot race it.
    */
-
-
   static stopHealthMonitor() {
     return health.stop();
   }
+
   /**
    * Lets the application decide per resource whether slow statements may
    * create covering indexes, e.g. from a per-resource setting an operator
@@ -392,53 +355,68 @@ module.exports = class Database {
    * returns true or false, or undefined to defer to the static lists. It is
    * synchronous because it runs on the query path. Pass null to clear.
    */
-
-
   static setAutoOptimizePolicy(policy) {
     if (policy !== null && policy !== undefined && typeof policy !== "function") {
       throw new TypeError("Auto-optimize policy must be a function or null");
     }
-
     autoOptimizePolicy = policy || null;
   }
-
   static getAutoOptimizePolicy() {
     return autoOptimizePolicy;
   }
+
   /**
-   * Resources a statement touches, plus this instance's collection: that is
-   * the keyspace `optimize()` would create the index on.
+   * Hands slow statements to the application instead of creating covering
+   * indexes here. `handler({ statement, shape, plan, resources, connection,
+   * bucket, scope, collection, duration_ms })` runs in the background, once
+   * per statement shape, after the resource opt-in policy has allowed it and
+   * only when the plan is not already served by a managed index. Pass null to
+   * restore the legacy behaviour.
    */
+  static setSlowStatementHandler(handler) {
+    if (handler !== null && handler !== undefined && typeof handler !== "function") {
+      throw new TypeError("Slow statement handler must be a function or null");
+    }
+    slowStatementHandler = handler || null;
+  }
+  static getSlowStatementHandler() {
+    return slowStatementHandler;
+  }
 
+  /** The fallback index every collection gets in place of a primary index. */
+  static get BASE_INDEX() {
+    return BASE_INDEX;
+  }
+  static get MANAGED_INDEX_NAME() {
+    return MANAGED_INDEX_NAME;
+  }
 
+  /**
+   * Resources a statement touches, plus this instance's collection: that is
+   * the keyspace `optimize()` would create the index on.
+   */
   statementResources(query) {
     var resources = extractStatementResources(query);
-
     if (this.collection_name && this.collection_name !== "_default") {
       resources.add(String(this.collection_name).toLowerCase());
     }
-
     return resources;
   }
+
   /**
    * True when a slow statement may create a covering index. See
    * OPTIMIZE_ENABLED_RESOURCES for the order of precedence.
    */
-
-
   shouldAutoOptimize(query) {
     var query_options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
     var requested = requestedAutoOptimize(query_options);
     if (requested !== undefined) return requested;
     if (typeof this.auto_optimize === "boolean") return this.auto_optimize;
     var resources = this.statementResources(query);
-
     if (typeof autoOptimizePolicy === "function" && resources.size > 0) {
       var deferred = false;
-
       for (var resource of resources) {
         var verdict = void 0;
-
         try {
           verdict = autoOptimizePolicy(resource, {
             query,
@@ -449,54 +427,42 @@ module.exports = class Database {
           // A broken policy must not create indexes nobody asked for.
           verdict = false;
         }
-
         if (verdict === true) return true;
         if (verdict === undefined || verdict === null) deferred = true;
       }
-
       if (!deferred) return false;
     }
-
     var enabled = new Set([...OPTIMIZE_ENABLED_RESOURCES, ...(this.enabled_resources || [])]);
     if (enabled.has("*")) return true;
-
     for (var _resource of resources) {
       if (enabled.has(_resource)) return true;
     }
-
     return false;
   }
-
   setGlobalConnectionObject(collection) {
     if (spice.checked_collections == undefined) {
       spice.checked_collections = {};
     }
-
     _.set(spice.checked_collections, collection, true);
   }
-
   checkGlobelConnectionObject(collection) {
     if (spice.checked_collections == undefined) {
       spice.checked_collections = {};
     }
-
     if (_.get(spice.checked_collections, collection)) {
       return true;
     }
-
     this.setGlobalConnectionObject(collection);
     return false;
   }
-
   connect(connection_name, config) {
     return _asyncToGenerator(function* () {
-      var {
-        cluster,
-        bucket,
-        scope,
-        collection
-      } = yield openHandles(config); // Watch the connection from here on and replace it if it wedges.
-
+      var _yield$openHandles = yield openHandles(config),
+        cluster = _yield$openHandles.cluster,
+        bucket = _yield$openHandles.bucket,
+        scope = _yield$openHandles.scope,
+        collection = _yield$openHandles.collection;
+      // Watch the connection from here on and replace it if it wedges.
       health.register(connection_name, config);
       return {
         connection: connection_name,
@@ -507,14 +473,11 @@ module.exports = class Database {
       };
     })();
   }
-
   getUserManager(connection) {
     return globalHandle("cluster", connection).users();
   }
-
   assignUserPermission() {
     var _this2 = this;
-
     return _asyncToGenerator(function* () {
       try {
         var allUsers = yield _this2.userManager.getAllUsers({
@@ -533,42 +496,47 @@ module.exports = class Database {
         console.log(e);
       }
     })();
-  } //create wait function
-
+  }
 
+  //create wait function
   wait(ms) {
     return _asyncToGenerator(function* () {
       return new Promise(resolve => setTimeout(resolve, ms));
     })();
   }
-
   quoteIdentifier(identifier) {
     return "`".concat(String(identifier).replace(/`/g, "``"), "`");
   }
-
   collectionPath(scope_name, collection_name) {
     return "default:".concat(this.quoteIdentifier(this.db_config.bucket), ".").concat(this.quoteIdentifier(scope_name), ".").concat(this.quoteIdentifier(collection_name));
   }
-
   isCollectionAlreadyExistsError(error) {
-    var _error$cause, _error$context, _error$context2, _error$cause2, _error$cause3;
-
-    var message = (error === null || error === void 0 ? void 0 : error.message) || (error === null || error === void 0 ? void 0 : (_error$cause = error.cause) === null || _error$cause === void 0 ? void 0 : _error$cause.first_error_message) || (error === null || error === void 0 ? void 0 : (_error$context = error.context) === null || _error$context === void 0 ? void 0 : _error$context.first_error_message) || (error === null || error === void 0 ? void 0 : (_error$context2 = error.context) === null || _error$context2 === void 0 ? void 0 : _error$context2.http_response_body) || "";
-    return error instanceof couchbase.CollectionExistsError || (error === null || error === void 0 ? void 0 : (_error$cause2 = error.cause) === null || _error$cause2 === void 0 ? void 0 : _error$cause2.first_error_code) === 12003 || (error === null || error === void 0 ? void 0 : (_error$cause3 = error.cause) === null || _error$cause3 === void 0 ? void 0 : _error$cause3.first_error_code) === 12027 || /collection .*already exists|already exists/i.test(message);
+    var _error$cause3, _error$context3, _error$context4, _error$cause4, _error$cause5;
+    var message = (error === null || error === void 0 ? void 0 : error.message) || (error === null || error === void 0 || (_error$cause3 = error.cause) === null || _error$cause3 === void 0 ? void 0 : _error$cause3.first_error_message) || (error === null || error === void 0 || (_error$context3 = error.context) === null || _error$context3 === void 0 ? void 0 : _error$context3.first_error_message) || (error === null || error === void 0 || (_error$context4 = error.context) === null || _error$context4 === void 0 ? void 0 : _error$context4.http_response_body) || "";
+    return error instanceof couchbase.CollectionExistsError || (error === null || error === void 0 || (_error$cause4 = error.cause) === null || _error$cause4 === void 0 ? void 0 : _error$cause4.first_error_code) === 12003 || (error === null || error === void 0 || (_error$cause5 = error.cause) === null || _error$cause5 === void 0 ? void 0 : _error$cause5.first_error_code) === 12027 || /collection .*already exists|already exists/i.test(message);
   }
-
   upsertCollection() {
     var _this3 = this;
-
     return _asyncToGenerator(function* () {
       try {
         if (!_this3.checkGlobelConnectionObject(_this3.collection_name)) {
           var collection_exists = yield _this3.collectionExists(_this3.collection_name, _this3.scope_name);
-
           if (!collection_exists) {
+            var _this3$db_config;
             yield _this3.createCollection(_this3.collection_name, _this3.scope_name);
             yield _this3.wait(2000);
-            yield _this3.createPrimaryIndex(_this3.scope_name, _this3.collection_name);
+            // `primary_index: false` on the connection replaces the primary
+            // index with the base secondary index. A new collection is empty,
+            // so building it straight away costs nothing.
+            if (((_this3$db_config = _this3.db_config) === null || _this3$db_config === void 0 ? void 0 : _this3$db_config.primary_index) === false) {
+              yield _this3.createIndex(_objectSpread(_objectSpread({}, BASE_INDEX), {}, {
+                defer_build: false,
+                collection: _this3.collection_name,
+                scope: _this3.scope_name
+              }));
+            } else {
+              yield _this3.createPrimaryIndex(_this3.scope_name, _this3.collection_name);
+            }
           }
         }
       } catch (e) {
@@ -576,27 +544,22 @@ module.exports = class Database {
       }
     })();
   }
-
   collectionExists(collection_name, scope_name) {
     var _this4 = this;
-
     return _asyncToGenerator(function* () {
       try {
-        var _spice3, _spice3$db, _spice3$db$collection;
-
-        if ((_spice3 = spice) === null || _spice3 === void 0 ? void 0 : (_spice3$db = _spice3.db) === null || _spice3$db === void 0 ? void 0 : (_spice3$db$collection = _spice3$db.collections) === null || _spice3$db$collection === void 0 ? void 0 : _spice3$db$collection.has(collection_name)) {
+        var _spice3;
+        if ((_spice3 = spice) !== null && _spice3 !== void 0 && (_spice3 = _spice3.db) !== null && _spice3 !== void 0 && (_spice3 = _spice3.collections) !== null && _spice3 !== void 0 && _spice3.has(collection_name)) {
           return true;
         } else {
           var response = yield _this4.cluster.query("SELECT RAW keyspace_id\n           FROM system:keyspaces\n           WHERE bucket_id = ?\n             AND scope_id = ?\n             AND keyspace_id = ?\n           LIMIT 1", {
             parameters: [_this4.db_config.bucket, scope_name, collection_name],
             scanConsistency: QueryScanConsistency.RequestPlus
           });
-
           if (Array.isArray(response === null || response === void 0 ? void 0 : response.rows) && response.rows.length > 0) {
             spice.db.collections.add(collection_name);
             return true;
           }
-
           return false;
         }
       } catch (e) {
@@ -605,10 +568,8 @@ module.exports = class Database {
       }
     })();
   }
-
   createCollection(connection_name, scope_name) {
     var _this5 = this;
-
     return _asyncToGenerator(function* () {
       try {
         var response = yield _this5.cluster.query("CREATE COLLECTION ".concat(_this5.collectionPath(scope_name, connection_name)), {
@@ -621,15 +582,12 @@ module.exports = class Database {
           spice.db.collections.add(connection_name);
           return;
         }
-
         console.log("CREATE Collection :::", e);
       }
     })();
   }
-
   primaryIndexExists(scope_name, col_name) {
     var _this6 = this;
-
     return _asyncToGenerator(function* () {
       try {
         var response = yield _this6.cluster.query("SELECT RAW name\n         FROM system:indexes\n         WHERE bucket_id = ?\n           AND scope_id = ?\n           AND keyspace_id = ?\n           AND is_primary = true\n         LIMIT 1", {
@@ -643,33 +601,26 @@ module.exports = class Database {
       }
     })();
   }
-
   createPrimaryIndex(scope_name, col_name) {
     var _this7 = this;
-
     return _asyncToGenerator(function* () {
       try {
         if (yield _this7.primaryIndexExists(scope_name, col_name)) {
           return;
         }
-
         var response = yield _this7.query("CREATE PRIMARY INDEX ON ".concat(_this7.collectionPath(scope_name, col_name)));
         return response;
       } catch (e) {
         var _e$cause, _e$cause2;
-
-        if (e instanceof couchbase.IndexExistsError || (e === null || e === void 0 ? void 0 : (_e$cause = e.cause) === null || _e$cause === void 0 ? void 0 : _e$cause.first_error_code) === 4300 || /index .*already exists|index_exists/i.test((e === null || e === void 0 ? void 0 : e.message) || (e === null || e === void 0 ? void 0 : (_e$cause2 = e.cause) === null || _e$cause2 === void 0 ? void 0 : _e$cause2.first_error_message) || "")) {
+        if (e instanceof couchbase.IndexExistsError || (e === null || e === void 0 || (_e$cause = e.cause) === null || _e$cause === void 0 ? void 0 : _e$cause.first_error_code) === 4300 || /index .*already exists|index_exists/i.test((e === null || e === void 0 ? void 0 : e.message) || (e === null || e === void 0 || (_e$cause2 = e.cause) === null || _e$cause2 === void 0 ? void 0 : _e$cause2.first_error_message) || "")) {
           return;
         }
-
         console.log("CREATE Index :::", e);
       }
     })();
   }
-
   createScope(scope_name) {
     var _this8 = this;
-
     return _asyncToGenerator(function* () {
       try {
         yield _this8.collection_manager.createScope(scope_name);
@@ -683,41 +634,187 @@ module.exports = class Database {
     })();
   }
 
-  get(doc_id) {
-    var _this9 = this;
+  // Index management. Every statement here is DDL or a catalog read against a
+  // fully qualified keyspace, run at cluster level and outside `query()` so a
+  // slow build never feeds back into the slow-statement path.
+
+  runDdl(statement) {
+    var _arguments = arguments,
+      _this9 = this;
+    return _asyncToGenerator(function* () {
+      var options = _arguments.length > 1 && _arguments[1] !== undefined ? _arguments[1] : {};
+      return _this9.observe(_this9.cluster.query(statement, options));
+    })();
+  }
+
+  /**
+   * Every index on a collection, from system:indexes, including the legacy
+   * catalog form of the default collection. Rows carry name, index_key,
+   * condition, state, is_primary, using.
+   */
+  listIndexes() {
+    var _arguments2 = arguments,
+      _this0 = this;
+    return _asyncToGenerator(function* () {
+      var _response$meta;
+      var _ref2 = _arguments2.length > 0 && _arguments2[0] !== undefined ? _arguments2[0] : {},
+        _ref2$collection = _ref2.collection,
+        collection = _ref2$collection === void 0 ? _this0.collection_name : _ref2$collection,
+        _ref2$scope = _ref2.scope,
+        scope = _ref2$scope === void 0 ? _this0.scope_name : _ref2$scope;
+      var response = yield _this0.runDdl("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: _this0.db_config.bucket,
+          scope,
+          collection
+        }
+      });
+      // A failed or partial inventory is not evidence that no index exists.
+      if (!Array.isArray(response === null || response === void 0 ? void 0 : response.rows) || response !== null && response !== void 0 && (_response$meta = response.meta) !== null && _response$meta !== void 0 && (_response$meta = _response$meta.warnings) !== null && _response$meta !== void 0 && _response$meta.length) {
+        throw new Error("Cannot read the index inventory for ".concat(scope, ".").concat(collection));
+      }
+      return response.rows;
+    })();
+  }
 
-    var {
-      columns = []
-    } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  /**
+   * `CREATE INDEX IF NOT EXISTS`. Deferred by default so several indexes on
+   * one collection can be built together with `buildIndexes`, in one pass
+   * over the data.
+   */
+  createIndex() {
+    var _arguments3 = arguments,
+      _this1 = this;
+    return _asyncToGenerator(function* () {
+      var _ref3 = _arguments3.length > 0 && _arguments3[0] !== undefined ? _arguments3[0] : {},
+        name = _ref3.name,
+        keys = _ref3.keys,
+        where = _ref3.where,
+        _ref3$defer_build = _ref3.defer_build,
+        defer_build = _ref3$defer_build === void 0 ? true : _ref3$defer_build,
+        num_replica = _ref3.num_replica,
+        _ref3$collection = _ref3.collection,
+        collection = _ref3$collection === void 0 ? _this1.collection_name : _ref3$collection,
+        _ref3$scope = _ref3.scope,
+        scope = _ref3$scope === void 0 ? _this1.scope_name : _ref3$scope;
+      if (!name || !Array.isArray(keys) || keys.length === 0) {
+        throw new TypeError("createIndex needs a name and at least one key");
+      }
+      var withClause = {
+        defer_build: Boolean(defer_build)
+      };
+      if (Number.isInteger(num_replica) && num_replica >= 0) {
+        withClause.num_replica = num_replica;
+      }
+      var statement = "CREATE INDEX IF NOT EXISTS ".concat(_this1.quoteIdentifier(name), " ") + "ON ".concat(_this1.collectionPath(scope, collection), "(").concat(keys.map(renderIndexKey).join(", "), ")") + (where ? " WHERE ".concat(where) : "") + " WITH ".concat(JSON.stringify(withClause));
+      yield _this1.runDdl(statement);
+      return statement;
+    })();
+  }
+
+  /** Builds deferred indexes on one collection together. */
+  buildIndexes(names) {
+    var _arguments4 = arguments,
+      _this10 = this;
+    return _asyncToGenerator(function* () {
+      var _ref4 = _arguments4.length > 1 && _arguments4[1] !== undefined ? _arguments4[1] : {},
+        _ref4$collection = _ref4.collection,
+        collection = _ref4$collection === void 0 ? _this10.collection_name : _ref4$collection,
+        _ref4$scope = _ref4.scope,
+        scope = _ref4$scope === void 0 ? _this10.scope_name : _ref4$scope;
+      var list = [...new Set(names || [])];
+      if (list.length === 0) return null;
+      var statement = "BUILD INDEX ON ".concat(_this10.collectionPath(scope, collection)) + "(".concat(list.map(name => _this10.quoteIdentifier(name)).join(", "), ")");
+      yield _this10.runDdl(statement);
+      return statement;
+    })();
+  }
+  dropIndex(name) {
+    var _arguments5 = arguments,
+      _this11 = this;
+    return _asyncToGenerator(function* () {
+      var _ref5 = _arguments5.length > 1 && _arguments5[1] !== undefined ? _arguments5[1] : {},
+        _ref5$collection = _ref5.collection,
+        collection = _ref5$collection === void 0 ? _this11.collection_name : _ref5$collection,
+        _ref5$scope = _ref5.scope,
+        scope = _ref5$scope === void 0 ? _this11.scope_name : _ref5$scope;
+      var statement = "DROP INDEX IF EXISTS ".concat(_this11.quoteIdentifier(name), " ON ").concat(_this11.collectionPath(scope, collection));
+      yield _this11.runDdl(statement);
+      return statement;
+    })();
+  }
+  dropPrimaryIndex() {
+    var _arguments6 = arguments,
+      _this12 = this;
+    return _asyncToGenerator(function* () {
+      var _ref6 = _arguments6.length > 0 && _arguments6[0] !== undefined ? _arguments6[0] : {},
+        _ref6$collection = _ref6.collection,
+        collection = _ref6$collection === void 0 ? _this12.collection_name : _ref6$collection,
+        _ref6$scope = _ref6.scope,
+        scope = _ref6$scope === void 0 ? _this12.scope_name : _ref6$scope;
+      var statement = "DROP PRIMARY INDEX IF EXISTS ON ".concat(_this12.collectionPath(scope, collection));
+      yield _this12.runDdl(statement);
+      return statement;
+    })();
+  }
+
+  /** The plan for a statement, resolved in this instance's scope by default. */
+  explain(statement) {
+    var _arguments7 = arguments,
+      _this13 = this;
+    return _asyncToGenerator(function* () {
+      var _response$rows;
+      var query_scope = _arguments7.length > 1 && _arguments7[1] !== undefined ? _arguments7[1] : _this13.use_bucket_name ? "cluster" : "scope";
+      var exec_scope = query_scope === "cluster" ? _this13.cluster : _this13.scope;
+      var response = yield _this13.observe(exec_scope.query("EXPLAIN ".concat(statement)));
+      return response === null || response === void 0 || (_response$rows = response.rows) === null || _response$rows === void 0 ? void 0 : _response$rows[0];
+    })();
+  }
+
+  /** Couchbase's own index advice for a statement (the ADVISE statement). */
+  advise(statement) {
+    var _arguments8 = arguments,
+      _this14 = this;
     return _asyncToGenerator(function* () {
+      var _response$rows2;
+      var query_scope = _arguments8.length > 1 && _arguments8[1] !== undefined ? _arguments8[1] : _this14.use_bucket_name ? "cluster" : "scope";
+      var exec_scope = query_scope === "cluster" ? _this14.cluster : _this14.scope;
+      var response = yield _this14.observe(exec_scope.query("ADVISE ".concat(statement)));
+      return response === null || response === void 0 || (_response$rows2 = response.rows) === null || _response$rows2 === void 0 ? void 0 : _response$rows2[0];
+    })();
+  }
+  get(doc_id) {
+    var _arguments9 = arguments,
+      _this15 = this;
+    return _asyncToGenerator(function* () {
+      var _ref7 = _arguments9.length > 1 && _arguments9[1] !== undefined ? _arguments9[1] : {},
+        _ref7$columns = _ref7.columns,
+        columns = _ref7$columns === void 0 ? [] : _ref7$columns;
       try {
         var useLookupIn = columns.length > 0;
-        var collection = _this9.use_bucket_name ? _this9.connection : _this9.collection;
-
+        var collection = _this15.use_bucket_name ? _this15.connection : _this15.collection;
         if (!useLookupIn) {
-          var response = yield _this9.observe(collection.get(doc_id));
+          var response = yield _this15.observe(collection.get(doc_id));
           return _objectSpread({
             id: doc_id
           }, response.content);
-        } // Batch columns into chunks of LOOKUP_IN_MAX_SPECS (16)
-
+        }
 
+        // Batch columns into chunks of LOOKUP_IN_MAX_SPECS (16)
         var value = {
           id: doc_id
         };
+        var columnBatches = _.chunk(columns, LOOKUP_IN_MAX_SPECS);
 
-        var columnBatches = _.chunk(columns, LOOKUP_IN_MAX_SPECS); // Execute all batch requests in parallel
-
-
+        // Execute all batch requests in parallel
         var batchPromises = columnBatches.map(batch => {
           var specs = batch.map(col => couchbase.LookupInSpec.get(col));
           return collection.lookupIn(doc_id, specs);
         });
         var batchResults = yield Promise.allSettled(batchPromises);
+        _this15.recordSettled(batchResults);
 
-        _this9.recordSettled(batchResults); // Merge results from all batches
-
-
+        // Merge results from all batches
         batchResults.forEach((result, batchIndex) => {
           if (result.status === "fulfilled" && result.value) {
             var batch = columnBatches[batchIndex];
@@ -734,131 +831,109 @@ module.exports = class Database {
       }
     })();
   }
-
   insert(doc_id, document, expiry) {
-    var _this10 = this;
-
+    var _this16 = this;
     return _asyncToGenerator(function* () {
       try {
-        yield _this10.observe((_this10.use_bucket_name ? _this10.connection : _this10.collection).insert(doc_id, document, {
+        yield _this16.observe((_this16.use_bucket_name ? _this16.connection : _this16.collection).insert(doc_id, document, {
           expiry: expiry
         }));
       } catch (e) {
         console.log(e.message, e, doc_id);
       }
-
-      return yield _this10.get(doc_id);
+      return yield _this16.get(doc_id);
     })();
   }
-
   touch(doc_id) {
-    var _this11 = this;
-
-    var expiry = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+    var _arguments0 = arguments,
+      _this17 = this;
     return _asyncToGenerator(function* () {
-      yield _this11.observe((_this11.use_bucket_name ? _this11.connection : _this11.collection).touch(doc_id, expiry));
-      return yield _this11.get(doc_id);
+      var expiry = _arguments0.length > 1 && _arguments0[1] !== undefined ? _arguments0[1] : 0;
+      yield _this17.observe((_this17.use_bucket_name ? _this17.connection : _this17.collection).touch(doc_id, expiry));
+      return yield _this17.get(doc_id);
     })();
   }
-
   count(doc_id, adjustment, initial_value) {
-    var _this12 = this;
-
+    var _this18 = this;
     return _asyncToGenerator(function* () {
-      var res = yield _this12.observe((_this12.use_bucket_name ? _this12.connection : _this12.collection).counter(doc_id, adjustment, {
+      var res = yield _this18.observe((_this18.use_bucket_name ? _this18.connection : _this18.collection).counter(doc_id, adjustment, {
         initial: initial_value
       }));
       return res.value;
     })();
   }
-
   update(doc_id, document, expiry) {
-    var _this13 = this;
-
+    var _this19 = this;
     return _asyncToGenerator(function* () {
-      var res = yield _this13.observe((_this13.use_bucket_name ? _this13.connection : _this13.collection).replace(doc_id, document, {
+      var res = yield _this19.observe((_this19.use_bucket_name ? _this19.connection : _this19.collection).replace(doc_id, document, {
         expiry: expiry
       }));
       return res.value;
     })();
   }
-
   delete(doc_id) {
-    var _this14 = this;
-
+    var _this20 = this;
     return _asyncToGenerator(function* () {
-      var res = yield _this14.observe((_this14.use_bucket_name ? _this14.connection : _this14.collection).remove(doc_id));
+      var res = yield _this20.observe((_this20.use_bucket_name ? _this20.connection : _this20.collection).remove(doc_id));
       return res.value;
     })();
   }
-
   multi_get(keys) {
-    var _this15 = this;
-
-    var {
-      keep_type = true,
-      columns = []
-    } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    var _arguments1 = arguments,
+      _this21 = this;
     return _asyncToGenerator(function* () {
+      var _ref8 = _arguments1.length > 1 && _arguments1[1] !== undefined ? _arguments1[1] : {},
+        _ref8$keep_type = _ref8.keep_type,
+        keep_type = _ref8$keep_type === void 0 ? true : _ref8$keep_type,
+        _ref8$columns = _ref8.columns,
+        columns = _ref8$columns === void 0 ? [] : _ref8$columns;
       if (keys.length == 0) {
         return [];
       }
-
       if (_.isArray(keys) && keys.length > 0) {
         var useLookupIn = columns.length > 0;
-        var collection = _this15.use_bucket_name ? _this15.connection : _this15.collection;
-
+        var collection = _this21.use_bucket_name ? _this21.connection : _this21.collection;
         if (!useLookupIn) {
           // Regular get - no batching needed
           var functions = _.map(keys, key => collection.get(key));
-
           var returned_all = yield Promise.allSettled(functions);
-
-          _this15.recordSettled(returned_all);
-
+          _this21.recordSettled(returned_all);
           var responses = _.flatten(_.map(returned_all, returned_obj => returned_obj === null || returned_obj === void 0 ? void 0 : returned_obj.value));
-
           var _final_responses = _.compact(_.map(responses, (res, index) => {
             if (res) {
               var value = res.value;
-
               if (!keep_type && value) {
                 delete value.type;
               }
-
               if (value) {
                 value.id = keys[index];
               }
-
               return value;
             }
           }));
-
           return _final_responses;
-        } // lookupIn with batching for columns > 16
-
-
-        var columnBatches = _.chunk(columns, LOOKUP_IN_MAX_SPECS); // For each key, we need to fetch all column batches and merge the results
+        }
 
+        // lookupIn with batching for columns > 16
+        var columnBatches = _.chunk(columns, LOOKUP_IN_MAX_SPECS);
 
-        var keyPromises = _.map(keys,
-        /*#__PURE__*/
-        function () {
-          var _ref = _asyncToGenerator(function* (key) {
+        // For each key, we need to fetch all column batches and merge the results
+        var keyPromises = _.map(keys, /*#__PURE__*/function () {
+          var _ref9 = _asyncToGenerator(function* (key) {
             try {
               var value = {
                 id: key
-              }; // Execute all batch requests for this key in parallel
+              };
 
+              // Execute all batch requests for this key in parallel
               var batchPromises = columnBatches.map(batch => {
                 var specs = batch.map(col => couchbase.LookupInSpec.get(col));
                 return collection.lookupIn(key, specs);
               });
               var batchResults = yield Promise.allSettled(batchPromises);
+              _this21.recordSettled(batchResults);
 
-              _this15.recordSettled(batchResults); // Merge results from all batches
-
-
+              // Merge results from all batches
               batchResults.forEach((result, batchIndex) => {
                 if (result.status === "fulfilled" && result.value) {
                   var batch = columnBatches[batchIndex];
@@ -869,75 +944,56 @@ module.exports = class Database {
                   });
                 }
               });
-
               if (!keep_type && value) {
                 delete value.type;
               }
-
               return value;
             } catch (e) {
               return null;
             }
           });
-
           return function (_x) {
-            return _ref.apply(this, arguments);
+            return _ref9.apply(this, arguments);
           };
         }());
-
         var results = yield Promise.allSettled(keyPromises);
-
         var final_responses = _.compact(_.map(results, result => {
           if (result.status === "fulfilled" && result.value) {
             // Only return if we got at least some data beyond just the id
             return Object.keys(result.value).length > 1 ? result.value : null;
           }
-
           return null;
         }));
-
         return final_responses;
       } else {
         return [];
       }
     })();
   }
-
   get_view(view, design_doc, search_query, limit, offset) {
     var that = this;
-    return new Promise(
-    /*#__PURE__*/
-    function () {
-      var _ref2 = _asyncToGenerator(function* (resolve, reject) {
+    return new Promise(/*#__PURE__*/function () {
+      var _ref0 = _asyncToGenerator(function* (resolve, reject) {
         var ViewQuery = couchbase.ViewQuery;
         var query = ViewQuery.from(design_doc, view);
-
         if (!limit) {
           limit = 0;
         }
-
         if (!offset) {
           offset = 0;
         }
-
         if (limit > 0) {
           query.limit(limit);
         }
-
         query.skip(offset);
-
         if (search_query) {
           if (search_query.length > 0) {
             query.range(search_query, search_query);
           }
         }
-
-        that.connection.query(query,
-        /*#__PURE__*/
-        function () {
-          var _ref3 = _asyncToGenerator(function* (err, results, matrix) {
+        that.connection.query(query, /*#__PURE__*/function () {
+          var _ref1 = _asyncToGenerator(function* (err, results, matrix) {
             var return_value = [];
-
             if (err) {
               reject(err);
             } else {
@@ -948,7 +1004,6 @@ module.exports = class Database {
                   return_value.push(results[i].key);
                 }
               }
-
               try {
                 var created = yield that.multi_get(return_value);
                 resolve(created);
@@ -957,42 +1012,38 @@ module.exports = class Database {
               }
             }
           });
-
           return function (_x4, _x5, _x6) {
-            return _ref3.apply(this, arguments);
+            return _ref1.apply(this, arguments);
           };
         }());
       });
-
       return function (_x2, _x3) {
-        return _ref2.apply(this, arguments);
+        return _ref0.apply(this, arguments);
       };
     }());
   }
-
   search(type) {
-    var _this16 = this;
-
-    var columns = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : "";
-    var query = arguments.length > 2 ? arguments[2] : undefined;
-    var limit = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 0;
-    var offset = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : 0;
-    var order_by = arguments.length > 5 ? arguments[5] : undefined;
-    var do_count = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : "false";
-    var query_scope = arguments.length > 7 ? arguments[7] : undefined;
-    var join = arguments.length > 8 && arguments[8] !== undefined ? arguments[8] : "";
-    var query_options = arguments.length > 9 && arguments[9] !== undefined ? arguments[9] : {};
+    var _arguments10 = arguments,
+      _this22 = this;
     return _asyncToGenerator(function* () {
-      var is_legacy = _this16.scope_name !== "_default" && _this16.collection_name !== "_default";
-      var bucket = "`".concat(_this16.use_bucket_name ? _this16.bucket : _this16.collection_name, "`");
-
+      var columns = _arguments10.length > 1 && _arguments10[1] !== undefined ? _arguments10[1] : "";
+      var query = _arguments10.length > 2 ? _arguments10[2] : undefined;
+      var limit = _arguments10.length > 3 && _arguments10[3] !== undefined ? _arguments10[3] : 0;
+      var offset = _arguments10.length > 4 && _arguments10[4] !== undefined ? _arguments10[4] : 0;
+      var order_by = _arguments10.length > 5 ? _arguments10[5] : undefined;
+      var do_count = _arguments10.length > 6 && _arguments10[6] !== undefined ? _arguments10[6] : "false";
+      var query_scope = _arguments10.length > 7 ? _arguments10[7] : undefined;
+      var join = _arguments10.length > 8 && _arguments10[8] !== undefined ? _arguments10[8] : "";
+      var query_options = _arguments10.length > 9 && _arguments10[9] !== undefined ? _arguments10[9] : {};
+      var is_legacy = _this22.scope_name !== "_default" && _this22.collection_name !== "_default";
+      var bucket = "`".concat(_this22.use_bucket_name ? _this22.bucket : _this22.collection_name, "`");
       function processColumns(columnsStr) {
         // If columns is empty or *, return default
         if (columnsStr === "*" || !columnsStr) {
           return "(".concat(bucket, ").*, META(").concat(bucket, ").id AS id");
-        } // Split by comma and process each column
-
+        }
 
+        // Split by comma and process each column
         var columnList = columnsStr.split(",").map(col => col.trim());
         var hasId = false;
         var processedColumns = columnList.map(col => {
@@ -1000,10 +1051,9 @@ module.exports = class Database {
           // Patterns: `collection`.`id`, collection.id, `id`, id
           var idPattern = /^(?:`?(\w+)`?\.)?`?id`?$/i;
           var match = col.match(idPattern);
-
           if (match) {
-            hasId = true; // match[1] contains the collection name if present
-
+            hasId = true;
+            // match[1] contains the collection name if present
             if (match[1]) {
               // Has collection prefix: `collection`.`id` or collection.id
               return "META(`".concat(match[1], "`).id AS id");
@@ -1011,52 +1061,47 @@ module.exports = class Database {
               // Just id without collection prefix
               return "META(".concat(bucket, ").id AS id");
             }
-          } // Return the column as-is
-
+          }
 
+          // Return the column as-is
           return col;
-        }); // If no id column was provided, add it automatically
+        });
 
+        // If no id column was provided, add it automatically
         if (!hasId) {
           processedColumns.push("META(".concat(bucket, ").id AS id"));
         }
-
         return processedColumns.join(", ");
       }
-
       try {
         columns = processColumns(columns);
         var front_query = "SELECT ".concat(columns, " FROM ").concat(bucket, " ").concat(join);
         var conditions = [];
-
-        if (_this16.use_bucket_name) {
+        if (_this22.use_bucket_name) {
           conditions.push("type = '".concat(type, "'"));
         }
-
         if (query) {
           conditions.push(query);
-        } // The conditions are folded into `where_clause` itself so that both queries below are built
+        }
+
+        // The conditions are folded into `where_clause` itself so that both queries below are built
         // from one string. Previously this held the bare literal " WHERE " and only the data query
         // appended `conditions.join(" AND ")`, which left the count query emitting a dangling
         // `WHERE` — Couchbase answered "syntax error - at end of input" and every `do_count=true`
         // request failed with a 400, on every resource.
-
-
         var where_clause = conditions.length ? " WHERE ".concat(conditions.join(" AND ")) : "";
         query = front_query + where_clause;
-        var count_query = "SELECT count(meta(".concat(bucket, ").id) as count FROM ").concat(bucket, " ").concat(join, " ").concat(where_clause); //console.log("Cound Query::", count_query);
-
+        var count_query = "SELECT count(meta(".concat(bucket, ").id) as count FROM ").concat(bucket, " ").concat(join, " ").concat(where_clause);
+        //console.log("Cound Query::", count_query);
         var order_by_clause = order_by ? " ORDER BY ".concat(order_by) : "";
         var limit_clause = limit > 0 ? " LIMIT ".concat(limit) : "";
         var offset_clause = offset > 0 ? " OFFSET ".concat(offset) : "";
         query = query + order_by_clause + limit_clause + offset_clause;
-        var active_query_space = query_scope || (!_this16.use_bucket_name ? "scope" : "cluster");
-        var queries = [_this16.getData(query, active_query_space, query_options)];
-
+        var active_query_space = query_scope || (!_this22.use_bucket_name ? "scope" : "cluster");
+        var queries = [_this22.getData(query, active_query_space, query_options)];
         if (do_count != "false") {
-          queries.push(_this16.getCount(count_query, active_query_space, query_options));
+          queries.push(_this22.getCount(count_query, active_query_space, query_options));
         }
-
         var responses = yield Promise.all(queries);
         return {
           data: responses[0],
@@ -1067,38 +1112,28 @@ module.exports = class Database {
       }
     })();
   }
-
   full_text_search(type, search_query, limit) {
     var offset = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 0;
     var full_text_index = arguments.length > 4 ? arguments[4] : undefined;
     var that = this;
-    return new Promise(
-    /*#__PURE__*/
-    function () {
-      var _ref4 = _asyncToGenerator(function* (resolve, reject) {
+    return new Promise(/*#__PURE__*/function () {
+      var _ref10 = _asyncToGenerator(function* (resolve, reject) {
         try {
           var full_query = search_query + " AND type:" + type;
           var query = that.SearchQuery.new(that.full_text_index || full_text_index, that.SearchQuery.queryString(full_query));
-
           if (!limit) {
             limit = 0;
           }
-
           if (!offset) {
             offset = 0;
           }
-
           if (limit > 0) {
             query.limit(limit);
           }
-
           query.skip(offset);
-          that.cluster.query(query,
-          /*#__PURE__*/
-          function () {
-            var _ref5 = _asyncToGenerator(function* (err, results, matrix) {
+          that.cluster.query(query, /*#__PURE__*/function () {
+            var _ref11 = _asyncToGenerator(function* (err, results, matrix) {
               var return_value = [];
-
               if (err) {
                 reject(err);
               } else {
@@ -1109,7 +1144,6 @@ module.exports = class Database {
                     return_value.push(results[i].id);
                   }
                 }
-
                 try {
                   var getted = yield that.multi_get(return_value);
                   resolve({
@@ -1121,64 +1155,58 @@ module.exports = class Database {
                 }
               }
             });
-
-            return function (_x9, _x10, _x11) {
-              return _ref5.apply(this, arguments);
+            return function (_x9, _x0, _x1) {
+              return _ref11.apply(this, arguments);
             };
           }());
         } catch (e) {
           reject(e);
         }
       });
-
       return function (_x7, _x8) {
-        return _ref4.apply(this, arguments);
+        return _ref10.apply(this, arguments);
       };
     }());
   }
-
   getCount(count_query_element) {
-    var _this17 = this;
-
-    var query_scope = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : "cluster";
-    var query_options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    var _arguments11 = arguments,
+      _this23 = this;
     return _asyncToGenerator(function* () {
-      var response = yield _this17.query(count_query_element, query_scope, query_options);
+      var query_scope = _arguments11.length > 1 && _arguments11[1] !== undefined ? _arguments11[1] : "cluster";
+      var query_options = _arguments11.length > 2 && _arguments11[2] !== undefined ? _arguments11[2] : {};
+      var response = yield _this23.query(count_query_element, query_scope, query_options);
       return response.rows[0].count;
     })();
   }
-
   getData(query_element) {
-    var _this18 = this;
-
-    var query_scope = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : "cluster";
-    var query_options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    var _arguments12 = arguments,
+      _this24 = this;
     return _asyncToGenerator(function* () {
-      var response = yield _this18.query(query_element, query_scope, query_options);
+      var query_scope = _arguments12.length > 1 && _arguments12[1] !== undefined ? _arguments12[1] : "cluster";
+      var query_options = _arguments12.length > 2 && _arguments12[2] !== undefined ? _arguments12[2] : {};
+      var response = yield _this24.query(query_element, query_scope, query_options);
       return response.rows;
     })();
   }
+
   /**
    * Recursively checks if the query plan contains a Fetch operator
    * @param {Object} plan - The EXPLAIN query plan
    * @returns {boolean} - True if Fetch operator is found
    */
-
-
   hasFetchOperator(plan) {
     if (!plan || typeof plan !== "object") {
       return false;
-    } // Check if this node is a Fetch operator
-
+    }
 
+    // Check if this node is a Fetch operator
     if (plan["#operator"] === "Fetch") {
       return true;
-    } // Recursively check all child properties
-
+    }
 
+    // Recursively check all child properties
     for (var key of Object.keys(plan)) {
       var value = plan[key];
-
       if (Array.isArray(value)) {
         for (var item of value) {
           if (this.hasFetchOperator(item)) {
@@ -1191,63 +1219,57 @@ module.exports = class Database {
         }
       }
     }
-
     return false;
   }
-
   optimize(query, exec_scope) {
-    var _this19 = this;
-
+    var _this25 = this;
     return _asyncToGenerator(function* () {
       optimizeState.inFlight += 1;
-
       try {
-        var _explainResponse$rows, _indexResponse$meta, _indexResponse$meta$w;
-
-        var {
-          buildCoveringIndexDefinition,
-          indexSatisfiesCoveringDefinition
-        } = require("./utility"); // 1. Run EXPLAIN to get the query plan
-
+        var _explainResponse$rows, _indexResponse$meta;
+        var _require5 = require("./utility"),
+          buildCoveringIndexDefinition = _require5.buildCoveringIndexDefinition,
+          indexSatisfiesCoveringDefinition = _require5.indexSatisfiesCoveringDefinition;
 
+        // 1. Run EXPLAIN to get the query plan
         var explainQuery = "EXPLAIN ".concat(query);
-        var explainResponse = yield exec_scope.query(explainQuery); // 2. Check if query plan contains Fetch operator (not covered)
-
-        var plan = explainResponse === null || explainResponse === void 0 ? void 0 : (_explainResponse$rows = explainResponse.rows) === null || _explainResponse$rows === void 0 ? void 0 : _explainResponse$rows[0];
+        var explainResponse = yield exec_scope.query(explainQuery);
 
-        if (!_this19.hasFetchOperator(plan)) {
+        // 2. Check if query plan contains Fetch operator (not covered)
+        var plan = explainResponse === null || explainResponse === void 0 || (_explainResponse$rows = explainResponse.rows) === null || _explainResponse$rows === void 0 ? void 0 : _explainResponse$rows[0];
+        if (!_this25.hasFetchOperator(plan)) {
           // Query is already covered, no need to create index
           return;
-        } // 3. Build covering index from the query
-
+        }
 
+        // 3. Build covering index from the query
         var candidate = buildCoveringIndexDefinition(query, {
-          bucket: _this19.bucket,
-          scope: _this19.scope_name,
-          collection: _this19.collection_name
+          bucket: _this25.bucket,
+          scope: _this25.scope_name,
+          collection: _this25.collection_name
         });
-        if (!candidate) return; // EXPLAIN only describes the chosen plan. An equivalent or wider index
+        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 (!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)) {
+        });
+        // A failed or incomplete inventory is not evidence that no index exists.
+        if (!Array.isArray(indexResponse === null || indexResponse === void 0 ? void 0 : indexResponse.rows) || indexResponse !== null && indexResponse !== void 0 && (_indexResponse$meta = indexResponse.meta) !== null && _indexResponse$meta !== void 0 && (_indexResponse$meta = _indexResponse$meta.warnings) !== null && _indexResponse$meta !== void 0 && _indexResponse$meta.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.
-
+        }
 
+        // 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
@@ -1259,44 +1281,90 @@ module.exports = class Database {
       }
     })();
   }
-
   query(query, query_scope) {
-    var _this20 = this;
-
-    var query_options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    var _arguments13 = arguments,
+      _this26 = this;
     return _asyncToGenerator(function* () {
+      var query_options = _arguments13.length > 2 && _arguments13[2] !== undefined ? _arguments13[2] : {};
       if (query_scope && typeof query_scope === "object" && !Array.isArray(query_scope)) {
         query_options = query_scope;
         query_scope = undefined;
       }
-
-      var scope = query_scope || _this20.query_scope || "cluster";
+      var scope = query_scope || _this26.query_scope || "cluster";
       var sanitizedQuery = query; //sanitization step to be implemented
-
       var exec_scope = null;
-
       if (scope === "cluster") {
-        exec_scope = _this20.cluster;
+        exec_scope = _this26.cluster;
       } else {
-        exec_scope = _this20.scope;
-      } // Start time
-
-
+        exec_scope = _this26.scope;
+      }
+      // Start time
       var startTime = process.hrtime.bigint();
       var options = buildQueryOptions(query_options);
-      var response = yield _this20.observe(exec_scope.query(sanitizedQuery, options)); // End time
-
-      var endTime = process.hrtime.bigint(); // Calculate duration in microseconds
-
-      var durationInMilliseconds = (endTime - startTime) / BigInt(1000000); // Optimise slow statements in the background, subject to the guard rails
+      var response;
+      try {
+        response = yield _this26.observe(exec_scope.query(sanitizedQuery, options));
+      } catch (error) {
+        // `scan_wait_fallback`: a request_plus read that could not get a fresh
+        // index snapshot within `scan_wait` runs once more without waiting, for
+        // callers that prefer a slightly stale answer to an error.
+        if (!wantsScanWaitFallback(query_options) || options.scanConsistency !== QueryScanConsistency.RequestPlus || options.scanWait === undefined || !isScanWaitExpired(error)) {
+          throw error;
+        }
+        console.warn("[spice-couchbase] index not current within ".concat(options.scanWait, "ms; reading without waiting"));
+        response = yield _this26.observe(exec_scope.query(sanitizedQuery, _objectSpread(_objectSpread({}, _.omit(options, ["scanWait"])), {}, {
+          scanConsistency: QueryScanConsistency.NotBounded
+        })));
+      }
+      // End time
+      var endTime = process.hrtime.bigint();
+      // Calculate duration in microseconds
+      var durationInMilliseconds = (endTime - startTime) / BigInt(1000000);
+      // Optimise slow statements in the background, subject to the guard rails
       // declared at the top of this file. Never awaited, never allowed to reject.
-
-      if (durationInMilliseconds > SLOW_QUERY_MS && _this20.shouldAutoOptimize(sanitizedQuery, query_options) && shouldOptimize(sanitizedQuery)) {
-        _this20.optimize(sanitizedQuery, exec_scope).catch(() => {});
+      if (durationInMilliseconds > SLOW_QUERY_MS && _this26.shouldAutoOptimize(sanitizedQuery, query_options)) {
+        if (slowStatementHandler) {
+          if (shouldOptimize(statementShape(sanitizedQuery))) {
+            _this26.reportSlowStatement(sanitizedQuery, exec_scope, Number(durationInMilliseconds)).catch(() => {});
+          }
+        } else if (shouldOptimize(sanitizedQuery)) {
+          _this26.optimize(sanitizedQuery, exec_scope).catch(() => {});
+        }
       }
-
       return response;
     })();
   }
 
+  /**
+   * Hands a slow statement to the application's handler, unless its plan is
+   * already served by a managed index. Runs under the same in-flight and
+   * cooldown guard rails as `optimize()`.
+   */
+  reportSlowStatement(query, exec_scope, duration_ms) {
+    var _this27 = this;
+    return _asyncToGenerator(function* () {
+      optimizeState.inFlight += 1;
+      try {
+        var _explainResponse$rows2;
+        var explainResponse = yield exec_scope.query("EXPLAIN ".concat(query));
+        var plan = explainResponse === null || explainResponse === void 0 || (_explainResponse$rows2 = explainResponse.rows) === null || _explainResponse$rows2 === void 0 ? void 0 : _explainResponse$rows2[0];
+        if (usesManagedIndex(plan)) return;
+        yield slowStatementHandler({
+          statement: query,
+          shape: statementShape(query),
+          plan,
+          resources: [..._this27.statementResources(query)],
+          connection: _this27.connection_name,
+          bucket: _this27.bucket,
+          scope: _this27.scope_name,
+          collection: _this27.collection_name,
+          duration_ms
+        });
+      } catch (e) {
+        optimizeState.cooldownUntil = Date.now() + OPTIMIZE_FAILURE_COOLDOWN_MS;
+      } finally {
+        optimizeState.inFlight -= 1;
+      }
+    })();
+  }
 };