Support maxRecords scan policy (#359)

* Support maxRecords scan policy

* Fix version number, when option was introduced; update changelog

* Skip percent-based sampling tests on server v4.9+

* Add note about scan percent sampling on v4.9

Author: Jan Hecking

CHANGELOG.md

@@ -4,7 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+* **New Features**
+  * Added a max records option for sampling with basic scans. Requires server version 4.9 or later. [#359](https://github.com/aerospike/aerospike-client-nodejs/pull/359)
+
 * **Updates**
+  * *BREAKING*: The client no longer supports the percent-based scan sampling for server versions 4.9 or later. Use the new max records scan policy option instead.
   * Update C client library to [v4.6.14](http://www.aerospike.com/download/client/c/notes.html#4.6.14).
 
 ## [3.15.0] - 2020-03-24

lib/policies/scan_policy.js

@@ -73,6 +73,21 @@ class ScanPolicy extends BasePolicy {
      * @since v3.14.0
      */
     this.recordsPerSecond = props.recordsPerSecond
+
+    /**
+     * Approximate number of records to return to client. This number is
+     * divided by the number of nodes involved in the scan. The actual number
+     * of records returned may be less than maxRecords if node record counts
+     * are small and unbalanced across nodes.
+     *
+     * Requires Aerospike Server version >= 4.9.
+     *
+     * @type number
+     * @default 0 (do not limit record count)
+     *
+     * @since v3.16.0
+     */
+    this.maxRecords = props.maxRecords
   }
 }
 

lib/scan.js

@@ -140,7 +140,11 @@ function Scan (client, ns, set, options) {
   this.priority = options.priority
 
   /**
-   * Percentage of records in the cluster to scan.
+   * Percentage of records in the cluster to scan. Valid integer range is 1 to
+   * 100.
+   *
+   * This field is supported on server versions < 4.9. For server versions >=
+   * 4.9, use {@link ScanPolicy#maxRecords}.
    *
    * @member {number} Scan#percent
    */

src/main/policy.cc

@@ -312,6 +312,9 @@ int scanpolicy_from_jsobject(as_policy_scan* policy, Local<Object> obj, const Lo
 	if ((rc = get_optional_uint32_property((uint32_t*) &policy->records_per_second, NULL, obj, "recordsPerSecond", log)) != AS_NODE_PARAM_OK) {
 		return rc;
 	}
+	if ((rc = get_optional_uint32_property((uint32_t*) &policy->max_records, NULL, obj, "maxRecords", log)) != AS_NODE_PARAM_OK) {
+		return rc;
+	}
 	as_v8_detail( log, "Parsing scan policy: success");
 	return AS_NODE_PARAM_OK;
 }

src/main/scan.cc

@@ -88,7 +88,9 @@ void setup_scan(as_scan* scan, Local<Value> ns, Local<Value> set, Local<Value> m
 	Local<Value> percent = Nan::Get(options, Nan::New("percent").ToLocalChecked()).ToLocalChecked();
 	TYPE_CHECK_OPT(percent, IsNumber, "percent must be a number");
 	if (percent->IsNumber()) {
-		as_scan_set_percent(scan, (uint8_t) Nan::To<uint32_t>(percent).FromJust());
+		uint8_t pct = (uint8_t) Nan::To<uint32_t>(percent).FromJust();
+		as_v8_detail(log, "Setting scan percent to %i", pct);
+		as_scan_set_percent(scan, pct);
 	}
 
 	Local<Value> priority = Nan::Get(options, Nan::New("priority").ToLocalChecked()).ToLocalChecked();

test/scan.js

@@ -147,7 +147,8 @@ context('Scans', function () {
         socketTimeout: 1000,
         durableDelete: true,
         failOnClusterChange: true,
-        recordsPerSecond: 50
+        recordsPerSecond: 50,
+        maxRecords: 5000
       })
 
       const stream = scan.foreach(policy)
@@ -190,6 +191,8 @@ context('Scans', function () {
     })
 
     context('with percent sampling', function () {
+      helper.skipUnlessVersion('< 4.9', this)
+
       it('should only scan approx. half of the records', function (done) {
         const scan = client.scan(helper.namespace, testSet, {
           percent: 50,
@@ -207,6 +210,25 @@ context('Scans', function () {
       })
     })
 
+    context('with max records limit', function () {
+      helper.skipUnlessVersion('>= 4.9.0', this)
+
+      it('returns at most X number of records', function (done) {
+        const scan = client.scan(helper.namespace, testSet, { nobins: true })
+
+        const maxRecords = 33
+        const stream = scan.foreach({ maxRecords })
+        let recordsReceived = 0
+        stream.on('data', () => recordsReceived++)
+        stream.on('end', () => {
+          // The actual number returned may be less than maxRecords if node
+          // record counts are small and unbalanced across nodes.
+          expect(recordsReceived).to.be.at.most(maxRecords)
+          done()
+        })
+      })
+    })
+
     context('without set', function () {
       it('executes a scan without set', function (done) {
         var scan = client.scan(helper.namespace)