Class: Query

Query

Aerospike Query operations perform value-based searches using secondary indexes. A Query object, created by calling Client#query, is used to execute queries on the specified namespace and set (optional). Queries can return a set of records as a RecordStream or be processed using Aeorspike User-Defined Functions (UDFs) before returning to the client.

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

To scan all records in a database namespace or set, it is more efficient to use operations, which provide more fine-grained control over execution priority, concurrency, etc.

Secondary Index Filters

With a secondary index, the following queries can be made:

See module:aerospike/filter for a list of all supported secondary index filter predicates.

Before a filter predicate can be applied, a secondary index needs to be created on the bins which the predicate matches on. Using the Node.js client, a secondary index can be created using Client#createIndex.

Currently, only a single secondary index filter predicate is supported for each query. To do more advanced filtering, a predicate expression can be applied to the query (see below). Alternatively, User-Defined Functions (UDFs) can be used to further process the query results on the server.

Predicate Filter Expressions

Using Aerospike Predicate Filtering (Aerospike server version 3.12 and later), you can:

  • Filter out records based on record meta data, such as last-update-time or storage-size.
  • Filter out records based on bin data, such as integer greater/less or regexp on string bins.

Predicate filter expressions can be combined with a secondary index filter.

See module:aerospike/predexp for a list of supported predicate expressions.

For more information about Predicate Filtering, please refer to the ⇑Predicate Filtering documentation in the Aerospike Feature Guide.

Selecting Bins

Using Query#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 Query#nobins property is set to true the only the record meta data (ttl, generation, etc.) will be returned.

Executing a Query

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

Applying User-Defined Functions

User-defined functions (UDFs) can be used to filter, transform, and aggregate query results. Stream UDFs can process a stream of data by defining a sequence of operations to perform. Stream UDFs perform read-only operations on a collection of records. Use Query#setUdf to set the UDF parameters (module name, function name and optional list of arguments) before executing the query using Query#foreach.

The feature guides on ⇑User-Defined Functions and ⇑Stream UDFs contain more detailed information and examples.

Query Aggregation using Stream UDFs

Use Aerospike Stream UDFs to aggregate query results using Query#apply. Aggregation queries work similar to a MapReduce system and return a single result value instead of stream of records. Aggregation results can be basic data types (string, number, byte array) or collection types (list, map).

Please refer to the technical documentation on ⇑Aggregation for more information.

Executing Record UDFs using Background Queries

Record UDFs perform operations on a single record such as updating records based on a set of parameters. Using Query#background you can run a Record UDF on the result set of a query. Queries 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 Query(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>

Query parameters.

Properties
Name Type Argument Default Description
filters Array.<FilterPredicate> <optional>

List of filter predicates to apply to the query. See Query#where.

select Array.<string> <optional>

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

nobins boolean <optional>
false

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

Source:
See:
Example
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')
      query.select('id', 'tags')
      query.where(Aerospike.filter.contains('tags', 'green', Aerospike.indexType.LIST))
      var stream = query.foreach()
      stream.on('error', (error) => {
        console.error(error)
        throw error
      })
      stream.on('data', (record) => {
        console.info(record)
      })
      stream.on('end', () => {
        client.close()
      })
    })
  })
})

Members


filters :Array.<FilterPredicate>

Filters to apply to the query.

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

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

nobins :boolean

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

Type:
  • boolean
Source:

ns :string

Namespace to query.

Type:
  • string
Source:

predexp :Array.<Predicate>

Sequence (array) of predicate expressions to apply to the query.

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

selected :Array.<string>

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).

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

set :string

Name of the set to query.

Type:
  • string
Source:

udf :Object

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

Type:
  • Object
Source:

Methods


apply(udfModule, udfFunction [, udfArgs] [, policy] [, callback])

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

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.

Parameters:
Name Type Argument Description
udfModule string

UDF module name.

udfFunction string

UDF function name.

udfArgs Array.<*> <optional>

Arguments for the function.

policy QueryPolicy <optional>

The Query Policy to use for this operation.

callback Query~aggregationResultCallback <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 the aggregation results.

Type
Promise

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

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

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.

Parameters:
Name Type Argument Description
udfModule string

UDF module name.

udfFunction string

UDF function name.

udfArgs Array.<*> <optional>

Arguments for the function.

policy QueryPolicy <optional>

The Query Policy to use for this operation.

queryID number <optional>

Job ID to use for the query; 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])

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

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.

Parameters:
Name Type Argument Description
policy QueryPolicy <optional>

The Query Policy to use for this operation.

Source:
Returns:
Type
RecordStream

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

Applies write operations to all matching records.

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 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 QueryPolicy <optional>

The Query Policy to use for this operation.

queryID number <optional>

Job ID to use for the query; 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 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()
})

results( [policy])

Executes the query and collects the results into an array.

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.

Parameters:
Name Type Argument Description
policy QueryPolicy <optional>

The Query Policy to use for this operation.

Source:
Returns:
Type
Promise.<Array.<Record>>

select(bins)

Specify the names of bins 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.)

Parameters:
Name Type Argument Description
bins string <repeatable>

List of bin names to return.

Source:

setUdf(udfModule, udfFunction [, udfArgs])

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

Parameters:
Name Type Argument Description
udfModule string

UDF module name.

udfFunction string

UDF function name.

udfArgs Array.<*> <optional>

Arguments for the function.

Source:

where(predicate)

Applies a secondary index filter and/or a predicate expression to the query.

Use a secondary index filter, a predicate expression, or both, to limit the results returned by the query. This method takes either a secondary index filter created using the filter module, or a sequence of predicate expressions created using the predexp module as argument. It can also be called multiple times to add both kinds of filters to the same query. (Max. one of each kind.)

Parameters:
Name Type Description
predicate module:aerospike/filter~SindexFilterPredicate | Array.<module:aerospike/predexp~PredicateExpression>

The filter to apply to the function.

Source:
See:
Examples

Applying a secondary index 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())
})

Applying a predicate expression in addition to a secondary index filter to find only record where the 'tags' list bin contains the value 'blue' but also contains at least one other value that is not 'blue':

const Aerospike = require('aerospike')
const predexp = Aerospike.predexp

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

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

  let tagsPredexp = [
    predexp.stringVar('tag'),
    predexp.stringValue('blue'),
    predexp.stringEqual(),
    predexp.listBin('tags'),
    predexp.listIterateAnd('tag'),
    predexp.not()
  ]
  query.where(tagsPredexp)

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

Type Definitions


aggregationResultCallback(error [, result])

Callback function returning the aggregation result for a query.

If the operation was successful, null will be returned for the error parameter. If there was an error, result will be undefined and the error paramter will provide more information about the error.

Parameters:
Name Type Argument Description
error AerospikeError <nullable>

The error code and message or null if the operation was successful.

result number | string | Array.<*> | Object <optional>

The aggregation result.

Source: