js-data Class: Query

new Query(collection)

A class used by the Collection class to build queries to be executed against the collection's data. An instance of Query is returned by Collection#query. Query instances are typically short-lived, and you shouldn't have to create them yourself. Just use Collection#query.

import {Query} from 'js-data'

Method parameters:

Name	Type	Description
`collection`	Collection	The collection on which this query operates.

Details

Since	Source
3.0.0	Query.js, line 25

        Example
      
    const posts = store.query('post').filter({ status: 'draft' }).limit(2).run()

Extends

This class extends the Component class.

Members

<static> ops

The filtering operators supported by Query#filter, and which are implemented by adapters (for the most part).

Details

Type	Since	Source
Object	3.0.0	Query.js, line 630

Properties:

Name	Type	Description
`==`	Function	Equality operator.
`!=`	Function	Inequality operator.
`>`	Function	Greater than operator.
`>=`	Function	Greater than (inclusive) operator.
`<`	Function	Less than operator.
`<=`	Function	Less than (inclusive) operator.
`isectEmpty`	Function	Operator that asserts that the intersection between two arrays is empty.
`isectNotEmpty`	Function	Operator that asserts that the intersection between two arrays is not empty.
`in`	Function	Operator that asserts whether a value is in an array.
`notIn`	Function	Operator that asserts whether a value is not in an array.
`contains`	Function	Operator that asserts whether an array contains a value.
`notContains`	Function	Operator that asserts whether an array does not contain a value.

Examples

Variant 1

const publishedPosts = store.filter('post', {
  status: 'published',
  limit: 2
})

Variant 2

const publishedPosts = store.filter('post', {
  where: {
    status: {
      '==': 'published'
    }
  },
  limit: 2
})

Variant 3

const publishedPosts = store.query('post').filter({
  status: 'published'
}).limit(2).run()

Variant 4

const publishedPosts = store.query('post').filter({
  where: {
    status: {
      '==': 'published'
    }
  }
}).limit(2).run()

Multiple operators

const myPublishedPosts = store.filter('post', {
  where: {
    status: {
      '==': 'published'
    },
    user_id: {
      '==': currentUser.id
    }
  }
})

_listeners

Event listeners attached to this Component. Do not modify. Use Component#on and Component#off instead.

Details

Type	Since	Source
Object	3.0.0	Component.js, line 7

Inherited From:

Component#_listeners

collection

The Collection on which this query operates.

Details

Type	Since	Source
Collection	3.0.0	Query.js, line 48

data

The current data result of this query.

Details

Type	Since	Source
Array	3.0.0	Query.js, line 57

Methods

<static> extend(props, classProps)

Create a subclass of this Query.

Method parameters:

Name	Type	Argument	Default	Description
`props`	Object	<optional>	{}	Properties to add to the prototype of the subclass.
`classProps`	Object	<optional>	{}	Static properties to add to the subclass.

Return value:

Type	Description
Constructor	Subclass of this Query.

Details

Since	Source
3.0.0	Query.js, line 744

Examples

Extend the class in a cross-browser manner.

import {Query} from 'js-data'
const CustomQueryClass = Query.extend({
  foo () { return 'bar' }
})
const customQuery = new CustomQueryClass({ name: 'test' })
console.log(customQuery.foo()) // "bar"

Extend the class using ES2015 class syntax.

class CustomQueryClass extends Query {
  foo () { return 'bar' }
}
const customQuery = new CustomQueryClass({ name: 'test' })
console.log(customQuery.foo()) // "bar"

between(leftKeys, rightKeys, opts)

Find all entities between two boundaries.

Method parameters:

Name Type Argument Description

leftKeys

Array

Keys defining the left boundary.

rightKeys

Array

Keys defining the right boundary.

opts

Object

Configuration options.

Properties

Name	Type	Argument	Default	Description
`index`	String	<optional>		Name of the secondary index to use in the query. If no index is specified, the main index is used.
`leftInclusive`	Boolean	<optional>	true	Whether to include entities on the left boundary.
`rightInclusive`	Boolean	<optional>	false	Whether to include entities on the left boundary.
`limit`	Boolean	<optional>		Limit the result to a certain number.
`offset`	Boolean	<optional>		The number of resulting entities to skip.

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 67

Examples

Get the users ages 18 to 30.

const users = query.between(18, 30, { index: 'age' }).run()

Same as above.

const users = query.between([18], [30], { index: 'age' }).run()

compare(orderBy, index, a, b)

The comparison function used by the Query class.

Method parameters:

Name	Type	Description
`orderBy`	Array	An orderBy clause used for sorting and sub-sorting.
`index`	Number	The index of the current orderBy clause being used.
`a`	*	The first item in the comparison.
`b`	*	The second item in the comparison.

Return value:

Type	Description
Number	-1 if `b` should preceed `a`. 0 if `a` and `b` are equal. 1 if `a` should preceed `b`.

Details

Since	Source
3.0.0	Query.js, line 101

dbg(args)

Log the provided values at the "debug" level.

Method parameters:

Name	Type	Argument	Description
`args`	*	<optional> <repeatable>	Values to log.

Details

Since	Source
3.0.0	Component.js, line 32

Inherited From:

Component#dbg

emit(event, args)

Trigger an event on this Component.

Method parameters:

Name	Type	Argument	Description
`event`	String		Name of event to emit.
`args`	*	<optional> <repeatable>	Arguments to pass to any listeners.

Details

Since	Source
3.0.0	Component.js, line 98

Inherited From:

Component#emit

        Examples
      
    collection.on('foo', (msg) => {
  console.log(msg) // "bar"
})
collection.emit('foo', 'bar')

    store.on('foo', (msg, val1, val2) => {
  console.log(msg, val1, val2) // "bar" "beep" "boop"
})
store.emit('foo', 'bar', 'beep', 'boop')

evaluate(value, op, predicate)

Predicate evaluation function used by the Query class.

Method parameters:

Name	Type	Description
`value`	*	The value to evaluate.
`op`	String	The operator to use in this evaluation.
`predicate`	*	The predicate to use in this evaluation.

Return value:

Type	Description
Boolean	Whether the value passed the evaluation or not.

Details

Since	Source
3.0.0	Query.js, line 147

filter(queryOrFn, thisArg)

Find the record or records that match the provided query or are accepted by the provided filter function.

Method parameters:

Name	Type	Argument	Default	Description
`queryOrFn`	Object \| Function	<optional>	{}	Selection query or filter function.
`thisArg`	Function	<optional>		Context to which to bind `queryOrFn` if `queryOrFn` is a function.

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 169

Examples

Get the draft posts created less than three months

const posts = query.filter({
  where: {
    status: {
      '==': 'draft'
    },
    created_at_timestamp: {
      '>=': (new Date().getTime() (1000 * 60 * 60 * 24 * 30 * 3)) // 3 months ago
    }
  }
}).run()

Use a custom filter function

const posts = query.filter(function (post) {
  return post.isReady()
}).run()

forEach(forEachFn, thisArg)

Iterate over all entities.

Method parameters:

Name	Type	Argument	Description
`forEachFn`	Function		Iteration function.
`thisArg`	*	<optional>	Context to which to bind `forEachFn`.

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 403

get(keyList, opts)

Find the entity or entities that match the provided key.

Method parameters:

Name Type Argument Description

keyList

Array

Key(s) defining the entity to retrieve. If keyList is not an array (i.e. for a single-value key), it will be wrapped in an array.

opts

Object

Configuration options.

Properties

Name	Type	Argument	Description
`string`	String	<optional>	Name of the secondary index to use in the query. If no index is specified, the main index is used.

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 417

Examples

Get the entity whose primary key is 25.

const entities = query.get(25).run()

Same as above.

const entities = query.get([25]).run()

Get all users who are active and have the "admin" role.

const activeAdmins = query.get(['active', 'admin'], {
  index: 'activityAndRoles'
}).run()

Get all entities that match a certain weather condition.

const niceDays = query.get(['sunny', 'humid', 'calm'], {
  index: 'weatherConditions'
}).run()

getAll(keyList, opts)

Find the entity or entities that match the provided keyLists.

Method parameters:

Name Type Argument Description

keyList

Array

Provide one or more keyLists, and all entities matching each keyList will be retrieved. If no keyLists are provided, all entities will be returned.

opts

Object

Configuration options.

Properties

Name	Type	Argument	Description
`index`	String	<optional>	Name of the secondary index to use in the query. If no index is specified, the main index is used.

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 464

Examples

Get the posts where "status" is "draft" or "inReview".

const posts = query.getAll('draft', 'inReview', { index: 'status' }).run()

Same as above.

const posts = query.getAll(['draft'], ['inReview'], { index: 'status' }).run()

