Struct QueryBuilder 

pub struct QueryBuilder { /* private fields */ }

Fluent query builder

Implementations

impl QueryBuilder

pub fn new(resource: impl Into<String>) -> Self

Create a new query builder for a resource

Examples

let query = QueryBuilder::new("Property")
    .filter("City eq 'Austin' and ListPrice gt 500000")
    .top(10)
    .build()?;

pub fn by_key(resource: impl Into<String>, key: impl Into<String>) -> Self

Create a query builder for direct key access

Direct key access is more efficient than using filters for single-record lookups. Returns a single object instead of an array wrapped in {"value": [...]}.

Key access supports $select and $expand, but not $filter, $top, $skip, $orderby, or $apply.

Examples

// Basic key access
let query = QueryBuilder::by_key("Property", "12345")
    .build()?;

// With select
let query = QueryBuilder::by_key("Property", "12345")
    .select(&["ListingKey", "City", "ListPrice"])
    .build()?;

// With expand
let query = QueryBuilder::by_key("Property", "12345")
    .expand(&["ListOffice", "ListAgent"])
    .build()?;

pub fn filter(self, expression: impl Into<String>) -> Self

Add an OData filter expression

Pass a complete OData filter string. The library does not parse or validate the filter - it simply URL-encodes it and adds it to the query.

Examples

// Simple equality
let query = QueryBuilder::new("Property")
    .filter("City eq 'Austin'")
    .build()?;

// Complex conditions
let query = QueryBuilder::new("Property")
    .filter("City eq 'Austin' and ListPrice gt 500000")
    .build()?;

// Enumeration with 'has' operator
let query = QueryBuilder::new("Property")
    .filter("Appliances has PropertyEnums.Appliances'Dishwasher'")
    .build()?;

// Collection operations
let query = QueryBuilder::new("Property")
    .filter("OpenHouse/any(x:x/OpenHouseDate eq 2025-06-01)")
    .build()?;

pub fn apply(self, expression: impl Into<String>) -> Self

Add an OData apply expression for aggregations

⚠️ Server Compatibility Required: This feature requires server support for OData v4.0 Aggregation Extensions. Not all RESO servers support $apply. If unsupported, the server will return a 400 error.

Pass a complete OData apply string. The library does not parse or validate the apply expression - it simply URL-encodes it and adds it to the query.

Examples

// Group by city with count
let query = QueryBuilder::new("Property")
    .apply("groupby((City), aggregate($count as Count))")
    .build()?;

// Group by multiple fields
let query = QueryBuilder::new("Property")
    .apply("groupby((City, PropertyType), aggregate($count as Count))")
    .build()?;

Alternative for servers without $apply support

If your server doesn’t support aggregation, use multiple filtered queries instead:

let statuses = ["Active", "Pending", "Closed"];
for status in statuses {
    let query = QueryBuilder::new("Property")
        .filter(format!("StandardStatus eq '{}'", status))
        .count()
        .build()?;

    let response = client.execute(&query).await?;
    let count = response.as_u64().unwrap_or(0);
    println!("{}: {}", status, count);
}

pub fn select(self, fields: &[&str]) -> Self

Select specific fields

Examples

let query = QueryBuilder::new("Property")
    .select(&["ListingKey", "City", "ListPrice"])
    .build()?;

pub fn expand(self, fields: &[&str]) -> Self

Expand related entities

The $expand parameter allows you to include related data in a single request, reducing the number of API calls needed. Common examples include expanding ListOffice or ListAgent for Property resources.

Note: When using $select, you must include the expanded field names in the select list, otherwise the expansion will be ignored.

Examples

// Expand a single related entity
let query = QueryBuilder::new("Property")
    .expand(&["ListOffice"])
    .build()?;

// Expand multiple related entities
let query = QueryBuilder::new("Property")
    .expand(&["ListOffice", "ListAgent"])
    .build()?;

// When using select, include expanded fields
let query = QueryBuilder::new("Property")
    .select(&["ListingKey", "City", "ListPrice", "ListOffice", "ListAgent"])
    .expand(&["ListOffice", "ListAgent"])
    .build()?;

pub fn order_by(self, field: &str, direction: &str) -> Self

Order by a field

Examples

let query = QueryBuilder::new("Property")
    .order_by("ListPrice", "desc")
    .build()?;

pub fn top(self, n: u32) -> Self

Limit number of results

Examples

let query = QueryBuilder::new("Property")
    .top(10)
    .build()?;

pub fn skip(self, n: u32) -> Self

Skip results (for pagination)

Examples

let query = QueryBuilder::new("Property")
    .skip(100)
    .top(10)
    .build()?;

pub fn with_count(self) -> Self

Include count in response

Examples

let query = QueryBuilder::new("Property")
    .filter("City eq 'Austin'")
    .with_count()
    .build()?;

pub fn count(self) -> Self

Create a count-only query

Examples

let query = QueryBuilder::new("Property")
    .filter("City eq 'Austin'")
    .count()
    .build()?;

pub fn build(self) -> Result<Query>

Build the query

Errors

Returns an error if:

• Key access is used with incompatible parameters ($filter, $top, $skip, $orderby, $apply, $count)