Aerospike

Class: Query

Query

Aerospike Query operations perform value-based searches using secondary indexes (SI). 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.

SI Filters

With a SI, 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 SI needs to be created on the bins which the predicate matches on. Using the Node.js client, a SI can be created using Client#createIndex.

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

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

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.<object>
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:

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 QueryaggregationResultCallback <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 WritePolicy <optional>

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

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.
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] [, 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 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 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()
})

partitions(begin, count, digest)

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

If a Query 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:

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

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 SI to the query.

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

Parameters:
Name Type Description
predicate module:aerospike/filter~SindexFilterPredicate

The filter to apply to the function.
Source:
See:
  • module:aerospike/filter to create SI filters. 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()) })
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())
})