Struct QueryParamsBuilder 

pub struct QueryParamsBuilder<'q, T> { /* private fields */ }

Implementations

impl<'q, T: Default + Serialize> QueryParamsBuilder<'q, T>

pub fn new() -> Self

Creates a new QueryParamsBuilder with default values.

Default values include:

• Page: 1
• Page size: 10
• Sort column: “created_at”
• Sort direction: Descending

Examples

use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}
let builder = QueryParamsBuilder::<UserExample>::new();

pub fn with_pagination(self, page: i64, page_size: i64) -> Self

Creates a new QueryParamsBuilder with default values.

Default values include:

• Page: 1
• Page size: 10
• Sort column: “created_at”
• Sort direction: Descending

Examples

use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}
let builder = QueryParamsBuilder::<UserExample>::new();

pub fn with_sort( self, sort_column: impl Into<String>, sort_direction: QuerySortDirection, ) -> Self

Sets sorting parameters.

Arguments

• sort_column - Column name to sort by
• sort_direction - Direction of sort (Ascending or Descending)

Examples

use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder, QuerySortDirection};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let params = QueryParamsBuilder::<UserExample>::new()
    .with_sort("updated_at", QuerySortDirection::Ascending)
    .build();

pub fn with_search( self, search: impl Into<String>, search_columns: Vec<impl Into<String>>, ) -> Self

Sets search parameters with multiple columns support.

Arguments

• search - Search term to look for
• search_columns - Vector of column names to search in

Examples

use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder, QuerySortDirection};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let params = QueryParamsBuilder::<UserExample>::new()
    .with_search("john", vec!["name", "email", "username"])
    .build();

pub fn with_date_range( self, date_after: Option<DateTime<Utc>>, date_before: Option<DateTime<Utc>>, column_name: Option<impl Into<String>>, ) -> Self

Sets date range parameters for filtering by date.

Arguments

• date_after - Optional start date (inclusive)
• date_before - Optional end date (inclusive)
• column_name - Optional column name to apply date range filter (defaults to created_at)

Examples

use chrono::{DateTime, Utc};
use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder, QuerySortDirection};

#[derive(Serialize, Default)]
struct UserExample {
    name: String,
    updated_at: DateTime<Utc>
}

let start = DateTime::parse_from_rfc3339("2024-01-01T00:00:00Z").unwrap().into();
let end = DateTime::parse_from_rfc3339("2024-12-31T23:59:59Z").unwrap().into();

let params = QueryParamsBuilder::<UserExample>::new()
    .with_date_range(Some(start), Some(end), Some("updated_at"))
    .build();

pub fn with_filter_operator( self, key: impl Into<String>, operator: QueryFilterOperator, value: impl Into<String>, ) -> Self

Adds a single filter condition with an operator.

Arguments

• key - Column name to filter on
• operator - The comparison operator to use
• value - Value to filter by (required for most operators except IS NULL/IS NOT NULL)

Details

Only adds the filter if the column exists in the model struct. Logs a warning if tracing is enabled and the column is invalid.

Examples

use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder, QueryFilterOperator};

#[derive(Serialize, Default)]
struct Product {
    name: String,
    price: f64,
    stock: i32,
    status: String,
}

let params = QueryParamsBuilder::<Product>::new()
    .with_filter_operator("price", QueryFilterOperator::GreaterThan, "10.00")
    .with_filter_operator("stock", QueryFilterOperator::LessOrEqual, "100")
    .with_filter_operator("status", QueryFilterOperator::NotEqual, "deleted")
    .build();

pub fn with_filter_null(self, key: impl Into<String>, is_null: bool) -> Self

Adds a filter condition for IS NULL or IS NOT NULL checks.

Arguments

• key - Column name to filter on
• is_null - If true, checks IS NULL; if false, checks IS NOT NULL

Examples

use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder};

#[derive(Serialize, Default)]
struct User {
    name: String,
    deleted_at: Option<String>,
}

let params = QueryParamsBuilder::<User>::new()
    .with_filter_null("deleted_at", true)  // IS NULL
    .build();

