Influxdb-query-parser NPM

influxdb-query-parser

Convert url query string to InfluxDB database InfluxQL query.

Features

Supports most of the InfluxDB operators and features including filters, sorting, limit, offset 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 influxdb-query-parser

Usage

API

import { InfluxDbQueryParser } from 'influxdb-query-parser';

const parser = new InfluxDbQueryParser(options?: ParserOptions)
const queryOptions = parser.parse(query: string) : 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 filter - blacklist: String array of fields disallowed to be in the filter - casters: Custom casters - castParams: Caster parameters - measurements: Names of the measurements for query - fieldsKey: Name of the query parameter used for selected fields - sortKey: Name of the query parameter used for sorting - limitKey: Name of the query parameter for result count limit and skip - filterKey: Name of the query parameter for filters - aggregateKey: Name of the query parameter for aggregations - fillKey: Name of the query parameter for aggregate fill - parseArray: Set to true if you want to automatically split comma seperated strings to array - parseBoolean: Set to true if you want to automatically cast true/false to boolean, otherwise you need to use boolean(true) caster

parser.parse(query)

Parses the query parameters into a QueryOptions object.

Arguments

query: query string part of the requested API URL (ie, firstName=John&limit=10). required

Returns

QueryOptions: object contains the following properties:
- filter.filters contains the query string
- fields contains the query projection
- sort, - limit contains the cursor modifiers for paging purposes - aggregate contains the parsed aggregations - fill contains the parsed aggregate fill.

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 larger than 1000
?price!=1000     // price is not 1000
?price>=1000     // price is larger or equal to 1000

Casters

Filter values can be casted or modified with special caster functions. Default casters:

date cast value to date. Caster takes parameters in format value:modifier?:date? where value can be a date string or key: - shortcuts: startOfYear, startOfQuarter, startOfMonth, startOfWeek, endOfYear, endOfQuarter, endOfWeek - Examples: - Start of current year: startOfYear or startOfYear:0 - Start of next year: startOfYear:1 - Start of previous year: startOfYear:-1 - Optional date parameter can be used for example: startOfYear:0:2019-10-01 to return start of year for the given date. - Other shortcuts to adjust from current or given date by modifier: year, quarter, month, week, day - Examples: - day:2019-10-01:1 to return the next day - day:-10 date for 10 days ago - month:1 date for one month to future
boolean caster to cast parameter to boolean:

?enabled=boolean(true)

string caster to explicitly cast parameter to string:

?key=string(123)

number caster to cast parameter to number:

?key=number(1.34)

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.

Aggregations

Aggregations can be specified in the format:

?aggregate=field,field2:as func field3

Where

field and field2 are the grouping fields
as is the name of the aggregation
func is the aggregation function (sum, count, distict, integral, mean, median, mode, spread, stddev, bottom, first, last, max, min, percentile, sample, top)
field3 is the name of the aggregated field

Example:

?aggregate=owner,status:totalPrice sum price,averagePrice avg price,priceCount count price

You can leave out the grouping fields:

?aggregate=totalCount count owner

will create query for aggregation without grouping.

InfluxDB specific time aggregations can be specified with syntax:

?aggregate=field,field2:time duration

Where

field and field2 are the grouping fields
time is static key top)
duration is InfluxDB duration (5m = 5 minutes, 3d = 3 days, 4mo = 4 months etc.) (See InfluxDB Documentation)

By default InfluxDB returns null for missing aggregated values. Behaviour can be changed with the fill parameter, example: