Query

const Aerospike = require('aerospike')
const namespace = 'test'
const set = 'demo'

Aerospike.connect((error, client) => {
  if (error) throw error
  var index = {
    ns: namespace,
    set: set,
    bin: 'tags',
    index: 'tags_idx',
    type: Aerospike.indexType.LIST,
    datatype: Aerospike.indexDataType.STRING
  }
  client.createIndex(index, (error, job) => {
    if (error) throw error
    job.waitUntilDone((error) => {
      if (error) throw error

      var query = client.query('test', 'demo')
      const queryPolicy = { filterExpression: exp.keyExist('uniqueExpKey') }
      query.select('id', 'tags')
      query.where(Aerospike.filter.contains('tags', 'green', Aerospike.indexType.LIST))
      var stream = query.foreach(queryPolicy)
      stream.on('error', (error) => {
        console.error(error)
        throw error
      })
      stream.on('data', (record) => {
        console.info(record)
      })
      stream.on('end', () => {
        client.close()
      })
    })
  })
})

Members

filters :Array.<object>

Description:

• Filters to apply to the query.

  Note: Currently, a single index filter is supported. To do more advanced filtering, you need to use a user-defined function (UDF) to process the result set on the server.

Source:

• query.js, line 223

See:

• Use Query#where to add index filters to the query.
• Use module:aerospike/filter to create a SI filter.

Type:

• Array.<object>

maxRecords :number

Description:

• Approximate number of records to return to client.

  When query#paginate is true, then maxRecords will be the page size if there are enough records remaining in the query to fill the page size.

  When query#paginate is false, this number is divided by the number of nodes involved in the scan, and actual number of records returned may be less than maxRecords if node record counts are small and unbalanced across nodes.

Source:

• query.js, line 382

Type:

• number

nobins :boolean

Description:

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

Source:

• query.js, line 250

Type:

• boolean

ns :string

Description:

• Namespace to query.

Source:

• query.js, line 211

Type:

• string

paginate :boolean

Description:

• If set to true, paginated queries are enabled. In order to receive paginated results, the query#maxRecords property must assign a nonzero integer value.

Source:

• query.js, line 274

Type:

• boolean

Examples

Asynchronous pagination over a set of thirty records with Query#foreach.

const Aerospike = require('./lib/aerospike');
// Define host configuration
let config = {
  hosts: '34.213.88.142:3000',
  policies: {
    batchWrite : new Aerospike.BatchWritePolicy({socketTimeout : 0, totalTimeout : 0}),
  }
};

var batchRecords = []
for(let i = 0; i < 30; i++){
  batchRecords.push({
    type: Aerospike.batchType;.BATCH_WRITE,
    key: new Aerospike.Key('test', 'demo', 'key' + i),
    ops:[Aerospike.operations.write('exampleBin', i)]
  })
}

;(async function() {
  try {
    client = await Aerospike.connect(config)
    await client.truncate('test', 'demo', 0)
    await client.batchWrite(batchRecords, {socketTimeout : 0, totalTimeout : 0})

    const query = client.query('test', 'demo', { paginate: true, maxRecords: 10})
    do {
      const stream = query.foreach()
      stream.on('error', (error) => { throw error })
      stream.on('data', (record) => {
        console.log(record.bins)
      })
      await new Promise(resolve => {
        stream.on('end', (queryState) => {
          query.queryState = queryState
          resolve()
        })
      })
    } while (query.queryState !== undefined)

  } catch (error) {
    console.error('An error occurred at some point.', error)
    process.exit(1)
  } finally {
    if (client) client.close()
  }
})()

Asynchronous pagination over a set of thirty records with Query#results

const Aerospike = require('./lib/aerospike');
// Define host configuration
let config = {
  hosts: '34.213.88.142:3000',
  policies: {
    batchWrite : new Aerospike.BatchWritePolicy({socketTimeout : 0, totalTimeout : 0}),
  }
};

var batchRecords = []
for(let i = 0; i < 30; i++){
  batchRecords.push({
    type: Aerospike.batchType.BATCH_WRITE,
    key: new Aerospike.Key('test', 'demo', 'key' + i),
    ops:[Aerospike.operations.write('exampleBin', i)]
  })
}


;(async function() {
  try {
    client = await Aerospike.connect(config)
    await client.truncate('test', 'demo', 0)
    await client.batchWrite(batchRecords, {socketTimeout : 0, totalTimeout : 0})

    const query = client.query('test', 'demo', { paginate: true, maxRecords: 11})

    let allResults = []
    let results = await query.results()
    allResults = [...allResults, ...results]


    results = await query.results()
    allResults = [...allResults, ...results]

    results = await query.results()
    allResults = [...allResults, ...results]

    console.log("Records returned in total: " + allResults.length)  // Should be 30 records
  } catch (error) {
    console.error('An error occurred at some point.', error)
    process.exit(1)
  } finally {
    if (client) client.close()
  }
})()

queryState :Object

Description:

• If set to a valid serialized query, calling query#foreach will allow the next page of records to be queried while preserving the progress of the previous query. If set to null, calling query#foreach will begin a new query.

Source:

• query.js, line 394

Type:

• Object

selected :Array.<string>

Description:

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

Source:

• query.js, line 238

See:

• Use Query#select to specify the bins to select.

