Querying

The query module provides a structured interface for filtering, selecting, sorting, aggregating, and joining datasets. It also supports raw SQL queries via DuckDB.

The query engine is scaffolded. The public API surface is defined but most methods raise NotImplementedError. This page documents the designed interface.

QueryEngine


from hermes.query import QueryEngine
 
engine = QueryEngine()

Methods

`filter(data, conditions) -> object`

Filter rows based on conditions:


filtered = engine.filter(data, conditions=[...])

`select(data, columns) -> object`

Select specific columns:


subset = engine.select(data, columns=["country", "gdp_growth"])

`sort(data, columns, ascending=True) -> object`

Sort by one or more columns:


sorted_data = engine.sort(data, columns=["date"], ascending=False)

`aggregate(data, operations) -> object`

Aggregate with specified operations:


agg = engine.aggregate(data, operations={"value": "mean", "count": "sum"})

`join(left, right, on) -> object`

Join two datasets:


joined = engine.join(left_df, right_df, on="country_code")

`sql(query) -> object`

Execute a raw SQL query:


result = engine.sql("SELECT country, AVG(value) FROM data GROUP BY country")

Filters

Structured filter objects:


from hermes.query.filters import eq, gt, lt, gte, lte, in_list, between
 
# Equality
f = eq("country", "US")
 
# Comparisons
f = gt("value", 100)
f = lt("value", 0)
f = gte("year", 2020)
f = lte("year", 2024)
 
# Membership
f = in_list("country", ["US", "GB", "JP"])
 
# Range
f = between("value", 0, 100)

Expressions

Logical combinators:


from hermes.query.expressions import and_, or_, not_
 
# Combine filters
combined = and_(eq("country", "US"), gt("value", 100))
any_match = or_(eq("country", "US"), eq("country", "GB"))
negated = not_(eq("country", "XX"))

Top-Level API


import hermes as hr
 
result = hr.query(data, conditions=[eq("country", "US")])