Aerospike

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.

Scan is depricated in server 6.0. Use Query methods implemented by Client#query 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.
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
Deprecated:
  • since server 6.0
Source:
See:
Example
const Aerospike = require('aerospike')

// INSERT HOSTNAME AND PORT NUMBER OF AEROSPIKE SERVER NODE HERE!
var config = {
  hosts: '192.168.33.10:3000',
  // Timeouts disabled, latency dependent on server location. Configure as needed.
  policies: {
    scan : new Aerospike.ScanPolicy({socketTimeout : 0, totalTimeout : 0}),
   }
}

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

  const scan = client.scan('test', 'demo')
  let recordsSeen = 0
  const 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:

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] [, dataCb] [, errorCb] [, endCb])

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.
dataCb recordCallback <optional>

The function to call when the operation completes with the results of the operation; if no callback function is provided, the method returns a Promise instead.
errorCb errorCallback <optional>

Callback function called when there is an error.
endCb doneCallback <optional>

Callback function called when an operation has completed.
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 server >= 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')

// INSERT HOSTNAME AND PORT NUMBER OF AEROSPIKE SERVER NODE HERE!
var config = {
  hosts: '192.168.33.10:3000',
  // Timeouts disabled, latency dependent on server location. Configure as needed.
  policies: {
    scan : new Aerospike.ScanPolicy({socketTimeout : 0, totalTimeout : 0})
   }
}

Aerospike.connect(config).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()
})

partitions(begin, count, digest)

Specify the begin and count of the partitions to be scanned by the scan foreach op.

If a scan specifies partitions begin and count, then only those partitons will be scanned and returned. If no partitions are specified, then all partitions will be scanned and returned.

Parameters:
Name Type Description
begin number

Start partition number to scan.
count number

Number of partitions from the start to scan.
digest string

Start from this digest if it is specified.
Source:

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: