gws.lib.cql.builder

Build database expressions from CQL2 parse trees.

Source code: gws.lib.cql.builder

Module Contents

class gws.lib.cql.builder.Builder

Walks a CQL2 parse tree and dispatches nodes to handler methods.

Node types go to build_<type> methods, standard functions to func_<name> methods (names are lowercased). This class implements no node types; subclasses add handlers.

build(e)

Build an expression from a parse tree node.

Calls build_<type> with the node arguments, or build_operator for operators without one.

Parameters:

e – Parse tree node.

Returns:

The expression returned by the handler.

Raises:

BuildError – If the node type is not implemented.

build_function(args)

Build a standard function call by calling func_<name> with the argument nodes.

Parameters:

args – Function name, followed by the argument nodes.

Returns:

The expression returned by the handler.

Raises:

BuildError – If the function is not implemented.

build_operator(op, args)

Build an operator expression.

Parameters:

• op – Operator, e.g. > or +.

• args – Operand nodes.

Returns:

The expression. Not implemented in this class.

Raises:

BuildError – Always, in this class.

build_user_function(args)

Build a non-standard function call. Subclasses handle their own functions here.

Parameters:

args – Function name as written, followed by the argument nodes.

Returns:

The expression. Not implemented in this class.

Raises:

BuildError – Always, in this class.

get_method(name)

Find a handler method.

Parameters:

name – Method name, case-insensitive.

Returns:

The method, or None if the builder does not implement it.

value(e) → Any

Unwrap a literal node into a plain python value.

Parameters:

e – Literal node. Array nodes are unwrapped recursively.

Returns:

The value, a list for arrays.

Raises:

BuildError – If the node is not a literal.

exception gws.lib.cql.builder.BuildError

Bases: Exception

A parse tree node or function is not supported by the builder, or its arguments are invalid.

class gws.lib.cql.builder.SqlBuilder(table: gws.lib.sa.Table)

Bases: Builder

Builds SQLAlchemy expressions for a postgis table.

Names refer to table columns, literals become bound parameters, geometries are in WGS84. All standard CQL2 functions are implemented, user functions are not.

table

array_element_type(vals)

Infer the element type of an array literal from its first element.

Parameters:

vals – Array values.

Returns:

An SQLAlchemy type, Text for an empty array or non-numeric values.

array_operand(e)

Build an array expression, an array literal becoming a typed parameter.

Parameters:

e – Array literal or another node.

Returns:

An array expression.

array_pair(args)

Coerce both operands of an array predicate to arrays.

Parameters:

args – Two array nodes.

Returns:

A tuple of two array expressions.

build_and(args)

Build a conjunction.

Parameters:

args – Operand nodes.

Returns:

An AND expression.

build_array(args)

Build an array.

Parameters:

args – Element nodes.

Returns:

A list of expressions.

build_bbox(args)

Build a bounding box geometry.

Parameters:

args – Four numbers: min x, min y, max x, max y.

Returns:

A rectangle geometry in WGS84.

build_between(args)

Build a BETWEEN predicate.

Parameters:

args – The value, lower bound and upper bound nodes.

Returns:

A BETWEEN expression.

build_bool(args)

Build a boolean literal.

Parameters:

args – A list with the value.

Returns:

A bound parameter.

build_date(args)

Build a date literal.

Parameters:

args – A list with the date value.

Returns:

A DATE expression.

build_float(args)

Build a float literal.

Parameters:

args – A list with the value.

Returns:

A bound parameter.

build_in(args)

Build an IN predicate.

Parameters:

args – The value node, followed by the list item nodes.

Returns:

An IN expression.

build_int(args)

Build a integer literal.

Parameters:

args – A list with the value.

Returns:

A bound parameter.

build_is_null(args)

Build an IS NULL predicate.

Parameters:

args – A list with the value node.

Returns:

An IS NULL expression.

build_like(args)

Build a LIKE predicate.

Parameters:

args – The value and pattern nodes.

Returns:

A LIKE expression.

build_name(args)

Build a column reference.

Parameters:

args – Name parts, only the first is used as the column name.

Returns:

The table column.

Raises:

BuildError – If the table has no such column.

build_not(args)

Build a negation.

Parameters:

args – A list with the operand node.

Returns:

A NOT expression.

build_not_between(args)

Build a NOT BETWEEN predicate.

Parameters:

args – The value, lower bound and upper bound nodes.

Returns:

A negated BETWEEN expression.

build_not_in(args)

Build a NOT IN predicate.

Parameters:

args – The value node, followed by the list item nodes.

Returns:

A negated IN expression.

build_not_like(args)

Build a NOT LIKE predicate.

Parameters:

args – The value and pattern nodes.

Returns:

A negated LIKE expression.

build_not_null(args)

Build an IS NOT NULL predicate.

Parameters:

args – A list with the value node.

Returns:

An IS NOT NULL expression.

build_operator(op, args)

Build an operator expression.

Parameters:

• op – Operator, e.g. > or +.

• args – Operand nodes.

Returns:

The expression. Not implemented in this class.

Raises:

BuildError – Always, in this class.

build_or(args)

Build a disjunction.

Parameters:

args – Operand nodes.

Returns:

An OR expression.

build_string(args)

Build a string literal.

Parameters:

args – A list with the value.

Returns:

A bound parameter.

build_timestamp(args)

Build a timestamp literal.

Parameters:

args – A list with the datetime value.

Returns:

A timestamptz expression.

build_wkt(args)

Build a geometry literal.

Parameters:

args – A list with the WKT string.

Returns:

A geometry in WGS84.

