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, qualified names (e.g.,
item.i-id
) can specify both the column and the relation at the
same time.
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 |
|
Regex fail |
|
Equality |
|
Inequality |
|
Less-than |
|
Less-or-equal |
|
Greater-than |
|
Greater-or-equal |
|
Boolean operators can be used to join multiple conditions or for negation:
Operation |
Form |
---|---|
Disjunction |
|
Conjunction |
|
Negation |
|
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 afrom
clauseselect * from item result
does not also include columns from the interveningparse
relationselect i-input from result
returns a matchingi-input
for every row inresult
, 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 overkwargs – 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.
-
exception
delphin.tsql.
TSQLError
(*args, **kwargs)[source]¶ Bases:
delphin.exceptions.PyDelphinException
Raised on invalid TSQL operations.