Querying Data
Use select() to retrieve rows from a table. It returns a list of dictionaries,
one per row, keyed by column name.
db.select(table, condition="", fields="*", order="")fields is the third positional argument, not order
A call like db.select('products', "price < 100", 'ORDER BY price') puts the
ORDER BY clause into the column list and produces broken SQL. Always pass the
ordering by keyword: order='ORDER BY price'.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
table | str | — | Name of the table |
condition | dict or str | "" |
Filter for the WHERE clause. Dict keys are joined with AND; a string is
injected verbatim. Empty means no WHERE clause.
|
fields | str | "*" | Comma-separated column list placed after SELECT. |
order | str | "" |
Raw SQL appended after the WHERE clause — ORDER BY, LIMIT,
GROUP BY, or anything else that legally follows WHERE.
|
Select all rows
products = db.select('products')
for p in products:
print(p['name'], p['price'])
Select specific columns
Pass fields to avoid pulling every column back:
# SELECT id,name FROM products
rows = db.select('products', fields='id,name')
# Aggregates work too — the result key is the expression as written
total = db.select('orders', fields='COUNT(*) AS total')
print(total[0]['total'])
Filter with a SQL string
results = db.select('products', "price < 100")
results = db.select('products', "name LIKE '%cable%'")
results = db.select('products', "category IN ('a','b') OR featured = 1")
Filter with a dictionary
Multiple keys are joined with AND, and every value is quoted:
# SELECT * FROM products WHERE category='electronics' AND in_stock='1'
results = db.select('products', {'category': 'electronics', 'in_stock': 1})
The dict branch is guarded by collections.Iterable, removed from the standard
library in Python 3.10, so this call raises
AttributeError: module 'collections' has no attribute 'Iterable' there. String
conditions are unaffected — the check short-circuits before it is reached. On Python 3.10+,
write the condition as a string. See Limitations.
Ordering and limiting results
The order argument is appended verbatim, so it is not limited to
ORDER BY:
# 10 most expensive products
top10 = db.select('products', order='ORDER BY price DESC LIMIT 10')
# Page 2 (rows 11–20)
page2 = db.select('products', order='ORDER BY id ASC LIMIT 10, 10')
# Combined filter + order
recent = db.select('orders', "status = 'pending'", order='ORDER BY created_at DESC LIMIT 5')
# GROUP BY is legal here as well
by_cat = db.select('products', fields='category, COUNT(*) AS n', order='GROUP BY category')
Return value
A list of dicts, one per row. If no rows match, select() returns an empty list
[] — it never returns None for an empty result set.
rows = db.select('users', "email = '[email protected]'")
if rows:
print(rows[0]['name']) # first (and likely only) match
else:
print("User not found")
If the query itself fails, the error is printed rather than raised and the return value is
unreliable — select() reads the cursor state left behind by the previous
statement. See Limitations.