

cozy-client / QueryDefinition

Class: QueryDefinition

Chainable API to create query definitions to retrieve documents from a Cozy. QueryDefinitions are sent to links.

Constructors

constructor

• new QueryDefinition(options?)

Parameters

Name	Type	Description
options	Object	Initial options for the query definition
options.bookmark	string	-
options.cursor	CouchDBViewCursor	-
options.doctype	string	-
options.fields	string[]	-
options.id	string	-
options.ids	string[]	-
options.includes	string[]	-
options.indexedFields	string[]	-
options.limit	number	-
options.partialFilter	any	-
options.referenced	string	-
options.selector	any	-
options.sharingId	string	-
options.skip	number	-
options.sort	any[]	-

Defined in

packages/cozy-client/src/queries/dsl.js:51

Properties

bookmark

• bookmark: string

Defined in

packages/cozy-client/src/queries/dsl.js:65

---

cursor

• cursor: CouchDBViewCursor

Defined in

packages/cozy-client/src/queries/dsl.js:64

---

doctype

• doctype: string

Defined in

packages/cozy-client/src/queries/dsl.js:52

---

fields

• fields: string[]

Defined in

packages/cozy-client/src/queries/dsl.js:56

---

id

• id: string

Defined in

packages/cozy-client/src/queries/dsl.js:53

---

ids

• ids: string[]

Defined in

packages/cozy-client/src/queries/dsl.js:54

---

includes

• includes: string[]

Defined in

packages/cozy-client/src/queries/dsl.js:60

---

indexedFields

• indexedFields: string[]

Defined in

packages/cozy-client/src/queries/dsl.js:57

---

limit

• limit: number

Defined in

packages/cozy-client/src/queries/dsl.js:62

---

partialFilter

• partialFilter: any

Defined in

packages/cozy-client/src/queries/dsl.js:58

---

referenced

• referenced: string

Defined in

packages/cozy-client/src/queries/dsl.js:61

---

selector

• selector: any

Defined in

packages/cozy-client/src/queries/dsl.js:55

---

sharingId

• sharingId: string

Defined in

packages/cozy-client/src/queries/dsl.js:66

---

skip

• skip: number

Defined in

packages/cozy-client/src/queries/dsl.js:63

---

sort

• sort: any[]

Defined in

packages/cozy-client/src/queries/dsl.js:59

Methods

UNSAFE_noLimit

▸ UNSAFE_noLimit(): QueryDefinition

Returns

QueryDefinition

Defined in

packages/cozy-client/src/queries/dsl.js:293

---

checkSelectFields

▸ checkSelectFields(obj): void

Check if the selected fields are all included in the selectors

Parameters

Name	Type	Description
obj	PartialQueryDefinition	A partial QueryDefinition to check

Returns

void

Defined in

packages/cozy-client/src/queries/dsl.js:156

---

checkSelector

▸ checkSelector(selector): void

Checks the selector predicates.

It is useful to warn the developer when a partial index might be used.

Parameters

Name	Type	Description
selector	any	The selector definition

Returns

void

Defined in

packages/cozy-client/src/queries/dsl.js:119

---

checkSortOrder

▸ checkSortOrder(obj): void

Checks if the sort order matches the index’ fields order.

When sorting with CouchDB, it is required to:

• use indexed fields
• keep the same order than the indexed fields.

See https://docs.cozy.io/en/tutorials/data/queries/#sort-data-with-mango

Parameters

Name	Type	Description
obj	PartialQueryDefinition	A partial QueryDefinition to check

Returns

void

Defined in

packages/cozy-client/src/queries/dsl.js:80

---

getById

▸ getById(id): QueryDefinition

Query a single document on its id.

Parameters

Name	Type	Description
id	string	The document id.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:183

---

getByIds

▸ getByIds(ids): QueryDefinition

Query several documents on their ids.

Parameters

Name	Type	Description
ids	any[]	The documents ids.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:196

---

include

▸ include(includes): QueryDefinition

Includes documents having a relationships with the ones queried. For example, query albums including the photos.

Parameters

Name	Type	Description
includes	any[]	The documents to include.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:276

---

indexFields

▸ indexFields(indexedFields): QueryDefinition

Specify which fields should be indexed. This prevent the automatic indexing of the mango fields.

Parameters

Name	Type	Description
indexedFields	any[]	The fields to index.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:232

---

limitBy

▸ limitBy(limit): QueryDefinition

Maximum number of documents returned, useful for pagination. Default is 100.

Parameters

Name	Type	Description
limit	number	The document’s limit.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:289

---

offset

▸ offset(skip): QueryDefinition

Skip the first ‘n’ documents, where ‘n’ is the value specified.

Beware, this performs badly on view’s index. Prefer cursor-based pagination in such situation.

Parameters

Name	Type	Description
skip	number	The number of documents to skip.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:306

---

offsetBookmark

▸ offsetBookmark(bookmark): QueryDefinition

Use bookmark pagination. Note this only applies for mango-queries (not views) and is way more efficient than skip pagination. The bookmark is a string returned by the _find response and can be seen as a pointer in the index for the next query.

Parameters

Name	Type	Description
bookmark	string	The bookmark to continue a previous paginated query.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:344

---

offsetCursor

▸ offsetCursor(cursor): QueryDefinition

Use cursor-based pagination. Warning: this is only useful for views. The cursor is a [startkey, startkey_docid] array, where startkey is the view’s key, e.g. [“io.cozy.photos.albums”, “album-id”] and startkey_docid is the id of the starting document of the query, e.g. “file-id”. Use the last docid of each query as startkey_docid to paginate or leave blank for the first query.

Parameters

Name	Type	Description
cursor	CouchDBViewCursor	The cursor for pagination.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:326

---

partialIndex

▸ partialIndex(partialFilter): QueryDefinition

Specify a partial index. The filter must follow the same syntax than the selector.

A partial index includes a filter, used to select documents before the indexing. You can find more information about partial indexes here

Parameters

Name	Type	Description
partialFilter	any	The filter definition.

Returns

QueryDefinition

Defined in

packages/cozy-client/src/queries/dsl.js:246

---

referencedBy

▸ referencedBy(document): QueryDefinition

Use the file reference system

Parameters

Name	Type	Description
document	any	The reference document

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:359

---

select

▸ select(fields): QueryDefinition

Specify which fields of each object should be returned. If it is omitted, the entire object is returned.

Parameters

Name	Type	Description
fields	any[]	The fields to return.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:220

---

sharingById

▸ sharingById(id): QueryDefinition

Use a sharingId to query documents coming from a sharing

Parameters

Name	Type	Description
id	string	The sharing doc id

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:369

---

sortBy

▸ sortBy(sort): QueryDefinition

Specify how to sort documents, following the sort syntax

Parameters

Name	Type	Description
sort	any[]	The list of field name and direction pairs.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:257

---

toDefinition

▸ toDefinition(): Object

Returns

Object

Name	Type
bookmark	string
cursor	CouchDBViewCursor
doctype	string
fields	string[]
id	string
ids	string[]
includes	string[]
indexedFields	string[]
limit	number
partialFilter	any
referenced	string
selector	any
sharingId	string
skip	number
sort	any[]

Defined in

packages/cozy-client/src/queries/dsl.js:373

---

where

▸ where(selector): QueryDefinition

Query documents with a mango selector. Each field passed in the selector will be indexed, except if the indexField option is used.

Parameters

Name	Type	Description
selector	any	The Mango selector.

Returns

QueryDefinition

The QueryDefinition object.

Defined in

packages/cozy-client/src/queries/dsl.js:207