docs: function withOptions() {
    /*jshint validthis:true */
    var self = (this instanceof QueryBuilder) ? this : new QueryBuilder();
  
    // TODO: share with documents.js
    var optionKeyMapping = {
      search:'search-option',     weight:'quality-weight',
      forestNames:'forest',       similarDocs:'return-similar',
      metrics:'return-metrics',   queryPlan:'return-plan',
      debug:'debug',              concurrencyLevel:'concurrency-level',
      categories:true,            txid:true
    };
  
    var withOptionsClause = {};
    if (0 < arguments.length) {
      var arg = arguments[0];
      var argKeys = Object.keys(arg);
      for (var i=0; i < argKeys.length; i++) {
        var key = argKeys[i];
        if (optionKeyMapping[key] !== void 0) {
          var value = arg[key];
          if (value !== void 0) {
            withOptionsClause[key] = value;
          } else {
            throw new Error('empty options value for '+key);
          }
        } else {
          throw new Error('unknown option '+key);
        }
      }
    }
    self.withOptionsClause = withOptionsClause;
  
    return self;
  }