Class Query

Aerospike Query commands 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 Scan.operate, which provide more fine-grained control over execution priority, concurrency, etc.

SI Filters

With a SI, the following queries can be made:

[Equal query]filter.equal against string or numeric indexes
[Range query]filter.range against numeric indexes
[Point-In-Region query]filter.geoWithinGeoJSONRegion or [Region-Contain-Point query]filter.geoContainsGeoJSONPoint against geo indexes

See filter for a list of all supported secondary index filter.

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

Currently, only a single SI index filter 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.

Previously, predicate filtering was used to perform secondary index queries. SI filter predicates have been deprecated since server 5.2, and obsolete since server 6.0.

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.

Query pagination

Query pagination allows for queries return records in pages rather than all at once. To enable query pagination, the query property paginate must be true and the previously stated query property Query.maxRecords must be set to a nonzero positive integer in order to specify a maximum page size.

When a page is complete, RecordStream event 'error' will emit a Query#queryState object containing a serialized version of the query. This serialized query, if be assigned back to Query#queryState, allows the query to retrieve the next page of records in the query upon calling Query#foreach. If Query#queryState is undefined, pagination is not enabled or the query has completed. If 'error' emits an undefined object, either paginate is not true, or the query has successfully returned all the specified records.

For additional information and examples, please refer to the paginate section below.

See

Client#query to create new instances of this class.

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()
      })
    })
  })
})

Index

Constructors

constructor

new Query(client, ns, set, options?): Query
Construct a Query instance.
Parameters
- client: Client
  A client instance.
- ns: string
  The namescape.
- set: string
  The name of a set.
- Optionaloptions: null | QueryOptions
  Query options. *
Returns Query
- Defined in typings/index.d.ts:1191

Properties

client

client: Client

Aerospike Client Instance

filters

filters: SindexFilterPredicate[]

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.

`Optional`maxRecords

maxRecords?: number

Approximate number of records to return to client.

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

nobins

nobins: boolean

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

ns

ns: string

Namespace to query.

`Optional`ops

ops?: Operation[]

Specifies operations to be executed when operate is called.

`Optional`paginate

paginate?: boolean

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

Example: Asynchronous pagination over a set of thirty records with {@link 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()
  }
})()

Example: Asynchronous pagination over a set of thirty records with {@link 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()
  }
})()

`Optional`partFilter

partFilter?: PartFilter

Used when querying partitions to manage the query. For internal use only.

`Optional`pfEnabled

pfEnabled?: boolean

If set to true, the query will return records belonging to the partitions specified in Query#partFilter.

`Optional`queryState

queryState?: number[]

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.

selected

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

set

set: string

Name of the set to query.

ttl

ttl: number

The time-to-live (expiration) of the record in seconds.

There are also special values that can be set in the record TTL For details

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

udf

udf: UDF

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

Methods

apply

apply(udfModule, udfFunction, udfArgs?, policy?): Promise<AerospikeBinValue>
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
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- OptionaludfArgs: null | AerospikeBinValue[]
  Arguments for the function.
- Optionalpolicy: null | policy.QueryPolicy
  The Query Policy to use for this command.
Returns Promise<AerospikeBinValue>
A promise that resolves with an Aerospike bin value.
- Defined in typings/index.d.ts:1342
apply(udfModule, udfFunction, callback): void
Parameters
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- callback: TypedCallback<AerospikeBinValue>
  The function to call when the command completes.
Returns void
- Defined in typings/index.d.ts:1349
apply(udfModule, udfFunction, udfArgs?, callback?): void
Parameters
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- OptionaludfArgs: null | AerospikeBinValue[]
  Arguments for the function.
- Optionalcallback: TypedCallback<AerospikeBinValue>
  The function to call when the command completes.
Returns void
- Defined in typings/index.d.ts:1357
apply(udfModule, udfFunction, udfArgs?, policy?, callback?): void
Parameters
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- OptionaludfArgs: AerospikeBinValue[]
  Arguments for the function.
- Optionalpolicy: null | policy.QueryPolicy
  The Query Policy to use for this command.
- Optionalcallback: TypedCallback<AerospikeBinValue>
  The function to call when the command completes.
Returns void
- Defined in typings/index.d.ts:1366

background

background(udfModule, udfFunction, udfArgs?, policy?, queryID?): Promise<Job<JobInfoResponse>>
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
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- OptionaludfArgs: null | AerospikeBinValue[]
  Arguments for the function.
- Optionalpolicy: null | policy.WritePolicy
  The Write Policy to use for this command.
- OptionalqueryID: null | number
  Job ID to use for the query; will be assigned randomly if zero or undefined.
Returns Promise<Job<JobInfoResponse>>
Promise that resolves to a Job instance.
- Defined in typings/index.d.ts:1384
background(udfModule, udfFunction, callback): void
Parameters
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- callback: TypedCallback<Job<JobInfoResponse>>
  The function to call when the command completes.
Returns void
- Defined in typings/index.d.ts:1391
background(udfModule, udfFunction, udfArgs?, callback?): void
Parameters
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- OptionaludfArgs: null | AerospikeBinValue[]
  Arguments for the function.
- Optionalcallback: TypedCallback<Job<JobInfoResponse>>
  The function to call when the command completes.
Returns void
- Defined in typings/index.d.ts:1399
background(udfModule, udfFunction, udfArgs?, policy?, callback?): void
Parameters
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- OptionaludfArgs: null | AerospikeBinValue[]
  Arguments for the function.
- Optionalpolicy: null | policy.WritePolicy
  The Write Policy to use for this command.
- Optionalcallback: TypedCallback<Job<JobInfoResponse>>
  The function to call when the command completes.
Returns void
- Defined in typings/index.d.ts:1408
background(udfModule, udfFunction, udfArgs?, policy?, queryID?, callback?): void
Parameters
- udfModule: string
  UDF module name.
- udfFunction: string
  UDF function name.
- OptionaludfArgs: null | AerospikeBinValue[]
  Arguments for the function.
- Optionalpolicy: null | policy.WritePolicy
  The Write Policy to use for this command.
- OptionalqueryID: null | number
  Job ID to use for the query; will be assigned randomly if zero or undefined.
- Optionalcallback: null | TypedCallback<Job<JobInfoResponse>>
  The function to call when the command completes.
Returns void
- Defined in typings/index.d.ts:1419

foreach

foreach(policy?, dataCb?, errorCb?, endCb?): RecordStream
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
- Optionalpolicy: null | policy.QueryPolicy
  The Query Policy to use for this command.
- OptionaldataCb: ((data: AerospikeRecord) => void)
  The function to call when the command completes with the results of the command; if no callback function is provided, the method returns a Promise instead.
  - - (data): void
    - Parameters
      data: AerospikeRecord
      Returns void
- OptionalerrorCb: ((error: Error) => void)Callback function called when there is an error. (error): void Parameters error: Error Returns void
- OptionalendCb: (() => void)Callback function called when an operation has completed. (): void Returns void
Returns RecordStream
RecordStream
Defined in typings/index.d.ts:1307

hasNextPage
hasNextPage(): boolean
Checks compiliation status of a paginated query.
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.
Returns boolean
true if another page remains.
Defined in typings/index.d.ts:1201

nextPage
nextPage(state): void
Sets Query#queryState to the value specified by the state argument.
setter function for the Query#queryState member variable.
Parameters
state: number[]serialized query emitted from the 'error' event.
Returns void
Defined in typings/index.d.ts:1209

operate
operate(operations, policy?, queryID?): Promise<Job<JobInfoResponse>>
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
operations: Operation[]List of write
operations to perform on the matching records.
Optionalpolicy: null | policy.QueryPolicyThe Query Policy to use for this command.
OptionalqueryID: null | numberJob ID to use for the query; will be assigned
randomly if zero or undefined.
Returns Promise<Job<JobInfoResponse>>
Promise that resolves to a Job instance.
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()
})


