Query Language

Filter and query data using conditional operators and parameters

Queries can be made using query string parameters on any object or nested object attribute. You can specify advanced conditional operators like greater-than or boolean on any parameter as described below.

Select, Update, and Delete operations can be performed on query results.

Conditional Queries

Less-Than Conditional

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Query for payments less than $200
payments = pl.Transaction.filter_by(
    pl.attr.amount < 200
).all()

Query for records where a numeric field is less than a specified value.

Combining Less-Than and Greater-Than

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Query for payments between $100 and $200
payments = pl.Transaction.filter_by(
    pl.attr.amount > 100,
    pl.attr.amount < 200
).all()

Combine multiple operators to create range queries for numeric values.

OR Conditional

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Query for payments with specific risk statuses
payments = pl.Transaction.filter_by(
    (pl.attr.risk_flag == 'denied') | (pl.attr.risk_flag == 'in_review')
).all()

Match records where a field equals any of multiple values using OR logic.

Like Conditional

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Query for payments with descriptions containing 'INV -'
payments = pl.Transaction.filter_by(
    pl.attr.description.contains('INV -')
).all()

Search for records containing specific text within a field.

Combined Conditional Example

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Query combining multiple conditions
payments = pl.Transaction.filter_by(
    pl.attr.amount > 100,
    pl.attr.amount < 200,
    (pl.attr.risk_status == 'denied') | (pl.attr.risk_status == 'in_review'),
    pl.attr.description.contains('INV -'),
    pl.attr.created_at.date() != '2025-02-01',
).all()

Combine multiple query conditions for complex filtering logic.

Nested Object Parameters

Nested objects or lists can be referenced as a query string parameter using the following syntax:

Nested Object Parameters

?object[attr]=value

2nd Degree Nested Object Parameters

?object[subobject][attr]=value

Nested List

?list[0]=value

Nested List of Objects

?list[0][attr]=value

Query Operators

Query String Examples

Basic Equality

https://api.payload.com/customers/?status=active

Range Queries

https://api.payload.com/transactions/?amount=>100&amount=<1000

OR Conditions

https://api.payload.com/payments/?status=processed|pending

Nested Object Queries

https://api.payload.com/invoices/?customer[email][email protected]

Like/Contains Queries

https://api.payload.com/customers/?name=?*John*

Date Queries

https://api.payload.com/transactions/?created_at=>2023-01-01&created_at=<2023-12-31