Struct postgrest::Builder

pub struct Builder { /* private fields */ }

QueryBuilder struct

Implementations

impl Builder

pub fn new<T>( url: T, schema: Option<String>, headers: HeaderMap, client: Client ) -> Selfwhere T: Into<String>,

Creates a new Builder with the specified schema.

pub fn auth<T>(self, token: T) -> Selfwhere T: AsRef<str>,

Authenticates the request with JWT.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("table")
    .auth("supers.ecretjw.ttoken");

pub fn select<T>(self, columns: T) -> Selfwhere T: Into<String>,

Performs horizontal filtering with SELECT.

Note

columns is whitespace-sensitive, so you need to omit them unless your column name contains whitespaces.

Example

Simple example:

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
let resp = client
    .from("table")
    .select("*")
    .execute()
    .await?;

Renaming columns:

let resp = client
    .from("users")
    .select("name:very_very_long_column_name")
    .execute()
    .await?;

Casting columns:

let resp = client
    .from("users")
    .select("age::text")
    .execute()
    .await?;

SELECTing JSON fields:

let resp = client
    .from("users")
    .select("id,json_data->phones->0->>number")
    .execute()
    .await?;

Embedded filters (assume there is a foreign key constraint between tables users and tweets):

let resp = client
    .from("users")
    .select("*,tweets(*)")
    .execute()
    .await?;

pub fn order<T>(self, columns: T) -> Selfwhere T: Into<String>,

Orders the result with the specified columns.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .select("*")
    .order("username.desc.nullsfirst,age_range");

pub fn order_with_options<T, U>( self, columns: T, foreign_table: Option<U>, ascending: bool, nulls_first: bool ) -> Selfwhere T: Into<String>, U: Into<String>,

Orders the result of a foreign table with the specified columns.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("countries")
    .select("name, cities(name)")
    .order_with_options("name", Some("cities"), true, false);

pub fn limit(self, count: usize) -> Self

Limits the result with the specified count.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .select("*")
    .limit(20);

pub fn foreign_table_limit<T>(self, count: usize, foreign_table: T) -> Selfwhere T: Into<String>,

Limits the result of a foreign table with the specified count.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("countries")
    .select("name, cities(name)")
    .foreign_table_limit(1, "cities");

pub fn range(self, low: usize, high: usize) -> Self

Limits the result to rows within the specified range, inclusive.

Example

This retrieves the 2nd to 5th entries in the result:

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .select("*")
    .range(1, 4);

pub fn exact_count(self) -> Self

Retrieves the (accurate) total size of the result.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .select("*")
    .exact_count();

pub fn planned_count(self) -> Self

Estimates the total size of the result using PostgreSQL statistics. This is faster than using exact_count().

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .select("*")
    .planned_count();

pub fn estimated_count(self) -> Self

Retrieves the total size of the result using some heuristics: exact_count for smaller sizes, planned_count for larger sizes.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .select("*")
    .estimated_count();

pub fn single(self) -> Self

Retrieves only one row from the result.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .select("*")
    .single();

pub fn insert<T>(self, body: T) -> Selfwhere T: Into<String>,

Performs an INSERT of the body (in JSON) into the table.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .insert(r#"[{ "username": "soedirgo", "status": "online" },
                { "username": "jose", "status": "offline" }]"#);

pub fn upsert<T>(self, body: T) -> Selfwhere T: Into<String>,

Performs an upsert of the body (in JSON) into the table.

Note

This merges duplicates by default. Ignoring duplicates is possible via PostgREST, but is currently unsupported.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .upsert(r#"[{ "username": "soedirgo", "status": "online" },
                { "username": "jose", "status": "offline" }]"#);

pub fn on_conflict<T>(self, columns: T) -> Selfwhere T: Into<String>,

Resolve upsert conflicts on unique columns other than the primary key.

Note

This informs PostgREST to resolve upsert conflicts through an alternative, unique index other than the primary key of the table. See the related PostgREST documentation.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
// Suppose `users` are keyed an SERIAL primary key,
// but have a unique index on `username`.
client
    .from("users")
    .upsert(r#"[{ "username": "soedirgo", "status": "online" },
                { "username": "jose", "status": "offline" }]"#)
    .on_conflict("username");

pub fn update<T>(self, body: T) -> Selfwhere T: Into<String>,