pub fn with_filter_in( self, key: impl Into<String>, values: Vec<impl Into<String>>, ) -> Self

Adds an IN filter condition with multiple values.

Arguments

• key - Column name to filter on
• values - Vector of values to check against

Examples

use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder};

#[derive(Serialize, Default)]
struct User {
    name: String,
    role: String,
}

let params = QueryParamsBuilder::<User>::new()
    .with_filter_in("role", vec!["admin", "moderator", "user"])
    .build();

pub fn with_filter_not_in( self, key: impl Into<String>, values: Vec<impl Into<String>>, ) -> Self

Adds a NOT IN filter condition with multiple values.

Arguments

• key - Column name to filter on
• values - Vector of values to exclude

Examples

use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder};

#[derive(Serialize, Default)]
struct User {
    name: String,
    role: String,
}

let params = QueryParamsBuilder::<User>::new()
    .with_filter_not_in("role", vec!["banned", "suspended"])
    .build();

pub fn with_filter( self, key: impl Into<String>, value: Option<impl Into<String>>, ) -> Self

Adds a simple equality filter condition (backward compatible).

Arguments

• key - Column name to filter on
• value - Optional value to filter by

Details

Only adds the filter if the column exists in the model struct. Logs a warning if tracing is enabled and the column is invalid. This method maintains backward compatibility with the original API.

Examples

use std::any::Any;
use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String,
    status: String,
    role: String
}

let params = QueryParamsBuilder::<UserExample>::new()
    .with_filter("status", Some("active"))
    .with_filter("role", Some("admin"))
    .build();

pub fn with_filters( self, filters: HashMap<impl Into<String>, Option<impl Into<String>>>, ) -> Self

Adds multiple filter conditions from a HashMap (backward compatible).

Arguments

• filters - HashMap of column names and their filter values (equality only)

Details

Only adds filters for columns that exist in the model struct. Logs a warning if tracing is enabled and a column is invalid.

Examples

use std::collections::HashMap;
use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String,
    status: String,
    role: String
}

let mut filters = HashMap::new();
filters.insert("status", Some("active"));
filters.insert("role", Some("admin"));

let params = QueryParamsBuilder::<UserExample>::new()
    .with_filters(filters)
    .build();

pub fn with_filter_conditions( self, filters: HashMap<impl Into<String>, QueryFilterCondition>, ) -> Self

Adds multiple filter conditions with operators from a HashMap.

Arguments

• filters - HashMap of column names and their FilterConditions

Details

Only adds filters for columns that exist in the model struct. Logs a warning if tracing is enabled and a column is invalid.

Examples

use std::collections::HashMap;
use serde::{Serialize};
use sqlx_paginated::{QueryParamsBuilder, QueryFilterCondition, QueryFilterOperator};

#[derive(Serialize, Default)]
struct Product {
    name: String,
    price: f64,
    stock: i32,
}

let mut filters = HashMap::new();
filters.insert("price", QueryFilterCondition::greater_than("10.00"));
filters.insert("stock", QueryFilterCondition::less_or_equal("100"));

let params = QueryParamsBuilder::<Product>::new()
    .with_filter_conditions(filters)
    .build();

pub fn build(self) -> QueryParams<'q, T>

Builds and returns the final QueryParams.

Returns

Returns the constructed QueryParams<T> with all the configured parameters.

Examples

use chrono::{DateTime, Utc};
use sqlx_paginated::{QueryParamsBuilder, QuerySortDirection};
use serde::{Serialize};

#[derive(Serialize, Default)]
struct UserExample {
    name: String,
    status: String,
    email: String,
    created_at: DateTime<Utc>
}

let params = QueryParamsBuilder::<UserExample>::new()
    .with_pagination(1, 20)
    .with_sort("created_at", QuerySortDirection::Descending)
    .with_search("john", vec!["name", "email"])
    .with_filter("status", Some("active"))
    .build();

Trait Implementations

impl<T: Default + Serialize> Default for QueryParamsBuilder<'_, T>

fn default() -> Self

Returns the “default value” for a type.