getData()

Return the current data result of this query.

Return value:

Type	Description
Array	The data in this query.

Details

Since	Source
3.0.0	Query.js, line 505

like(pattern, flags)

Implementation used by the like operator. Takes a pattern and flags and returns a RegExp instance that can test strings.

Method parameters:

Name	Type	Description
`pattern`	String	Testing pattern.
`flags`	String	Flags for the regular expression.

Return value:

Type	Description
RegExp	Regular expression for testing strings.

Details

Since	Source
3.0.0	Query.js, line 520

limit(num)

Limit the result.

Method parameters:

Name	Type	Description
`num`	Number	The maximum number of entities to keep in the result.

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 534

Example

Get only the first 10 draft posts.

const posts = query.get('draft', { index: 'status' }).limit(10).run()

log(level, args)

Log the provided values. By default sends values to console[level].

Method parameters:

Name	Type	Argument	Description
`level`	String		Log level
`args`	*	<optional> <repeatable>	Values to log.

Details

Since	Source
3.0.0	Component.js, line 39

Inherited From:

Component#log

map(mapFn, thisArg)

Apply a mapping function to the result data.

Method parameters:

Name	Type	Argument	Description
`mapFn`	Function		Mapping function.
`thisArg`	*	<optional>	Context to which to bind `mapFn`.

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 554

        Example
      
    const ages = UserCollection.query().map((user) => {
  return user.age
}).run()

mapCall(funcName)

Return the result of calling the specified function on each item in this collection's main index.

Method parameters:

Name	Type	Description
`funcName`	String	Name of function to call

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 573

        Example
      
    const stringAges = UserCollection.query().mapCall('toString').run()

off(event, listener)

Remove an event listener from this Component. If no listener is provided, then all listeners for the specified event will be removed. If no event is specified then all listeners for all events will be removed.

Method parameters:

Name	Type	Argument	Description
`event`	String	<optional>	Name of event to unsubsribe to.
`listener`	Function	<optional>	Listener to remove.

Details

Since	Source
3.0.0	Component.js, line 79

Inherited From:

Component#off

Examples

Remove a listener to a single event

collection.off('add', handler)

Remove all listeners to a single event

record.off('change')

Remove all listeners to all events

store.off()

on(event, listener, ctx)

Method parameters:

Name	Type	Argument	Description
`event`	String		Name of event to subsribe to.
`listener`	Function		Listener function to handle the event.
`ctx`	*	<optional>	Optional content in which to invoke the listener.

Details

Since	Source
3.0.0	Component.js, line 49

Inherited From:

Component#on

Examples

Listen for all "afterCreate" events in a DataStore

store.on('afterCreate', (mapperName, props, opts, result) => {
  console.log(mapperName) // "post"
  console.log(props.id) // undefined
  console.log(result.id) // 1234
})
store.create('post', { title: 'Modeling your data' }).then((post) => {
  console.log(post.id) // 1234
})

Listen for the "add" event on a collection

collection.on('add', (records) => {
  console.log(records) // [...]
})

Listen for "change" events on a record

post.on('change', (record, changes) => {
  console.log(changes) // { changed: { title: 'Modeling your data' } }
})
post.title = 'Modeling your data'

run()

Complete the execution of the query and return the resulting data.

Return value:

Type	Description
Array	The result of executing this query.

Details

Since	Source
3.0.0	Query.js, line 593

skip(num)

Skip a number of results.

Method parameters:

Name	Type	Description
`num`	Number	The number of entities to skip.

Return value:

Type	Description
Query	A reference to itself for chaining.

Details

Since	Source
3.0.0	Query.js, line 606

Example

Get all but the first 10 draft posts.

const posts = query.get('draft', { index: 'status' }).skip(10).run()

Class: Query

new Query(collection)

Extends

Members

<static> ops

Properties:

_listeners

collection

data

Methods

<static> extend(props, classProps)

between(leftKeys, rightKeys, opts)

Properties

compare(orderBy, index, a, b)

dbg(args)

emit(event, args)

evaluate(value, op, predicate)

filter(queryOrFn, thisArg)

forEach(forEachFn, thisArg)

get(keyList, opts)

Properties

getAll(keyList, opts)

Properties

getData()

like(pattern, flags)

limit(num)

log(level, args)

map(mapFn, thisArg)

mapCall(funcName)

off(event, listener)

on(event, listener, ctx)

run()

skip(num)

Search results