The query module exports the [SQL] query method to pass queries to dbs connections configured in the XYZ process environment.

Requires

Methods

(async, inner) checkFieldsParam(req, res) → {Error}

Layer queries should restrict the fields provided as param to query templates.

The method will call the recursive objPropValueSet method to parse the layer object for any values referenced as properties with the 'field' key.

Field values may not be referenced in the layer object from role restricted templates.

The method will return an Error if the fields request param contains a string value which is not referenced in a field prooperty in the layer object.

Parameters:
NameTypeDescription
reqreq

HTTP request.

resres

HTTP response.

Properties
NameTypeAttributesDescription
req.paramsobject

The request object params.

params.fieldsstring<optional>

The request layer object [from template].

params.layerobject

The request layer object [from template].

Returns:

An error will be returned if the check fails.

Type: 
Error

(inner) getQueryFromTemplate(req, template) → {string}

The method will assign the body param from the request body object in a post query.

The template.render method will be called to return a query string.

An error will be returned if the template object does not have a template string.

Varibles must be replaced or substituted in query string to prevent SQL injections.

Parameter to be replaced in the SQL query string must be checked to only contain whitelisted character to prevent SQL injection.

Any variables to be replaced on query execution in the database must be replaced with indices in the query string. eg. $1, $2, ...

The substitute values are stored in the ordered params.SQL[] array.

An error will be returned if the substitution fails.

Parameters:
NameTypeDescription
reqreq

HTTP request.

templateobject

Request template.

Properties
NameTypeAttributesDescription
req.bodyobject<optional>

Post request body.

req.paramsobject

Request params.

params.filterobject<optional>

JSON filter which must be turned into a SQL filter string for substitution.

params.SQLarray

Substitute parameter for SQL query.

params.sqlFilterstring<optional>

A string which must be parsed as JSON to create a SQL filter string.

template.renderfunction<optional>

Method to render template string.

template.templatestring

SQL template string.

Returns:

A PostgreSQL query string.

Type: 
string

(async, inner) infojMap(req, res)

The method assigns the infojMap object property to the request params for layer requests.

The method iterates over the layer.infoj entries and only assigns entry fields valid for a location_get request.

A lookup of template [SQL] strings is attempted only if the template is defined in the entry object.

Parameters:
NameTypeDescription
reqreq

HTTP request.

resres

HTTP response.

Properties
NameTypeDescription
req.paramsobject

The request params.

params.layerobject

The layer object assigned by the layerQuery

(async, inner) layerQuery(req, res)

Queries which reference a layer must be checked against the layer JSON in the workspace.

Layer query templates must have a layer request property.

Layer queries have restricted viewport and filter params. These params can not be substituted in the database but must be replaced in the SQL query string.

Any query which references a layer and locale will be passed through the layer query method. The getLayer method will fail return an error if the locale is not defined as param or the layer is not a member of the locale.

The fields request param property may be provided as an array. The string should be replaced with the template property of a matching workspace template.

Parameters:
NameTypeDescription
reqreq

HTTP request.

resres

HTTP response.

Properties
NameTypeAttributesDescription
req.paramsobject

Request params.

params.filterobject<optional>

JSON filter which must be turned into a SQL filter string for substitution.

params.SQLarray

Substitute parameter for SQL query.

params.viewportstring<optional>

Viewport string to be split into an array to create a SQL viewport.

params.userobject<optional>

Requesting user.

params.layer_templatestring<optional>

A layer can be loaded directly from a template not referenced in a locale.

(inner) objPropValueSet(obj, prop, set)

The recursive method parses all properties in an object and calls itself if the property value is an object.

String values of object properties with the key matching the prop argument will be added to the set argument.

Parameters:
NameTypeDescription
objobject

Object to parse for property values.

propstring

The property key.

setset

The set to which the property values should be added.

(async, inner) query(req, res)

The [SQL] query method requests a query template from the getTemplate method and checks whether the requesting user is permitted to execute the query.

The layerQuery() method must be awaited to check whether params are referenced in a role restricted JSON layer.

The query method assigns and checks the dbs connection for the query template.

A query string must returned from the getQueryFromTemplate() method.

The query and SQL params to be substituted in the database process are send to the dbs_connection.

The rows returned from the dbs_connection are then passed to the sendRows() method.

Parameters:
NameTypeDescription
reqreq

HTTP request.

resres

HTTP response.

Properties
NameTypeAttributesDescription
req.paramsObject

Request params.

params.userObject<optional>

Requesting user.

user.rolesArray<optional>

User roles.

params.value_onlyboolean<optional>

Return a single value from one row.

params.reduceboolean<optional>

Reduce query response to a values array.

params.nonblockingboolean<optional>

Execute a nonblocking query.

params.statement_timeoutinteger<optional>

Timeout for database connection.

(inner) replaceStringParams(req, matched) → {string}

The method receives a variable matched from a regex /${(.{0,99}?)}/g which should be replaced with a request params string.

Table and column names cannot be provided a values to be substituted in the database. To protect from SQL injections these variables may only contain whitelisted characters /^[A-Za-z0-9,"'._-\s]*$/.

Optional params such as [SQL] filter, and viewports may contain any character and will be replaced with an empty string if not provided in the req.params{}.

Parameters:
NameTypeDescription
reqreq

HTTP request.

matchedstring

${variable} to replace in template.

Properties
NameTypeDescription
req.paramsobject

Request params.

params.missingarray

Missing params in req.params.

params.optionalset

Optional params for query template [eg filter, viewport].

Returns:

The string to replace the matched variable with.

Type: 
string

(inner) replaceValueParams(req, matched) → {string}

The method receives a variable matched from a regex /%{(.{0,99}?)}/g which should be substituted in the database to protect from SQL injections.

Optional params such as [SQL] filter, and viewports may contain any character and will be replaced with an empty string if not provided in the req.params{}.

Variable substitution works with sequential placeholders. Values from the req.params or req.body will be added to the params.SQL[] array and replaced with a $n placeholder in the query_template string where n is the index of value in the params.SQL[] array.

Parameters:
NameTypeDescription
reqreq

HTTP request.

matchedstring

%{variable} to be substituted in database.

Properties
NameTypeDescription
req.paramsobject

Request params.

params.SQLarray

Array of values to be substituted in the database.

params.missingarray

Missing params in req.params.

params.optionalset

Optional params for query template [eg filter, viewport].

Returns:

The string to replace the matched variable with.

Type: 
string

(inner) sendRows(res, template, rows)

The method formats the rows returned from a SQL query and sends the formated rows through the HTTP response object.

Parameters:
NameTypeDescription
resres

HTTP response.

templateobject

Request template.

rowsarray

The response from a SQL query.

Properties
NameTypeAttributesDescription
template.value_onlyboolean<optional>

Return a single value from one row.

template.reduceboolean<optional>

Reduce query response to a values array.

(inner) templateTables(template) → {Array}

The methods call the internal getObjTables method to iterate through the [layer] template object argument and its nested propertiess. Any 'table' string properties and string values of a 'tables' object are pushed into tables array returned from the method.

Parameters:
NameTypeDescription
templateobject

[Layer] template object to parse for table strings.

Returns:

Array of table strings in layer template object.

Type: 
Array