Type:

• Array.<string>

set :string

Description:

• Name of the set to query.

Source:

• query.js, line 217

Type:

• string

ttl :number

Description:

• The time-to-live (expiration) of the record in seconds. There are also special values that can be set in the record TTL:

  0 (defined Aerospike.ttl.NAMESPACE_DEFAULT), which means that the record will adopt the default TTL value from the namespace.

  -1 (defined Aerospike.ttl.NEVER_EXIRE), which means that the record will get an internal "void_time" of zero, and thus will never expire.

  -2 (defined Aerospike.ttl.DONT_UPDATE), which means that the record ttl will not change when the record is updated.

  Note that the TTL value will be employed ONLY on background query writes.

Source:

• query.js, line 401

Type:

• number

udf :Object

Description:

• User-defined function parameters to be applied to the query executed using Query#foreach.

Source:

• query.js, line 257

Type:

• Object

Methods

apply(udfModule, udfFunction, udfArgsopt, policyopt, callbackopt) → (nullable) {Promise}

Applies a user-defined function (UDF) to aggregate the query results.

Description:

• The aggregation function is called on both server and client (final reduce). Therefore, the Lua script files must also reside on both server and client.

Source:

• query.js, line 645

Parameters:

Returns:

Type

Promise

background(udfModule, udfFunction, udfArgsopt, policyopt, queryIDopt, callbackopt) → (nullable) {Promise}

Applies a user-defined function (UDF) on records that match the query filter. Records are not returned to the client.

Description:

• When a background query 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 query status on the database.

Source:

• query.js, line 680

Parameters:

Returns:

Type

Promise

foreach(policyopt, dataCbopt, errorCbopt, endCbopt) → {RecordStream}

Asynchronously executes the query and returns each result item through the stream.

Description:

• Applying a Stream UDF to the query results

  A stream UDF can be applied to the query to filter, transform and aggregate the query results. The UDF parameters need to be set on the query object using Query#setUdf before the query is executed.

  If a UDF is applied to the query, the resulting stream will return the results of the UDF stream function. Record meta data and the record keys will not be returned.

  For aggregation queries that return a single result value instead of a stream of values, you should use the Query#apply method instead.

Source:

• query.js, line 547

Parameters:

Returns:

Type

RecordStream

hasNextPage() → {boolean}

Checks compiliation status of a paginated query.

Description:

• If false is returned, there are no more records left in the query, and the query is complete. If true is returned, calling Query#foreach will continue from the state specified by Query#queryState.

Source:

• query.js, line 433

Returns:

Type

boolean

nextPage(…state)

Sets query#queryState to the value specified by the state argument.

Description:

• setter function for the Query#queryState member variable.

Source:

• query.js, line 420

Parameters:

operate(operations, policyopt, queryIDopt, callbackopt) → (nullable) {Promise}

Applies write operations to all matching records.

Description:

• Performs a background query and applies one or more write operations to all records that match the query filter(s). 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 query status.

  This method requires server >= 3.7.0.

Source:

• query.js, line 723

Since:

• v3.14.0

Example

Increment count bin on all matching records using a background query

const Aerospike = require('aerospike')

Aerospike.connect().then(async (client) => {
  const query = client.query('namespace', 'set')
  query.where(Aerospike.filter.range('age', 18, 42))
  const ops = [Aerospike.operations.incr('count', 1)]
  const job = await query.operate(ops)
  await job.waitUntilDone()
  client.close()
})

Parameters:

Returns:

Type

Promise

partitions(begin, count, digest)

Specify the begin and count of the partitions to be queried by the Query foreach op.

Description:

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

Source:

• query.js, line 527

Parameters:

results(policyopt) → {Promise.<Array.<RecordObject>>}

Executes the query and collects the results into an array. On paginated queries, preparing the next page is also handled automatically.

Description:

• This method returns a Promise that contains the query results as an array of records, when fulfilled. It should only be used if the query is expected to return only few records; otherwise it is recommended to use Query#foreach, which returns the results as a RecordStream instead.

  If pagination is enabled, the data emitted from the RecordStream#event:error event will automatically be assigned to Query#queryState, allowing the next page of records to be queried if Query#foreach or Query#results is called.

Source:

• query.js, line 610

Parameters:

Returns:

Type

Promise.<Array.<RecordObject>>

select(…bins)

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

Description:

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

Source:

• query.js, line 447

Parameters:

setUdf(udfModule, udfFunction, udfArgsopt)

Set user-defined function parameters to be applied to the query.

Source:

• query.js, line 510

Parameters:

where(index)

Applies a SI to the query.

Description:

• Use a SI to limit the results returned by the query. This method takes SI created using the filter module as argument.

Source:

• query.js, line 466

See:

• module:aerospike/filter to create SI filters.

Example

Applying a SI filter to find all records where the 'tags' list bin contains the value 'blue':

const Aerospike = require('aerospike')

Aerospike.connect().then(client => {
  let query = client.query('test', 'demo')

  let tagsFilter = Aerospike.filter.contains('tags', 'blue', Aerospike.indexType.LIST)
  query.where(tagsFilter)

  let stream = query.foreach()
  stream.on('data', record => { console.info(record.bins.tags) })
  stream.on('error', error => { throw error })
  stream.on('end', () => client.close())
})

Parameters: