Class: Scan

Scan

The scan object created by calling Client#scan is used for executing record scans on the specified namespace and set (optional). Scans can return a set of records as a RecordStream or apply an Aerospike UDF (user-defined function) on each of the records on the server.

For more information, please refer to the section on ⇑Scans in the Aerospike technical documentation.

Selecting Bins

Using Scan#select it is possible to select a subset of bins which should be returned by the query. If no bins are selected, then the whole record will be returned. If the Scan#nobins property is set to true the only the record meta data (ttl, generation, etc.) will be returned.

Executing a Scan

A scan is executed using Scan#foreach. The method returns a RecordStream which emits a data event for each record returned by the scan. The scan can be aborted at any time by calling RecordStream#abort.

Executing Record UDFs using Background Scans

Record UDFs perform operations on a single record such as updating records based on a set of parameters. Using Scan#background you can run a Record UDF on the result set of a scan. Scans using Records UDFs are run in the background on the server and do not return the records to the client.

For additional information please refer to the section on ⇑Record UDFs in the Aerospike technical documentation.


new Scan(client, ns, set [, options])

Parameters:
Name Type Argument Description
client Client

A client instance.

ns string

The namescape.

set string

The name of a set.

options object <optional>

Scan parameters.

Properties
Name Type Argument Default Description
select Array.<string> <optional>

List of bin names to select. See Scan#select.

priority number <optional>

Priority level at which the scan will be executed. See Scan#priority.

percent number <optional>
100

Percentage of records to scan. See Scan#percent.

nobins boolean <optional>
false

Whether only meta data should be returned. See Scan#nobins.

concurrent boolean <optional>
false

Whether all cluster nodes should be scanned concurrently. See Scan#concurrent.

Since:
  • v2.0
Source:
See:
Example
const Aerospike = require('aerospike')

Aerospike.connect((error, client) => {
  if (error) throw error

  var scan = client.scan('test', 'demo')
  scan.priority = Aerospike.scanPriority.LOW
  scan.percent = 50 // scan only 50% of all records in the set

  var recordsSeen = 0
  var stream = scan.foreach()
  stream.on('error', (error) => { throw error })
  stream.on('end', () => client.close())
  stream.on('data', (record) => {
    console.log(record)
    recordsSeen++
    if (recordsSeen > 100) stream.abort() // We've seen enough!
  })
})

Members


concurrent :boolean

If set to true, all cluster nodes will be scanned in parallel.

Type:
  • boolean
Source:

nobins :boolean

If set to true, the scan will return only meta data, and exclude bins.

Type:
  • boolean
Source:

ns :string

Namespace to scan.

Type:
  • string
Source:

percent :number

Percentage of records in the cluster to scan.

Type:
  • number
Source:

priority :number

Priority level at which the scan will be executed.

Type:
  • number
Source:
See:

selected :Array.<string>

List of bin names to be selected by the scan. If a scan specifies bins to be selected, then only those bins will be returned. If no bins are selected, then all bins will be returned (unless Scan#nobins is set to true).

Type:
  • Array.<string>
Source:
See:

set :string

Name of the set to scan.

Type:
  • string
Source:

Methods


background(udfModule, udfFunction [, udfArgs] [, policy] [, scanID] [, callback])

Perform a read-write background scan and apply a Lua user-defined function (UDF) to each record.

When a background scan is initiated, the client will not wait for results from the database. Instead a Job instance will be returned, which can be used to query the scan status on the database.

Parameters:
Name Type Argument Description
udfModule string

UDF module name.

udfFunction string

UDF function name.

udfArgs Array.<*> <optional>

Arguments for the function.

policy ScanPolicy <optional>

The Scan Policy to use for this operation.

scanID number <optional>

Job ID to use for the scan; will be assigned randomly if zero or undefined.

callback jobCallback <optional>

The function to call when the operation completes.

Source:
Returns:

If no callback function is passed, the function returns a Promise that resolves to a Job instance.

Type
Promise

foreach( [policy])

Performs a read-only scan on each node in the cluster. As the scan iterates through each partition, it returns the current version of each record to the client.

Parameters:
Name Type Argument Description
policy ScanPolicy <optional>

The Scan Policy to use for this operation.

Source:
Returns:
Type
RecordStream

operate(operations [, policy] [, scanID] [, callback])

Applies write operations to all matching records.

Performs a background scan and applies one or more write operations to all records. Neither the records nor the results of the operations are returned to the client. Instead a Job instance will be returned, which can be used to query the scan status.

This method requires Aerospike Server version >= 3.7.0.

Parameters:
Name Type Argument Description
operations Array.<module:aerospike/operations~Operation>

List of write operations to perform on the matching records.

policy ScanPolicy <optional>

The Scan Policy to use for this operation.

scanID number <optional>

Job ID to use for the scan; will be assigned randomly if zero or undefined.

callback jobCallback <optional>

The function to call when the operation completes.

Since:
  • v3.14.0
Source:
Returns:

If no callback function is passed, the function returns a Promise that resolves to a Job instance.

Type
Promise
Example

Increment count bin on all records in set using a background scan

const Aerospike = require('aerospike')

Aerospike.connect().then(async (client) => {
  const scan = client.scan('namespace', 'set')
  const ops = [Aerospike.operations.incr('count', 1)]
  const job = await scan.operate(ops)
  await job.waitUntilDone()
  client.close()
})

select(bins)

Specify the names of bins to be selected by the scan.

If a scan specifies bins to be selected, then only those bins will be returned. If no bins are selected, then all bins will be returned. (Unless Scan#nobins is set to true.)

Parameters:
Name Type Argument Description
bins string <repeatable>

List of bin names to return.

Source: