Query API¶
RestMachine ORM provides a chainable query interface for filtering, ordering, and retrieving data.
Starting a Query¶
Queries are started from model classes:
# Start a query
query = User.where()
# Start with filters (keyword style)
query = User.where(age__gte=18)
# Start with field expressions (recommended)
query = User.where(User.age >= 18)
Query Syntax Styles¶
RestMachine ORM supports two query syntax styles:
Field Expression Syntax (Recommended)¶
SQLAlchemy-style field expressions provide a Pythonic, type-safe way to build queries:
# Basic comparisons
users = User.where(User.age > 25).all()
users = User.where(User.status == "active").all()
# Boolean operators
young_or_old = User.where((User.age < 18) | (User.age > 65)).all()
adults = User.where((User.age >= 18) & (User.age <= 65)).all()
not_deleted = User.where(~(User.status == "deleted")).all()
# String methods
alice_users = User.where(User.name.startswith("Alice")).all()
gmail_users = User.where(User.email.endswith("@gmail.com")).all()
search_users = User.where(User.bio.contains("python")).all()
# Mix with keyword filters
users = User.where(User.age >= 18, is_verified=True).all()
Field Expression Operators:
- ==
- Equal
- !=
- Not equal
- >
- Greater than
- >=
- Greater than or equal
- <
- Less than
- <=
- Less than or equal
- &
- AND (must wrap expressions in parentheses)
- |
- OR (must wrap expressions in parentheses)
- ~
- NOT
Field Expression Methods:
- .startswith(value)
- String starts with
- .endswith(value)
- String ends with
- .contains(value)
- String contains
- .in_(values)
- Field in list
Keyword Syntax (Classic)¶
Traditional Django-style keyword arguments are still fully supported:
# Basic filters
users = User.where(age__gte=18).all()
users = User.where(status="active").all()
# Chaining with and_()
users = User.where(age__gte=18).and_(status="active").all()
# NOT conditions
users = User.where().not_(status="deleted").all()
Query Methods¶
Filtering¶
where(*expressions, **filters)
- Start query with expressions and/or keyword filtersand_(**filters)
- Add AND conditions (keyword style only)not_(**filters)
- Add NOT conditions (keyword style only)
Comparison Operators (Keyword Syntax)¶
Use these suffixes in filter kwargs:
field__gt
- Greater thanfield__gte
- Greater than or equalfield__lt
- Less thanfield__lte
- Less than or equalfield__ne
- Not equalfield__in
- In listfield__contains
- Contains substringfield__startswith
- Starts withfield__endswith
- Ends with
Example:
Ordering¶
order_by(*fields)
- Order results- Use
"field"
for ascending - Use
"-field"
for descending
Example:
Pagination¶
limit(n)
- Limit resultsoffset(n)
- Skip n resultscursor(cursor_value)
- Use cursor for pagination
Example:
# Offset-based
page1 = User.where().limit(10).all()
page2 = User.where().limit(10).offset(10).all()
# Cursor-based
results, cursor = User.where().limit(10).paginate()
if cursor:
more, next_cursor = User.where().limit(10).cursor(cursor).paginate()
Execution¶
all()
- Get all matching resultsfirst()
- Get first result or Nonelast()
- Get last result or Nonecount()
- Count matching resultsexists()
- Check if any matchpaginate()
- Get results and pagination cursor
Example: