arangodb-query-parser
v0.1.20
Published
Convert url query string to ArangoDB friendly query object.
Downloads
6
Readme
arangodb-query-parser
Convert url query string to ArangoDB database AQL query.
Features
Supports most of the ArangoDB operators and features including filters, sorting, limit, skip, populating and aggregations.
Note: as this library allows to create heavy and/or unintentional database queries use it with caution in public environments!
Installation
npm install arangodb-query-parser
Usage
API
import { ArangoDbQueryParser } from 'arangodb-query-parser';
const parser = new ArangoDbQueryParser(options?: ParserOptions)
const queryOptions = parser.parse(query: string, predefined: any) : QueryOptions
parser.createQuery(queryOptions);
Constructor
Initialize parser with given options.
Arguments
ParserOptions
: Object for advanced options:dateFormat
: Date format, default is ISO-8601 (YYYY-MM-DD)whitelist
: String array of fields allowed to be in the filterblacklist
: String array of fields disallowed to be in the filtercasters
: Custom casterscastParams
: Caster parameterscollection
: Name of the collection for querypopulateMapping
: Field to collection mappingspopulateAlways
: Related collections/fields that are always populatedfieldsKey
: Name of the query parameter used for selected fieldspopulateKey
: Name of the query parameter used for reference populationsortKey
: Name of the query parameter used for sortinglimitKey
: Name of the query parameter for result count limit and skipfilterKey
: Name of the query parameter for filtersaggregateKey
: Name of the query parameter for aggregations
parser.parse(query, predefined)
Parses the query parameters into a QueryOptions object.
Arguments
query
: query string part of the requested API URL (ie,firstName=John&limit=10
). [required]predefined
: object for predefined queries/string templates [optional]
Returns
QueryOptions
: object contains the following properties:filter.filters
contains the query stringfilter.bindVars
contains the query binding valuesfields
contains the query projectionpopulate
paths to populatesort
,limit
contains the cursor modifiers for paging purposes.aggregate
contains the parsed aggregations
Filters
All other query parameters are considered to be filters. Example:
?firstName=Frederick&lastName=Durst
Specifies filters for firstName and lastName fields. Several values can be separated with comma for alternatives (OR):
?firstName=Frederick,Bernie,Jack
Value can be a regular expression:
?firstName=/frederick/i
Other signs for number and date fields:
?price<1000 // price is less than 1000
?price!=1000 // price is not 1000
?price>=1000 // price is larger or equal to 1000
?categories?=party // categories array includes party (any)
?categories*=party // categories array includes party (all)
?categories#=party // categories array does not include party (none)
Filters are excluding by default (AND): you can create OR by adding pipe character in front of the field name:
?price<1000&|price>1500 // price is less than 1000 or larger than 1500
Fields
Result fields can be specified in the format:
?fields=firstName,lastName
Limit
Result limits can be specified in the format:
?limit=10
will return 10 items. Optionally you can add starting offset:
?limit=10,30
will return 10 items starting from 30.
Sorting
Sorting can be specified in the format:
?sort=creationDate,-price
will sort first by creationDate ascending and then by price descending.
Populating
Two choices for relationship population exists:
- "Hardcoded" population with option populateAlways and populateMapping.
- Permissive population with option populateMapping and parsed parameter populate.
The option populateMapping is used for mapping allowed relationships (field to collection).
Option populateAlways can be used for specifying which relationships are always populated.
Example 1 - map field owner to collection users and field parent to collection customers:
const parser = new ArangoDbQueryParser({
collection: 'customers',
populateMapping: { owner: 'users', parent: 'customers' },
});
Then the query URL can specify which relationships to populate, for example:
?populate=owner,parent.name,parent.name2
will populate all fields from owner and fields name & name2 from parent.
Example 2 - map field owner to collection users and field parent to collection customers, specify that all fields from owner and name field from parent are always populated:
const parser = new ArangoDbQueryParser({
collection: 'customers',
populateMapping: { owner: 'users', parent: 'customers' },
populateAlways: 'owner,parent.name'
});
You can disable default populates with dash:
?populate=-owner,-parent.name
To disable all populates use a dash only:
?populate=-
Aggregations
Aggregations can be specified in the format:
field,field2:as func field3
Where
field
andfield2
are the grouping fieldsas
is the name of the aggregationfunc
is the aggregation function (avg, sum, min, max, length, stddev, variance, count, count_distinct, unique, sorted_unique)field3
is the name of the aggregated field
Example:
?aggregate=owner,status:totalPrice sum sum,averagePrice avg sum,priceCount count sum
You can leave out the grouping fields:
?aggregate=totalCount count owner
will create query for aggregation without grouping.
parser.createQuery(queryOptions)
Arguments
queryOptions
: query options created by parse method. [required]
Returns
query
: AQL query (as string) created from the query options. This can be used together with queryoptions filter.bindVars to run the query in ArangoDB.
License
Thanks
This library is heavily based on mongoose-query-parser by Leodinas Hao