delphin.tsql

See also

The select command is a quick way to query test suites with TSQL queries.

TSQL – Test Suite Query Language

Note

This module deals with queries of TSDB databases. For basic, low-level access to the databases, see delphin.tsdb. For high-level operations and structures on top of the databases, see delphin.itsdb.

This module implements a subset of TSQL, namely the ‘select’ (or ‘retrieve’) queries for extracting data from test suites. The general form of a select query is:

[select] <projection> [from <relations>] [where <condition>]*

For example, the following selects item identifiers that took more than half a second to parse:

select i-id from item where total > 500

The select string is necessary when querying with the generic query() function, but is implied and thus disallowed when using the select() function.

The <projection> is a list of space-separated field names (e.g., i-id i-input mrs), or the special string * which selects all columns from the joined relations.

The optional from clause provides a list of relation names (e.g., item parse result) that are joined on shared keys. The from clause is required when * is used for the projection, but it can also be used to select columns from non-standard relations (e.g., i-id from output). Alternatively, delphin.itsdb-style data specifiers (see delphin.itsdb.get_data_specifier()) may be used to specify the relation on the column name (e.g., item.i-id).

The where clause provide conditions for filtering the list of results. Conditions are binary operations that take a column or data specifier on the left side and an integer (e.g., 10), a date (e.g., 2018-10-07), or a string (e.g., “sleep”) on the right side of the operator. The allowed conditions are:

Condition

Form

Regex match

<field> ~ "regex"

Regex fail

<field> !~ "regex"

Equality

<field> = (integer|date|"string")

Inequality

<field> != (integer|date|"string")

Less-than

<field> < (integer|date)

Less-or-equal

<field> <= (integer|date)

Greater-than

<field> > (integer|date)

Greater-or-equal

<field> >= (integer|date)

Boolean operators can be used to join multiple conditions or for negation:

Operation

Form

Disjunction

X | Y, X || Y, or X or Y

Conjunction

X & Y, X && Y, or X and Y

Negation

!X or not X

Normally, disjunction scopes over conjunction, but parentheses may be used to group clauses, so the following are equivalent:

... where i-id = 10 or i-id = 20 and i-input ~ "[Dd]og"
... where i-id = 10 or (i-id = 20 and i-input ~ "[Dd]og")

Multiple where clauses may also be used as a conjunction that scopes over disjunction, so the following are equivalent:

... where (i-id = 10 or i-id = 20) and i-input ~ "[Dd]og"
... where i-id = 10 or i-id = 20 where i-input ~ "[Dd]og"

This facilitates query construction, where a user may want to apply additional global constraints by appending new conditions to the query string.

PyDelphin has several differences to standard TSQL:

  • select * requires a from clause

  • select * from item result does not also include columns from the intervening parse relation

  • select i-input from result returns a matching i-input for every row in result, rather than only the unique rows

PyDelphin also adds some features to standard TSQL:

  • qualified column names (e.g., item.i-id)

  • multiple where clauses (as described above)

Module Functions

delphin.tsql.inspect_query(querystring)[source]

Parse querystring and return the interpreted query dictionary.

Example

>>> from delphin import tsql
>>> from pprint import pprint
>>> pprint(tsql.inspect_query(
...     'select i-input from item where i-id < 100'))
{'type': 'select',
 'projection': ['i-input'],
 'relations': ['item'],
 'condition': ('<', ('i-id', 100))}
delphin.tsql.query(querystring, db, **kwargs)[source]

Perform query querystring on the testsuite ts.

Note: currently only ‘select’ queries are supported.

Parameters
  • querystring (str) – TSQL query string

  • ts (delphin.itsdb.TestSuite) – testsuite to query over

  • kwargs – keyword arguments passed to the more specific query function (e.g., select())

Example

>>> list(tsql.query('select i-id where i-length < 4', ts))
[[142], [1061]]
delphin.tsql.select(querystring, db, record_class=None)[source]

Perform the TSQL selection query querystring on testsuite ts.

Note: The select/retrieve part of the query is not included.

Parameters
  • querystring – TSQL select query

  • db – TSDB database to query over

Example

>>> list(tsql.select('i-id where i-length < 4', ts))
[[142], [1061]]

Exceptions

exception delphin.tsql.TSQLSyntaxError(message=None, filename=None, lineno=None, offset=None, text=None)[source]

Bases: delphin.exceptions.PyDelphinSyntaxError

Raised when encountering an invalid TSQL query.