gbd_core.query.GBDQuery

class documentation

class GBDQuery: (source)

Constructor: GBDQuery(db, query)

View In Hierarchy

Translates a GBD query string and parameters into a complete SQLite SELECT statement.

A GBD query spans one or more ATTACHed SQLite databases managed by Database. Each database belongs to a context (e.g. cnf, wcnf, pbo). Features within the same context are joined directly; features from a different context require a translator feature - a 1:n feature named to_{context} that maps hashes between contexts.

Typical usage:

q   = GBDQuery(db, "filename like foo%")
sql = q.build_query(resolve=["local"], collapse="group_concat")
rows = db.query(sql)
Method __init__ No summary
Method build_from Build the FROM / JOIN clause.
Method build_query Build and return a complete SQL SELECT statement.
Method build_select Build the SELECT clause.
Method build_where Build the WHERE clause body.
Method determine_group_by Return the default context:hash column used as the GROUP BY key.
Method features_exist_or_throw Raise DatabaseException if any feature in features does not exist in the attached databases.
Method find_translator_feature Find the 1:n translator feature that bridges two contexts.
Instance Variable db Undocumented
Instance Variable features Undocumented
Instance Variable parser Undocumented
def __init__(self, db: Database, query): (source)
Parameters
db:DatabaseMulti-database instance used for feature resolution.
query:str|
None
GBD filter expression, or None / empty string for an unconditional (match-all) query.
def build_from(self, group, features, join_type='LEFT'): (source)

Build the FROM / JOIN clause.

Three JOIN strategies depending on the feature's context relative to the group-by column:

  1. Same-context, 1:1 feature (column in features table): {join_type} JOIN db.features ON db.features.hash = base.hash
  2. Same-context, 1:n feature (separate table): ensures db.features is joined first, then {join_type} JOIN db.{name} ON db.{name}.hash = db.features.{name}
  3. Cross-context: always INNER JOIN via the translator feature table regardless of join_type (see Issues.md #4).
Parameters
group:strFeature identifier of the group-by column; its database is the base FROM table.
features:set[str]All features that must appear in the clause (filter features + resolved features).
join_type:str"LEFT" or "INNER" applied to same-context joins.
Returns
strSQL FROM / JOIN clause.
def build_query(self, hashes=[], resolve=[], group_by=None, join_type='LEFT', collapse=None): (source)

Build and return a complete SQL SELECT statement.

Parameters
hashes:list[str]Restrict results to these benchmark hashes.
resolve:list[str]Features to include as output columns.
group_by:str|
None
Group results by this feature instead of the default context:hash column; inferred from resolve when None.
join_type:str"LEFT" (default, include unmatched hashes) or "INNER" (exclude them). Cross-context joins are always INNER (see Issues.md #4).
collapse:str|
None
Aggregate function for resolved columns; one of "group_concat", "min", "max", "avg", "count", "sum". None returns one raw row per join result.
Returns
strReady-to-execute SQL query.
def build_select(self, group_by, resolve, collapse=None): (source)

Build the SELECT clause.

When collapse is given, every selected column (including the group-by column) is wrapped with the aggregate function. Without collapse, SELECT DISTINCT deduplicates rows.

The group-by column is also aggregated, which is redundant when GROUP BY is present (see Issues.md #6).

Parameters
group_by:strPrimary output column (always first in the SELECT list).
resolve:list[str]Additional output columns.
collapse:str|
None
Aggregate function name (e.g. "group_concat"), or None for no aggregation.
Returns
str
SQL SELECT clause, e.g.
"SELECT DISTINCT cnf_db.features.hash, cnf_db.local.value".
def build_where(self, hashes, group_by): (source)

Build the WHERE clause body.

Combines three conditions with AND:

  1. group_column != 'None' excludes the sentinel null-hash row present in every 1:n feature table (see Issues.md #7 - sentinel design).
  2. The SQL fragment compiled from the GBD filter expression.
  3. An optional hash IN (...) restriction when hashes is non-empty.
Parameters
hashes:list[str]Benchmark hashes to restrict results to; empty list means no hash restriction.
group_by:strFeature identifier of the group-by column.
Returns
strSQL WHERE clause body (without the WHERE keyword).
def determine_group_by(self, resolve): (source)

Return the default context:hash column used as the GROUP BY key.

Uses the database of the first feature in resolve, or the primary hash feature when resolve is empty.

When resolve spans multiple contexts, only the first feature's context is considered (see Issues.md #5).

Parameters
resolve:list[str]Features that will be resolved in the query.
Returns
strFeature identifier of the form "context:hash".
def features_exist_or_throw(self, features): (source)

Raise DatabaseException if any feature in features does not exist in the attached databases.

Parameters
features:list[str]Feature identifiers to validate.
def find_translator_feature(self, source_context, target_context): (source)

Find the 1:n translator feature that bridges two contexts.

A translator feature is a 1:n feature named to_{target_context} stored in a database of source_context, or to_{source_context} stored in a database of target_context. It provides a hash mapping used by build_from to construct cross-context JOINs.

Parameters
source_context:strContext of the primary (group-by) table.
target_context:strContext of the feature being resolved.
Returns
FeatureInfoInfo object for the translator feature.
Raises
DatabaseExceptionIf no translator feature exists for the context pair.
db = (source)

Undocumented

features = (source)

Undocumented

parser = (source)

Undocumented