Trait TablesampleDsl

pub trait TablesampleDsl: Table {
    // Provided methods
    fn tablesample_bernoulli(
        self,
        portion: i16,
    ) -> Tablesample<Self, BernoulliMethod> { ... }
    fn tablesample_system(self, portion: i16) -> Tablesample<Self, SystemMethod> { ... }
}

Available on crate feature postgres_backend only.

The tablesample method

The TABLESAMPLE clause is used to select a randomly sampled subset of rows from a table.

This is only implemented for the Postgres backend. While TABLESAMPLE is standardized in SQL:2003, in practice each RDBMS seems to implement a superset of the SQL:2003 syntax, supporting a wide variety of sampling methods.

Calling this function on a table (mytable.tablesample(...)) will result in the SQL FROM mytable TABLESAMPLE ... – mytable.tablesample(...) can be used just like any table in diesel since it implements Table.

The BernoulliMethod and SystemMethod types can be used to indicate the sampling method for a TABLESAMPLE method(p) clause where p is specified by the portion argument. The provided percentage should be an integer between 0 and 100.

To generate a TABLESAMPLE ... REPEATABLE (f) clause, you’ll need to call .with_seed(f).

Example:

let random_user_ids = users::table
    .tablesample_bernoulli(10)
    .select((users::id))
    .load::<i32>(connection);

Selects the ids for a random 10 percent of users.

It can also be used in inner joins:

users::table
    .tablesample_system(10).with_seed(42.0)
    .inner_join(posts::table)
    .select((users::name, posts::title))
    .load::<(String, String)>(connection);

That query selects all of the posts for all of the users in a random 10 percent storage pages, returning the same results each time it is run due to the static seed of 42.0.

Provided Methods

fn tablesample_bernoulli( self, portion: i16, ) -> Tablesample<Self, BernoulliMethod>

See the trait-level docs.

fn tablesample_system(self, portion: i16) -> Tablesample<Self, SystemMethod>

See the trait-level docs.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T: Table> TablesampleDsl for T