Functions

Apply transformations, aggregations, and date operations to attributes

Functions can be applied to attributes in either a query string conditional statement or to modify the attribute value in the response.

There are a few special aggregate functions which can only be used to modify the response, not in a conditional statement.

Basic Function Usage

basic.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
customers = pl.Account.select(
		pl.attr.email.lower(),
		*pl.attr
	)\
	.filter_by( pl.attr.created_at.year() == 2020 )\
	.all()

String Functions

Transform and manipulate string values:

Function	Description	Example
`lower`	Convert to lowercase	`pl.attr.email.lower()`
`upper`	Convert to uppercase	`pl.attr.name.upper()`
`length`	Get string length	`pl.attr.description.length()`

String Function Examples

string.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Select customers with lowercase emails
 
 
customers = pl.Account.select(
    pl.attr.id,
    pl.attr.email.lower()
).all()
 
# Filter by string length
long_names = pl.Account.filter_by(
    pl.attr.legal_name.length() > 20
).all()
 
# Uppercase names in response
customers = pl.Account.select(
    pl.attr.name.upper(),
    pl.attr.email
).all()

Numeric Functions

Perform mathematical operations on numeric values:

Function	Description	Example
`abs`	Absolute value	`pl.attr.balance.abs()`
`ceil`	Round up to nearest integer	`pl.attr.amount.ceil()`
`floor`	Round down to nearest integer	`pl.attr.amount.floor()`
`round`	Round to nearest integer	`pl.attr.amount.round()`

Numeric Function Examples

numeric.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Get absolute values of account balances
 
 
accounts = pl.Account.select(
    pl.attr.id,
    pl.attr.balance.abs()
).all()
 
# Filter by rounded amounts
transactions = pl.Transaction.filter_by(
    pl.attr.amount.round() == 100
).all()

Date Functions

Extract and manipulate date/time values:

Function	Description	Example
`year`	Extract year	`pl.attr.created_at.year()`
`month`	Extract month number	`pl.attr.created_at.month()`
`monthname`	Extract month name	`pl.attr.created_at.monthname()`
`day`	Extract day of month	`pl.attr.created_at.day()`
`dayname`	Extract day of week name	`pl.attr.created_at.dayname()`
`dayofweek`	Extract day of week number	`pl.attr.created_at.dayofweek()`
`dayofyear`	Extract day of year	`pl.attr.created_at.dayofyear()`
`weekofyear`	Extract week of year	`pl.attr.created_at.weekofyear()`
`last_day`	Get last day of month	`pl.attr.created_at.last_day()`
`hour`	Extract hour	`pl.attr.created_at.hour()`
`minute`	Extract minute	`pl.attr.created_at.minute()`
`second`	Extract second	`pl.attr.created_at.second()`
`unix_timestamp`	Convert to Unix timestamp	`pl.attr.created_at.unix_timestamp()`

Date Function Examples

date.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Group customers by signup year
 
 
yearly_signups = pl.Account.select(
    pl.attr.created_at.year(),
    pl.attr.id.count()
).group_by(
    pl.attr.created_at.year()
).all()
 
# Filter by specific month
march_customers = pl.Account.filter_by(
    pl.attr.created_at.month() == 3
).all()
 
# Get day of week for transactions
transactions = pl.Transaction.select(
    pl.attr.id,
    pl.attr.created_at.dayname()
).all()

Aggregate Functions

Aggregate functions can be used to produce an aggregated response. You can combine aggregate functions with a group_by attribute to produce grouped results.

Function	Description	Example
`sum`	Sum values	`pl.attr.amount.sum()`
`count`	Count records	`pl.attr.id.count()`
`count_distinct`	Count unique values	`pl.attr.customer_id.count_distinct()`
`avg`	Average value	`pl.attr.amount.avg()`
`min`	Minimum value	`pl.attr.amount.min()`
`max`	Maximum value	`pl.attr.amount.max()`
`variance`	Statistical variance	`pl.attr.amount.variance()`
`stddev`	Standard deviation	`pl.attr.amount.stddev()`

Aggregate functions and group_by requests currently do not support nested object hierarchies. This functionality only works on immediate objects.

Aggregate Function Example

aggregate.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
invoice_stats = (
    pl.Invoice.select(
        pl.attr.amount_due.sum(),
        pl.attr.status,
    )
    .filter_by(
        pl.attr.due_date >= '2026-01-01',
    )
    .group_by(pl.attr.status)
    .all()
)

Response:

[
  {
    "status": "overdue",
    "sum(amount_due)": 2389.5
  },
  {
    "status": "paid",
    "sum(amount)": 52310.0
  }
]

Group By

Use the group_by parameter to group results by one or more attributes:

Parameter	Description	Example
`group_by=status`	Group results by status	`?group_by=status`

Group By Examples

group.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Monthly revenue report
 
 
monthly_revenue = (
    pl.Transaction.select(
        pl.attr.created_at.month(), pl.attr.created_at.year(), pl.attr.amount.sum()
    )
    .group_by(pl.attr.created_at.year(), pl.attr.created_at.month())
    .all()
)
 
# Account statistics
account_stats = (
    pl.Transaction.select(
        pl.attr.sender.account_id,
        pl.attr.id.count(),
        pl.attr.amount.avg(),
        pl.attr.amount.sum(),
    )
    .group_by(pl.attr.sender.account_id)
    .all()
)

Function Combinations

You can combine multiple functions for complex transformations:

combo.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Complex date grouping with aggregations
 
 
quarterly_stats = (
    pl.Transaction.select(
        pl.attr.created_at.year(),
        pl.attr.created_at.month(),
        pl.attr.amount.sum(),
        pl.attr.amount.avg(),
        pl.attr.id.count(),
    )
    .filter_by(pl.attr.created_at.year() >= 2020)
    .group_by(
        pl.attr.created_at.year(),
        pl.attr.created_at.month(),
    )
    .order_by(
        pl.attr.created_at,
    )
    .all()
)

Paging & Ordering Custom Attributes