Struct QueryRequest 

pub struct QueryRequest<TD: TableDefinition, T = (), O: OutputFormat = Raw, F: FilterState = NoFilter, P: ProjectionState = NoProjection> { /* private fields */ }

Builder for a DynamoDB Query request.

Constructed via DynamoDBItemOp::query / DynamoDBItemOp::query_index (typed, with a concrete T) or QueryRequest::new / QueryRequest::new_index (stand-alone, raw output). The builder provides:

• Output format — the result can be deserialized into T. Call .raw() to receive untyped Item<TD> values instead (one-way). Calling .project() also forces raw output.
• Filter — call .filter() to add a server-side filter expression. DynamoDB accepts a single filter expression per request, so this can only be called once.
• Projection — call .project() to limit which attributes are returned. This can only be called once.

Use .all() to collect all pages into a Vec, or .stream() for lazy page-by-page iteration.

Errors

Returns Err if any DynamoDB page request fails or if deserialization of any returned item fails.

Examples

use dynamodb_facade::{DynamoDBItemOp, Condition, KeyCondition};

// Simple query
let enrollments /* : Vec<Enrollment> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .all()
        .await?;

// Query with a filter
let advanced /* : Vec<Enrollment> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .filter(Condition::gt("progress", 0.5))
        .all()
        .await?;

// Query a secondary index
let users /* : Vec<User> */ = User::query_index::<EmailIndex>(
    client,
    KeyCondition::pk("alice@example.com".to_owned()),
)
.all()
.await?;

Implementations

impl<TD: TableDefinition> QueryRequest<TD>