Performs an UPDATE using the body (in JSON) on the table.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .eq("username", "soedirgo")
    .update(r#"{ "status": "offline" }"#);

pub fn delete(self) -> Self

Performs a DELETE on the table.

Example

use postgrest::Postgrest;

let client = Postgrest::new("https://your.postgrest.endpoint");
client
    .from("users")
    .eq("username", "soedirgo")
    .delete();

pub fn rpc<T>(self, params: T) -> Selfwhere T: Into<String>,

Performs a stored procedure call. This should only be used through the rpc() method in Postgrest.

pub fn build(self) -> RequestBuilder

Build the PostgREST request.

pub async fn execute(self) -> Result<Response, Error>

Executes the PostgREST request.

impl Builder

pub fn not<T, U, V>(self, operator: T, column: U, filter: V) -> Selfwhere T: AsRef<str>, U: AsRef<str>, V: AsRef<str>,

Finds all rows which doesn’t satisfy the filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .not("eq", "name", "New Zealand")
    .select("*")
    .execute()
    .await?;

pub fn and<T>(self, filters: T) -> Selfwhere T: AsRef<str>,

Finds all rows satisfying all of the filters.

Note

If your column/filter contains PostgREST’s reserved characters, you need to surround them with double quotes (not percent encoded). See here for details.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .and("name.eq.New Zealand,or(id.gte.1,capital.is.null)")
    .select("*")
    .execute()
    .await?;

pub fn or<T>(self, filters: T) -> Selfwhere T: AsRef<str>,

Finds all rows satisfying at least one of the filters.

Note

If your column/filter contains PostgREST’s reserved characters, you need to surround them with double quotes (not percent encoded). See here for details.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .or("name.eq.New Zealand,or(id.gte.1,capital.is.null)")
    .select("*")
    .execute()
    .await?;

pub fn eq<T, U>(self, column: T, filter: U) -> Selfwhere T: AsRef<str>, U: AsRef<str>,

Finds all rows whose value on the stated column exactly matches the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .eq("name", "New Zealand")
    .select("*")
    .execute()
    .await?;

pub fn neq<T, U>(self, column: T, filter: U) -> Selfwhere T: AsRef<str>, U: AsRef<str>,

Finds all rows whose value on the stated column doesn’t match the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .neq("name", "China")
    .select("*")
    .execute()
    .await?;

pub fn gt<T, U>(self, column: T, filter: U) -> Selfwhere T: AsRef<str>, U: AsRef<str>,

Finds all rows whose value on the stated column is greater than the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .gt("id", "20")
    .select("*")
    .execute()
    .await?;

pub fn gte<T, U>(self, column: T, filter: U) -> Selfwhere T: AsRef<str>, U: AsRef<str>,

Finds all rows whose value on the stated column is greater than or equal to the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .gte("id", "20")
    .select("*")
    .execute()
    .await?;

pub fn lt<T, U>(self, column: T, filter: U) -> Selfwhere T: AsRef<str>, U: AsRef<str>,

Finds all rows whose value on the stated column is less than the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .lt("id", "20")
    .select("*")
    .execute()
    .await?;

pub fn lte<T, U>(self, column: T, filter: U) -> Selfwhere T: AsRef<str>, U: AsRef<str>,

Finds all rows whose value on the stated column is less than or equal to the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .lte("id", "20")
    .select("*")
    .execute()
    .await?;

pub fn like<T, U>(self, column: T, pattern: U) -> Selfwhere T: AsRef<str>, U: Into<String>,

Finds all rows whose value in the stated column matches the supplied pattern (case sensitive).

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .like("name", "%United%")
    .select("*")
    .execute()
    .await?;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .like("name", "%United States%")
    .select("*")
    .execute()
    .await?;

pub fn ilike<T, U>(self, column: T, pattern: U) -> Selfwhere T: AsRef<str>, U: Into<String>,

Finds all rows whose value in the stated column matches the supplied pattern (case insensitive).

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .ilike("name", "%United%")
    .select("*")
    .execute()
    .await?;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .ilike("name", "%united states%")
    .select("*")
    .execute()
    .await?;

pub fn is<T, U>(self, column: T, filter: U) -> Selfwhere T: AsRef<str>, U: AsRef<str>,

A check for exact equality (null, true, false), finds all rows whose value on the stated column exactly match the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .is("name", "null")
    .select("*")
    .execute()
    .await?;

pub fn in_<T, U, V>(self, column: T, values: U) -> Selfwhere T: AsRef<str>, U: IntoIterator<Item = V>, V: AsRef<str>,

Finds all rows whose value on the stated column is found on the specified values.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .in_("name", vec!["China", "France"])
    .select("*")
    .execute()
    .await?;

let resp = Postgrest::new("http://localhost:3000")
    .from("countries")
    .in_("capitals", vec!["Beijing,China", "Paris,France"])
    .select("*")
    .execute()
    .await?;

let resp = Postgrest::new("http://localhost:3000")
    .from("recipes")
    .in_("food_supplies", vec!["carrot (big)", "carrot (small)"])
    .select("*")
    .execute()
    .await?;

pub fn cs<T, U>(self, column: T, filter: U) -> Selfwhere T: AsRef<str>, U: AsRef<str>,

Finds all rows whose json, array, or range value on the stated column contains the values specified in filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("users")
    .cs("age_range", "(10,20)")
    .select("*")
    .execute()
    .await?;

pub fn cd<T, U>(self, column: T, filter: U) -> Selfwhere T: Into<String>, U: AsRef<str>,

Finds all rows whose json, array, or range value on the stated column is contained by the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("users")
    .cd("age_range", "(10,20)")
    .select("*")
    .execute()
    .await?;

pub fn sl<T>(self, column: T, range: (i64, i64)) -> Selfwhere T: Into<String>,

Finds all rows whose range value on the stated column is strictly to the left of the specified range.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("users")
    .sl("age_range", (10, 20))
    .select("*")
    .execute()
    .await?;

pub fn sr<T>(self, column: T, range: (i64, i64)) -> Selfwhere T: Into<String>,

Finds all rows whose range value on the stated column is strictly to the right of the specified range.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .sr("age_range", (10, 20))
    .select("*")
    .execute()
    .await?;

pub fn nxl<T>(self, column: T, range: (i64, i64)) -> Selfwhere T: Into<String>,

Finds all rows whose range value on the stated column does not extend to the left of the specified range.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .nxl("age_range", (10, 20))
    .select("*")
    .execute()
    .await?;

pub fn nxr<T>(self, column: T, range: (i64, i64)) -> Selfwhere T: Into<String>,

Finds all rows whose range value on the stated column does not extend to the right of the specified range.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .nxr("age_range", (10, 20))
    .select("*")
    .execute()
    .await?;

pub fn adj<T>(self, column: T, range: (i64, i64)) -> Selfwhere T: Into<String>,

Finds all rows whose range value on the stated column is adjacent to the specified range.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .adj("age_range", (10, 20))
    .select("*")
    .execute()
    .await?;

pub fn ov<T, U>(self, column: T, filter: U) -> Selfwhere T: Into<String>, U: AsRef<str>,

Finds all rows whose array or range value on the stated column overlaps with the specified filter.

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .ov("age_range", "(10,20)")
    .select("*")
    .execute()
    .await?;

pub fn fts<T, U>(self, column: T, tsquery: U, config: Option<&str>) -> Selfwhere T: Into<String>, U: AsRef<str>,

Finds all rows whose tsvector value on the stated column matches to_tsquery(tsquery).

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .fts("phrase", "The Fat Cats", Some("english"))
    .select("*")
    .execute()
    .await?;

pub fn plfts<T, U>(self, column: T, tsquery: U, config: Option<&str>) -> Selfwhere T: Into<String>, U: AsRef<str>,

Finds all rows whose tsvector value on the stated column matches plainto_tsquery(tsquery).

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .plfts("phrase", "The Fat Cats", None)
    .select("*")
    .execute()
    .await?;

pub fn phfts<T, U>(self, column: T, tsquery: U, config: Option<&str>) -> Selfwhere T: Into<String>, U: AsRef<str>,

Finds all rows whose tsvector value on the stated column matches phraseto_tsquery(tsquery).

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .phfts("phrase", "The Fat Cats", Some("english"))
    .select("*")
    .execute()
    .await?;

pub fn wfts<T, U>(self, column: T, tsquery: U, config: Option<&str>) -> Selfwhere T: Into<String>, U: AsRef<str>,

Finds all rows whose tsvector value on the stated column matches websearch_to_tsquery(tsquery).

Example

use postgrest::Postgrest;

let resp = Postgrest::new("http://localhost:3000")
    .from("table")
    .wfts("phrase", "The Fat Cats", None)
    .select("*")
    .execute()
    .await?;

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.