@c8y/client
Version:
Client application programming interface to access the Cumulocity IoT-Platform REST services.
166 lines • 8.53 kB
TypeScript
export type QueryObjectRoot = QueryObjectFilterComparison;
export type QueryObjectFilterComparison = {
__and?: QueryObjectRoot | QueryObjectRoot[];
__or?: QueryObjectRoot | QueryObjectRoot[];
__not?: QueryObjectRoot | QueryObjectRoot[];
[key: string]: {
__eq?: string | number | boolean;
__lt?: string | number;
__gt?: string | number;
__le?: string | number;
__ge?: string | number;
} | string | string[] | number | QueryObjectRoot | QueryObjectRoot[] | Array<string | number | boolean | null> | undefined;
__eq?: {
[key: string]: string | number | boolean;
};
__lt?: {
[key: string]: string | number;
};
__gt?: {
[key: string]: string | number;
};
__le?: {
[key: string]: string | number;
};
__ge?: {
[key: string]: string | number;
};
__in?: Array<string | number | boolean | null>;
__bygroupid?: number | string | Array<string | number>;
__isinhierarchyof?: number | string | Array<string | number>;
__has?: string;
__hasany?: string | string[];
__useFilterQueryString?: string;
};
/**
* Object defining how to order results by specific fields.
*
* Key is the field path, value is:
* 1 for ascending, -1 for descending, 0 for no order
*/
export interface QueryObjectOrderBy {
[key: string]: 1 | -1 | 0 | undefined;
}
export interface QueryObjectWithDedicatedFilter {
__filter?: QueryObjectRoot;
__orderby?: QueryObjectOrderBy[];
}
export type QueryObject = QueryObjectWithDedicatedFilter | QueryObjectRoot;
export declare class QueriesUtil {
protected operatorFns: {
__not: (operand: any) => string;
__and: (operand: any) => string;
__or: (operand: any) => string;
__eq: (operand: any, contextKey: string) => string;
__gt: (operand: any, contextKey: string) => string;
__ge: (operand: any, contextKey: string) => string;
__lt: (operand: any, contextKey: string) => string;
__le: (operand: any, contextKey: string) => string;
__in: (operand: Array<string | number | boolean>, contextKey: string) => string;
__bygroupid: (operand: number | string | Array<string | number>) => string;
__has: (operand: string) => string;
__isinhierarchyof: (operand: string | number | Array<string | number>) => string;
__hasany: (operand: string | string[]) => string;
__useFilterQueryString: (queryString: string) => string;
};
/**
* Builds query string from provided query object.
*
* @param query Object containing filters and sort order for querying managed objects. Supported filters are:
* - **__and** - Specifies conditions, e.g. `{__and: [{__has: 'c8y_IsDevice'}, {'count': {__gt: 0}}]}`.
* - **__or** - Specifies alternative conditions, e.g. `{__or: [{__bygroupid: 10300}, {__bygroupid: 10400}]}`.
* - **__eq** - Specified fragment must be equal to given value, e.g. `{'status': 'AVAILABLE'}` (no nested object required).
* - **__lt** - Specified fragment must be less then given value, e.g. `{'count': {__lt: 10}}`.
* - **__gt** - Specified fragment must be greater then given value, e.g. `{'count': {__gt: 0}}`.
* - **__in** - Specified fragment must be equal to one of values in the list, e.g. `{'status': {__in: ['AVAILABLE', 'UNAVAILABLE']}}`.
* - **__not** - Negates condition, e.g. `{__not: {'status': 'AVAILABLE'}}`.
* - **__bygroupid** - True if filtered managed object is assigned to given group, e.g. `{__bygroupid: 10300}`.
* - **__has** - Specified fragment must have a value defined, e.g. `{__has: 'c8y_IsDevice'}`.
* - **__hasany** - Matches objects having at least one of the fragments defined, e.g. `{__has: ['c8y_IsDevice', 'c8y_Dashboard']}`.
* - **__isinhierarchyof** - Matches objects that are in hierarchy of given managed object, e.g. `{__isinhierarchyof: '12345'}`.
* - **__useFilterQueryString** - Gets rid of the `$filter=()… $orderby=…` parts of a query and keeps only what's between the most
* exterior parentheses of the $filter.
* EXAMPLE: takes a query of the form
* `$filter=(name eq 'RaspPi*') $orderby=name asc`
* and turns it into
* `name eq 'RaspPi*'`
* This is necessary for searching for smart groups, which are identified by their own query
* that needs to be passed through.
*
* Note: if you want to specify the order, you need to wrap your filters within `__filter` property and then add `__orderby` with the array of field paths and sort directions (1 for ascending, -1 for descending), for example:
* - `{ __filter: { ... }, __orderby: [{ 'creationTime': -1 }, { 'name': 1 }] }`
*
* @returns {string} Returns a query string ready to be sent in request params to backend.
*
* **Example**
* ```typescript
* const query = {
* __filter: {
* 'name': 'My Device*',
* 'c8y_Availability.status': {
* __in: ['AVAILABLE', 'UNAVAILABLE']
* },
* 'creationTime': {
* __lt: '2015-11-30T13:28:123Z'
* },
* 'c8y_ActiveAlarmsStatus.critical': {
* __gt: 0
* },
* __or: [
* {__not: {__has: 'c8y_ActiveAlarmsStatus.major'}},
* {
* __or: [
* {__bygroupid: 10300},
* {__bygroupid: 10400}
* ]
* }
* ]
* },
* __orderby: [
* {'name': 1},
* {'creationTime': -1},
* {'c8y_ActiveAlarmsStatus.critical': -1}
* ]
* };
*
* const params = {
* query: queriesUtil.buildQuery(query)
* };
* ```
*/
buildQuery(query: QueryObjectWithDedicatedFilter | QueryObjectRoot | QueryObjectRoot[]): string;
buildQueryFilter(queryFilter: QueryObjectRoot | QueryObjectRoot[], _queryKey?: string, _glueType?: 'and' | 'or'): string;
buildQueryOrderby(queryOrderbys: QueryObjectOrderBy[]): string;
addAndFilter(query: QueryObjectWithDedicatedFilter | QueryObjectRoot, filter: QueryObjectRoot): QueryObjectFilterComparison | QueryObjectWithDedicatedFilter | {
[x: string]: QueryObjectFilterComparison[];
};
addOrFilter(query: QueryObjectWithDedicatedFilter | QueryObjectRoot, filter: QueryObjectRoot): QueryObjectFilterComparison | QueryObjectWithDedicatedFilter | {
[x: string]: QueryObjectFilterComparison[];
};
addFilter(query: QueryObjectWithDedicatedFilter | QueryObjectRoot, filter: QueryObjectRoot, operator: 'and' | 'or'): QueryObjectFilterComparison | QueryObjectWithDedicatedFilter | {
[x: string]: QueryObjectFilterComparison[];
};
prependOrderbys(query: QueryObjectWithDedicatedFilter | QueryObjectRoot, orderbys: QueryObjectOrderBy[]): QueryObjectWithDedicatedFilter;
appendOrderbys(query: QueryObjectWithDedicatedFilter | QueryObjectRoot, orderbys: QueryObjectOrderBy[]): QueryObjectWithDedicatedFilter;
addOrderbys(query: QueryObjectWithDedicatedFilter | QueryObjectRoot, orderbys: QueryObjectOrderBy[], how: 'prepend' | 'append'): QueryObjectWithDedicatedFilter;
extractAndMergeOrderBys(queries: string[]): string;
protected glue(statements: string[], type: 'and' | 'or'): string;
protected useAsFloat(operand: string | number): string;
protected quoteString<T>(s: T): T;
protected skipEmptyObjects<T extends object>(objs: T[]): T[];
protected isEmptyObject(obj: object): boolean;
/**
* Escapes a string to be used in OData query.
*
* - OData does not support single quotes in the query. We need to replace all single quotes with double quotes.
* - OData uses parentheses for grouping expressions and functions. We need to escape any parentheses in the string.
* - OData uses backslash as an escape character. We need to escape any backslashes in the string.
*
* Spec: http://docs.oasis-open.org/odata/odata/v4.01/cs01/part2-url-conventions/odata-v4.01-cs01-part2-url-conventions.html#sec_URLComponents
*
* @param s String to be escaped.
* @returns Escaped string.
*/
private escapeString;
}
//# sourceMappingURL=QueriesUtil.d.ts.map