pub fn new( client: Client, key_condition: KeyCondition<'_, TD::KeySchema, impl KeyConditionState>, ) -> Self

Creates a stand-alone QueryRequest against the table’s primary key schema.

Output is raw (T = (), O = Raw). For typed access, prefer DynamoDBItemOp::query instead.

Examples

use dynamodb_facade::{QueryRequest, KeyCondition};

let items = QueryRequest::<PlatformTable>::new(
    client,
    KeyCondition::pk("USER#user-1".to_owned()),
)
.all()
.await?;

pub fn new_index<I: IndexDefinition<TD>>( client: Client, key_condition: KeyCondition<'_, I::KeySchema, impl KeyConditionState>, ) -> Self

Creates a stand-alone QueryRequest against a secondary index.

Output is raw (T = (), O = Raw). For typed access, prefer DynamoDBItemOp::query_index instead.

Examples

use dynamodb_facade::{QueryRequest, KeyCondition};

let items = QueryRequest::<PlatformTable>::new_index::<EmailIndex>(
    client,
    KeyCondition::pk("alice@example.com".to_owned()),
)
.all()
.await?;

impl<TD: TableDefinition, T, O: OutputFormat, F: FilterState, P: ProjectionState> QueryRequest<TD, T, O, F, P>

pub fn consistent_read(self) -> Self

Enables strongly consistent reads for this query.

By default DynamoDB uses eventually consistent reads. Enabling consistent reads guarantees the most up-to-date data but consumes twice the read capacity units and is not supported on Global Secondary Indexes.

Examples

use dynamodb_facade::DynamoDBItemOp;

let enrollments /* : Vec<Enrollment> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .consistent_read()
        .all()
        .await?;

pub fn limit(self, limit: i32) -> Self

Sets the maximum number of items to evaluate per page.

Note that DynamoDB evaluates up to limit items before applying any filter expression, so the number of items returned may be less than limit when a filter is active. Pagination continues automatically when using .all() or .stream().

Examples

use dynamodb_facade::DynamoDBItemOp;

// Evaluate at most 10 items per page
let enrollments /* : Vec<Enrollment> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .limit(10)
        .all()
        .await?;

pub fn reverse(self) -> Self

Change the sort order of results by sort key by setting scan_index_forward = false.

Examples

use dynamodb_facade::DynamoDBItemOp;

// Return enrollments in reverse sort-key order
let enrollments /* : Vec<Enrollment> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .reverse()
        .all()
        .await?;

pub fn into_inner(self) -> QueryFluentBuilder

Consumes the builder and returns the underlying SDK QueryFluentBuilder.

Use this escape hatch when you need to set options not exposed by this facade, or when integrating with code that expects the raw SDK builder.

Examples

use dynamodb_facade::DynamoDBItemOp;

let sdk_builder =
    Enrollment::query(client, Enrollment::key_condition("user-1")).into_inner();
// configure sdk_builder further, then call .send().await

impl<TD: TableDefinition, T, O: OutputFormat, P: ProjectionState> QueryRequest<TD, T, O, NoFilter, P>

pub fn filter( self, filter: Condition<'_>, ) -> QueryRequest<TD, T, O, AlreadyHasFilter, P>

Adds a filter expression applied after the key condition.

DynamoDB accepts a single filter expression per request, so this method can only be called once. The filter is evaluated server-side after items are read but before they are returned, so it does not reduce read capacity consumption.

Examples

use dynamodb_facade::{DynamoDBItemOp, Condition};

// Query enrollments with progress above 50%
let advanced /* : Vec<Enrollment> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .filter(Condition::gt("progress", 0.5))
        .all()
        .await?;

impl<TD: TableDefinition, T, O: OutputFormat, F: FilterState> QueryRequest<TD, T, O, F, NoProjection>

pub fn project( self, projection: Projection<'_, TD>, ) -> QueryRequest<TD, T, Raw, F, AlreadyHasProjection>

Applies a projection expression, limiting the attributes returned per item.

This method can only be called once. It forces the output to raw Item<TD> because projected results may not contain all fields required for deserialization into T.

Examples

use dynamodb_facade::{DynamoDBItemOp, Projection};

// Fetch only the "progress" attribute for each enrollment
let partial /* : Vec<Item<PlatformTable>> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .project(Projection::new(["progress"]))
        .all()
        .await?;
// partial: contains only "PK", "SK" and "progress"

impl<TD: TableDefinition, T, F: FilterState, P: ProjectionState> QueryRequest<TD, T, Typed, F, P>

pub fn raw(self) -> QueryRequest<TD, T, Raw, F, P>

Switches the output format from Typed to Raw.

After calling .raw(), .all() returns Vec<Item<TD>> and .stream() yields Result<Vec<Item<TD>>> (pages of raw items) instead of the typed equivalents. This transition is one-way.

Examples

use dynamodb_facade::DynamoDBItemOp;

let raw_items /* : Vec<Item<PlatformTable>> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .raw()
        .all()
        .await?;

impl<TD: TableDefinition, T: DynamoDBItem<TD> + DeserializeOwned, F: FilterState, P: ProjectionState> QueryRequest<TD, T, Typed, F, P>

pub async fn all(self) -> Result<Vec<T>>

Executes the query, collecting all pages and returning items deserialized as T.

Automatically follows pagination tokens until all matching items have been retrieved. For large result sets, prefer .stream() to avoid loading everything into memory at once.

Errors

Returns Err if any DynamoDB page request fails or if deserialization of any item fails.

Examples

use dynamodb_facade::DynamoDBItemOp;

let enrollments /* : Vec<Enrollment> */ =
    Enrollment::query(client, Enrollment::key_condition("user-1"))
        .all()
        .await?;

pub fn stream(self) -> impl Stream<Item = Result<Vec<T>>>

Executes the query as a lazy async stream, yielding one page at a time.

Each element yielded by the stream is a Vec<T> representing one page of results deserialized as T. Pages are fetched on demand as the stream is consumed. Use this for large result sets where loading everything into memory at once is undesirable.

Examples

use dynamodb_facade::DynamoDBItemOp;
use futures_util::StreamExt;
use std::pin::pin;

let stream = Enrollment::query(client, Enrollment::key_condition("user-1"))
    .stream();
// Must pin the stream
let mut stream = pin!(stream);

while let Some(result) = stream.next().await {
    let page /* : Vec<Enrollment> */ = result?;
    for enrollment in page {
        let _ = enrollment;
    }
}

impl<TD: TableDefinition, T, F: FilterState, P: ProjectionState> QueryRequest<TD, T, Raw, F, P>

pub async fn all(self) -> Result<Vec<Item<TD>>>

Executes the query, collecting all pages and returning raw item maps.

Automatically follows pagination tokens until all matching items have been retrieved.

Errors

Returns Err if any DynamoDB page request fails.

Examples

use dynamodb_facade::{DynamoDBItemOp, QueryRequest, KeyCondition};

let raw_items = QueryRequest::<PlatformTable>::new(
    client,
    KeyCondition::pk("USER#user-1".to_owned()),
)
.all()
.await?;
// raw_items: Vec<Item<PlatformTable>>

pub fn stream(self) -> impl Stream<Item = Result<Vec<Item<TD>>>>

Executes the query as a lazy async stream, yielding one page of raw item maps at a time.

Each element yielded by the stream is a Vec<Item<TD>> representing one page of results. Pages are fetched on demand as the stream is consumed.

Examples

use dynamodb_facade::{QueryRequest, KeyCondition};
use futures_util::StreamExt;
use std::pin::pin;

let stream = QueryRequest::<PlatformTable>::new(
    client,
    KeyCondition::pk("USER#user-1".to_owned()),
)
.stream();
// Must pin the stream
let mut stream = pin!(stream);

while let Some(result) = stream.next().await {
    let page /* : Vec<Item<PlatformTable>> */ = result?;
    for item in page {
        let _ = item;
    }
}