Defined in typings/index.d.ts:1454
operate(operations, callback?): void
Parameters
operations: Operation[]List of write
operations to perform on the matching records.
Optionalcallback: TypedCallback<Job<JobInfoResponse>>The function to call when the command completes.
Returns void
Promise that resolves to a Job instance.
Defined in typings/index.d.ts:1462
operate(operations, policy, callback?): void
Parameters
operations: Operation[]List of write
operations to perform on the matching records.
policy: null | policy.QueryPolicyThe Query Policy to use for this command.
Optionalcallback: TypedCallback<Job<JobInfoResponse>>The function to call when the command completes.
Returns void
Promise that resolves to a Job instance.
Defined in typings/index.d.ts:1471
operate(operations, policy, queryID, callback?): void
Parameters
operations: Operation[]List of write
operations to perform on the matching records.
policy: null | policy.QueryPolicyThe Query Policy to use for this command.
queryID: null | numberJob ID to use for the query; will be assigned
randomly if zero or undefined.
Optionalcallback: TypedCallback<Job<JobInfoResponse>>The function to call when the command completes.
Returns void
Promise that resolves to a Job instance.
Defined in typings/index.d.ts:1482

partitions
partitions(begin, count, digest?): void
Specify the begin and count of the partitions
to be queried by the Query foreach op.
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.
Parameters
begin: numberStart partition number to query.
count: numberNumber of partitions from the start to query.
Optionaldigest: null | BufferStart from this digest if it is specified.
Returns void
Defined in typings/index.d.ts:1223

results
results(policy?): Promise<AerospikeRecord[]>
Executes the query and collects the results into an array. On paginated queries,
preparing the next page is also handled automatically.
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 '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.
Parameters
Optionalpolicy: null | policy.QueryPolicyThe Query Policy to use for this command.
Returns Promise<AerospikeRecord[]>
A promise that resolves with an Aerospike Record.
Defined in typings/index.d.ts:1328

select
select(bins): void
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
bins: string[]List of bin names or multiple bin names to return.
Returns void
Defined in typings/index.d.ts:1234
select(...bins): void
Parameters
Rest...bins: string[]A spread of bin names to return.
Returns void
Defined in typings/index.d.ts:1240

setUdf
setUdf(udfModule, udfFunction, udfArgs?): void
Set user-defined function parameters to be applied to the query.
Parameters
udfModule: stringUDF module name.
udfFunction: stringUDF function name.
OptionaludfArgs: null | AerospikeBinValue[]Arguments for the function.
Returns void
Defined in typings/index.d.ts:1280

where
where(predicate): void
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
predicate: SindexFilterPredicateThe index filter to
apply to the function.
Returns void
Example
<caption>Applying a SI filter to find all records
where the 'tags' list bin contains the value 'blue':</caption>

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())
})


See
filter to create SI filters.
Defined in typings/index.d.ts:1270

Class Query

SI Filters

Selecting Bins

Executing a Query

Applying User-Defined Functions

Query Aggregation using Stream UDFs

Executing Record UDFs using Background Queries

Query pagination

See

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Query

Properties

client

filters

OptionalmaxRecords

nobins

ns

Optionalops

Optionalpaginate

Example: Asynchronous pagination over a set of thirty records with {@link Query#foreach}.

Example: Asynchronous pagination over a set of thirty records with {@link Query#results}

OptionalpartFilter

OptionalpfEnabled

OptionalqueryState

selected

set

ttl

udf

Methods

apply

Parameters

Returns Promise<AerospikeBinValue>

Parameters

Returns void

Parameters

Returns void

Parameters

Returns void

background

Parameters

Returns Promise<Job<JobInfoResponse>>

Parameters

Returns void

Parameters

Returns void

Parameters

Returns void

Parameters

Returns void

foreach

Parameters

Parameters

Returns void

Parameters

Returns void

Returns void

Returns RecordStream

hasNextPage

Returns boolean

nextPage

Parameters

Returns void

operate

Parameters

Returns Promise<Job<JobInfoResponse>>

Since

Example: Increment count bin on all matching records using a background query

Parameters

Returns void

Parameters

Returns void

Parameters

Returns void

`Optional`maxRecords

`Optional`ops

`Optional`paginate

`Optional`partFilter

`Optional`pfEnabled

`Optional`queryState

`Parameters`

`Returns void`

`Returns RecordStream`

`Settings`

`On This Page`