func_a_containedby(args)

Build the A_CONTAINEDBY array predicate.

Parameters:

args – Two array nodes.

Returns:

A condition that is true if all elements of the first array are in the second.

func_a_contains(args)

Build the A_CONTAINS array predicate.

Parameters:

args – Two array nodes.

Returns:

A condition that is true if the first array contains all elements of the second.

func_a_equals(args)

Build the A_EQUALS array predicate.

Parameters:

args – Two array nodes.

Returns:

A condition that is true if both arrays contain the same elements, ignoring order and duplicates.

func_a_overlaps(args)

Build the A_OVERLAPS array predicate.

Parameters:

args – Two array nodes.

Returns:

A condition that is true if the arrays have a common element.

func_accenti(args)

Build the ACCENTI function.

Parameters:

args – A string node.

Returns:

The value without accents, using the postgres unaccent extension.

func_bbox(args)

Build the BBOX function.

Parameters:

args – Four number literal nodes: min x, min y, max x, max y.

Returns:

A rectangle geometry in WGS84.

Raises:

BuildError – If an argument is not a literal.

func_casei(args)

Build the CASEI function.

Parameters:

args – A string node.

Returns:

The lowercased value.

func_date(args)

Build the DATE function.

Parameters:

args – An ISO date string literal node.

Returns:

A DATE expression.

Raises:

BuildError – If the argument is not a literal.

func_interval(args)

Reject INTERVAL outside of temporal predicates.

Parameters:

args – Interval bound nodes.

Raises:

BuildError – Always.

func_s_contains(args)

Build the S_CONTAINS spatial predicate.

Parameters:

args – Two geometry nodes.

Returns:

An ST_Contains expression.

func_s_crosses(args)

Build the S_CROSSES spatial predicate.

Parameters:

args – Two geometry nodes.

Returns:

An ST_Crosses expression.

func_s_disjoint(args)

Build the S_DISJOINT spatial predicate.

Parameters:

args – Two geometry nodes.

Returns:

An ST_Disjoint expression.

func_s_equals(args)

Build the S_EQUALS spatial predicate.

Parameters:

args – Two geometry nodes.

Returns:

An ST_Equals expression.

func_s_intersects(args)

Build the S_INTERSECTS spatial predicate.

Parameters:

args – Two geometry nodes.

Returns:

An ST_Intersects expression.

func_s_overlaps(args)

Build the S_OVERLAPS spatial predicate.

Parameters:

args – Two geometry nodes.

Returns:

An ST_Overlaps expression.

func_s_touches(args)

Build the S_TOUCHES spatial predicate.

Parameters:

args – Two geometry nodes.

Returns:

An ST_Touches expression.

func_s_within(args)

Build the S_WITHIN spatial predicate.

Parameters:

args – Two geometry nodes.

Returns:

An ST_Within expression.

func_t_after(args)

Build the T_AFTER temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the first range starts after the second ends.

func_t_before(args)

Build the T_BEFORE temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the first range ends before the second starts.

func_t_contains(args)

Build the T_CONTAINS temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the second range lies strictly inside the first.

func_t_disjoint(args)

Build the T_DISJOINT temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the ranges have no common point.

func_t_during(args)

Build the T_DURING temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the first range lies strictly inside the second.

func_t_equals(args)

Build the T_EQUALS temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if both ranges are equal.

func_t_finishedby(args)

Build the T_FINISHEDBY temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if both ranges end together and the first starts earlier.

func_t_finishes(args)

Build the T_FINISHES temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if both ranges end together and the first starts later.

func_t_intersects(args)

Build the T_INTERSECTS temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the ranges have a common point.

func_t_meets(args)

Build the T_MEETS temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the first range ends where the second starts.

func_t_metby(args)

Build the T_METBY temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the first range starts where the second ends.

func_t_overlappedby(args)

Build the T_OVERLAPPEDBY temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the first range starts inside the second and ends after it.

func_t_overlaps(args)

Build the T_OVERLAPS temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if the first range starts before the second and ends inside it.

func_t_startedby(args)

Build the T_STARTEDBY temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if both ranges start together and the first ends later.

func_t_starts(args)

Build the T_STARTS temporal predicate.

Parameters:

args – Two temporal nodes, instants or intervals.

Returns:

A condition that is true if both ranges start together and the first ends earlier.

func_timestamp(args)

Build the TIMESTAMP function.

Parameters:

args – An ISO date-time string literal node.

Returns:

A timestamptz expression.

Raises:

BuildError – If the argument is not a literal.

literal(val)

Wrap a python value as a bound parameter.

Parameters:

val – Value.

Returns:

A literal expression.

temporal_bound(e, unbounded)

Build an interval bound.

Parameters:

• e – Bound node. The string '..' means an open bound.

• unbounded – Value for an open bound, -infinity or infinity.

Returns:

A timestamptz expression.

temporal_pair(args)

Coerce both operands of a temporal predicate to ranges.

Parameters:

args – Two temporal nodes.

Returns:

A tuple of two tstzrange expressions.

temporal_range(e)

Coerce a temporal expression to a tstzrange, an instant becomes a degenerate range.

A null bound is unbounded in postgres, therefore null inputs must yield a null range, otherwise a null column would match everything.

Parameters:

e – An INTERVAL function node, or a node that builds a timestamp.

Returns:

A tstzrange expression with inclusive bounds, null if a bound is null.

timestamp_value(e)

Coerce an expression to a timestamptz, naive values are assumed to be UTC.

Parameters:

e – Node.

Returns:

A timestamptz expression.