Request Builders#

Note

In the source code, there are separate synchronous and asynchronous request builder classes. These classes are otherwise exactly the same, and provide the same interfaces.

Warning

These classes are not meant to be constructed by the user.

class postgrest.AsyncRequestBuilder#

__init__(session: AsyncClient, path: str) → None#

select(*columns: str, count: CountMethod | None = None) → AsyncSelectRequestBuilder[_ReturnT]#

Run a SELECT query.

Parameters:

*columns – The names of the columns to fetch.
count – The method to use to get the count of rows returned.

Returns:

AsyncSelectRequestBuilder

insert(json: dict | list, *, count: CountMethod | None = None, returning: ReturnMethod = ReturnMethod.representation, upsert: bool = False) → AsyncQueryRequestBuilder[_ReturnT]#

Run an INSERT query.

Parameters:

json – The row to be inserted.
count – The method to use to get the count of rows returned.
returning – Either ‘minimal’ or ‘representation’
upsert – Whether the query should be an upsert.

Returns:

AsyncQueryRequestBuilder

upsert(json: dict | list, *, count: CountMethod | None = None, returning: ReturnMethod = ReturnMethod.representation, ignore_duplicates: bool = False, on_conflict: str = '') → AsyncQueryRequestBuilder[_ReturnT]#

Run an upsert (INSERT … ON CONFLICT DO UPDATE) query.

Parameters:

json – The row to be inserted.
count – The method to use to get the count of rows returned.
returning – Either ‘minimal’ or ‘representation’
ignore_duplicates – Whether duplicate rows should be ignored.
on_conflict – Specified columns to be made to work with UNIQUE constraint.

Returns:

AsyncQueryRequestBuilder

update(json: dict, *, count: CountMethod | None = None, returning: ReturnMethod = ReturnMethod.representation) → AsyncFilterRequestBuilder[_ReturnT]#

Run an UPDATE query.

Parameters:

json – The updated fields.
count – The method to use to get the count of rows returned.
returning – Either ‘minimal’ or ‘representation’

Returns:

AsyncFilterRequestBuilder

delete(*, count: CountMethod | None = None, returning: ReturnMethod = ReturnMethod.representation) → AsyncFilterRequestBuilder[_ReturnT]#

Run a DELETE query.

Parameters:

count – The method to use to get the count of rows returned.
returning – Either ‘minimal’ or ‘representation’

Returns:

AsyncFilterRequestBuilder

class postgrest.AsyncSelectRequestBuilder#

__init__(session: AsyncClient, path: str, http_method: str, headers: Headers, params: QueryParams, json: dict) → None#

single() → AsyncSingleRequestBuilder[_ReturnT]#: Specify that the query will only return a single row in response.

Caution

The API will raise an error if the query returned more than one row.

maybe_single() → AsyncMaybeSingleRequestBuilder[_ReturnT]#: Retrieves at most one row from the result. Result must be at most one row (e.g. using eq on a UNIQUE column), otherwise this will result in an error.

csv() → AsyncSingleRequestBuilder[str]#: Specify that the query must retrieve data as a single CSV string.

eq(column: str, value: Any) → Self#

An ‘equal to’ filter.

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

async execute() → APIResponse[_ReturnT]#

Execute the query.

Tip

This is the last method called, after the query is built.

Returns:: APIResponse
Raises:: APIError –

filter(column: str, operator: str, criteria: str) → Self#

Apply filters on a query.

Parameters:

column – The name of the column to apply a filter on
operator – The operator to use while filtering
criteria – The value to filter by

gt(column: str, value: Any) → Self#

A ‘greater than’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

gte(column: str, value: Any) → Self#

A ‘greater than or equal to’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

ilike(column: str, pattern: str) → Self#

An ‘ILIKE’ filter, to use for pattern matching (case insensitive).

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

ilike_all_of(column: str, pattern: str) → Self#

A ‘ILIKE’ filter, to use for pattern matching (case insensitive).

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

ilike_any_of(column: str, pattern: str) → Self#

A ‘ILIKE’ filter, to use for pattern matching (case insensitive).

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

is_(column: str, value: Any) → Self#

An ‘is’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

like(column: str, pattern: str) → Self#

A ‘LIKE’ filter, to use for pattern matching.

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

like_all_of(column: str, pattern: str) → Self#

A ‘LIKE’ filter, to use for pattern matching.

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

like_any_of(column: str, pattern: str) → Self#

A ‘LIKE’ filter, to use for pattern matching.

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

limit(size: int, *, foreign_table: str | None = None) → Self#

Limit the number of rows returned by a query.

Parameters:

size – The number of rows to be returned
foreign_table – Foreign table name to limit

Changed in version 0.10.3: Allow limiting results returned for foreign tables with the foreign_table parameter.

lt(column: str, value: Any) → Self#

A ‘less than’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

lte(column: str, value: Any) → Self#

A ‘less than or equal to’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

neq(column: str, value: Any) → Self#

A ‘not equal to’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

property not_: Self#: Whether the filter applied next should be negated.

offset(size: int) → _FilterT#: Set the starting row index returned by a query. :param size: The number of the row to start at

or_(filters: str, reference_table: str | None = None) → Self#

An ‘or’ filter

Parameters:

filters – The filters to use, following PostgREST syntax
reference_table – Set this to filter on referenced tables instead of the parent table

order(column: str, *, desc: bool = False, nullsfirst: bool = False, foreign_table: str | None = None) → Self#

Sort the returned rows in some specific order.

Parameters:

column – The column to order by
desc – Whether the rows should be ordered in descending order or not.
nullsfirst – nullsfirst
foreign_table – Foreign table name whose results are to be ordered.

Changed in version 0.10.3: Allow ordering results for foreign tables with the foreign_table parameter.

class postgrest.AsyncQueryRequestBuilder#

__init__(session: AsyncClient, path: str, http_method: str, headers: Headers, params: QueryParams, json: dict) → None#

async execute() → APIResponse[_ReturnT]#

Execute the query.

Tip

This is the last method called, after the query is built.

Returns:: APIResponse
Raises:: APIError –

class postgrest.SyncRequestBuilder#

__init__(session: SyncClient, path: str) → None#

select(*columns: str, count: CountMethod | None = None) → SyncSelectRequestBuilder[_ReturnT]#

Run a SELECT query.

Parameters:

*columns – The names of the columns to fetch.
count – The method to use to get the count of rows returned.

Returns:

AsyncSelectRequestBuilder

insert(json: dict | list, *, count: CountMethod | None = None, returning: ReturnMethod = ReturnMethod.representation, upsert: bool = False) → SyncQueryRequestBuilder[_ReturnT]#

Run an INSERT query.

Parameters:

json – The row to be inserted.
count – The method to use to get the count of rows returned.
returning – Either ‘minimal’ or ‘representation’
upsert – Whether the query should be an upsert.

Returns:

AsyncQueryRequestBuilder

Run an upsert (INSERT … ON CONFLICT DO UPDATE) query.

Parameters:

json – The row to be inserted.
count – The method to use to get the count of rows returned.
returning – Either ‘minimal’ or ‘representation’
ignore_duplicates – Whether duplicate rows should be ignored.
on_conflict – Specified columns to be made to work with UNIQUE constraint.

Returns:

AsyncQueryRequestBuilder

update(json: dict, *, count: CountMethod | None = None, returning: ReturnMethod = ReturnMethod.representation) → SyncFilterRequestBuilder[_ReturnT]#

Run an UPDATE query.

Parameters:

json – The updated fields.
count – The method to use to get the count of rows returned.
returning – Either ‘minimal’ or ‘representation’

Returns:

AsyncFilterRequestBuilder

delete(*, count: CountMethod | None = None, returning: ReturnMethod = ReturnMethod.representation) → SyncFilterRequestBuilder[_ReturnT]#

Run a DELETE query.

Parameters:

count – The method to use to get the count of rows returned.
returning – Either ‘minimal’ or ‘representation’

Returns:

AsyncFilterRequestBuilder

class postgrest.SyncSelectRequestBuilder#

__init__(session: SyncClient, path: str, http_method: str, headers: Headers, params: QueryParams, json: dict) → None#

single() → SyncSingleRequestBuilder[_ReturnT]#: Specify that the query will only return a single row in response.

Caution

The API will raise an error if the query returned more than one row.

maybe_single() → SyncMaybeSingleRequestBuilder[_ReturnT]#: Retrieves at most one row from the result. Result must be at most one row (e.g. using eq on a UNIQUE column), otherwise this will result in an error.

csv() → SyncSingleRequestBuilder[str]#: Specify that the query must retrieve data as a single CSV string.

eq(column: str, value: Any) → Self#

An ‘equal to’ filter.

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

execute() → APIResponse[_ReturnT]#

Execute the query.

Tip

This is the last method called, after the query is built.

Returns:: APIResponse
Raises:: APIError –

filter(column: str, operator: str, criteria: str) → Self#

Apply filters on a query.

Parameters:

column – The name of the column to apply a filter on
operator – The operator to use while filtering
criteria – The value to filter by

gt(column: str, value: Any) → Self#

A ‘greater than’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

gte(column: str, value: Any) → Self#

A ‘greater than or equal to’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

ilike(column: str, pattern: str) → Self#

An ‘ILIKE’ filter, to use for pattern matching (case insensitive).

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

ilike_all_of(column: str, pattern: str) → Self#

A ‘ILIKE’ filter, to use for pattern matching (case insensitive).

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

ilike_any_of(column: str, pattern: str) → Self#

A ‘ILIKE’ filter, to use for pattern matching (case insensitive).

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

is_(column: str, value: Any) → Self#

An ‘is’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

like(column: str, pattern: str) → Self#

A ‘LIKE’ filter, to use for pattern matching.

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

like_all_of(column: str, pattern: str) → Self#

A ‘LIKE’ filter, to use for pattern matching.

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

like_any_of(column: str, pattern: str) → Self#

A ‘LIKE’ filter, to use for pattern matching.

Parameters:

column – The name of the column to apply a filter on
pattern – The pattern to filter by

limit(size: int, *, foreign_table: str | None = None) → Self#

Limit the number of rows returned by a query.

Parameters:

size – The number of rows to be returned
foreign_table – Foreign table name to limit

Changed in version 0.10.3: Allow limiting results returned for foreign tables with the foreign_table parameter.

lt(column: str, value: Any) → Self#

A ‘less than’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

lte(column: str, value: Any) → Self#

A ‘less than or equal to’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

neq(column: str, value: Any) → Self#

A ‘not equal to’ filter

Parameters:

column – The name of the column to apply a filter on
value – The value to filter by

property not_: Self#: Whether the filter applied next should be negated.

offset(size: int) → _FilterT#: Set the starting row index returned by a query. :param size: The number of the row to start at

or_(filters: str, reference_table: str | None = None) → Self#

An ‘or’ filter

Parameters:

filters – The filters to use, following PostgREST syntax
reference_table – Set this to filter on referenced tables instead of the parent table

order(column: str, *, desc: bool = False, nullsfirst: bool = False, foreign_table: str | None = None) → Self#

Sort the returned rows in some specific order.

Parameters:

column – The column to order by
desc – Whether the rows should be ordered in descending order or not.
nullsfirst – nullsfirst
foreign_table – Foreign table name whose results are to be ordered.

Changed in version 0.10.3: Allow ordering results for foreign tables with the foreign_table parameter.

class postgrest.SyncQueryRequestBuilder#

__init__(session: SyncClient, path: str, http_method: str, headers: Headers, params: QueryParams, json: dict) → None#

execute() → APIResponse[_ReturnT]#

Execute the query.

Tip

This is the last method called, after the query is built.

Returns:: APIResponse
Raises:: APIError –