Struct ScanRequest 

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

Builder for a DynamoDB Scan request.

Constructed via DynamoDBItemOp::scan / DynamoDBItemOp::scan_index (typed, with a concrete T) or ScanRequest::new / ScanRequest::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.

Note: Scans read every item in the table (or index) and are significantly more expensive than queries. Prefer QueryRequest when possible.

Errors

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

Examples

use dynamodb_facade::{DynamoDBItemOp, Condition};

// Simple scan
let all_users /* : Vec<User> */ = User::scan(client).all().await?;

// Scan with a filter
let instructors /* : Vec<User> */ = User::scan(client)
    .filter(Condition::eq("role", "instructor"))
    .all()
    .await?;

Implementations

impl<TD: TableDefinition> ScanRequest<TD>

pub fn new(client: Client) -> Self

Creates a stand-alone ScanRequest against the full table with raw output.

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

Examples

use dynamodb_facade::ScanRequest;

let items = ScanRequest::<PlatformTable>::new(client).all().await?;

pub fn new_index<I: IndexDefinition<TD>>(client: Client) -> Self

Creates a stand-alone ScanRequest scoped to a secondary index.

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

Examples

use dynamodb_facade::ScanRequest;

let items = ScanRequest::<PlatformTable>::new_index::<TypeIndex>(client)
    .all()
    .await?;

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

pub fn consistent_read(self) -> Self

Enables strongly consistent reads for this scan.

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 users /* : Vec<User> */ = User::scan(client).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;

let users /* : Vec<User> */ = User::scan(client).limit(100).all().await?;

pub fn into_inner(self) -> ScanFluentBuilder

Consumes the builder and returns the underlying SDK ScanFluentBuilder.

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 = User::scan(client).into_inner();
// configure sdk_builder further, then call .send().await

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

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

Adds a filter expression applied after items are read from the table.

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};

let instructors /* : Vec<User> */ = User::scan(client)
    .filter(Condition::eq("role", "instructor"))
    .all()
    .await?;

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

pub fn project( self, projection: Projection<'_, TD>, ) -> ScanRequest<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 "name" attribute for each user
let partial = User::scan(client)
    .project(Projection::new(["name"]))
    .all()
    .await?;
// partial: Vec<Item<PlatformTable>>
// with only "PK", "SK" and "name"

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

pub fn raw(self) -> ScanRequest<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 = User::scan(client).raw().all().await?;
// raw_items: Vec<Item<PlatformTable>>

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

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

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

Automatically follows pagination tokens until all matching items have been retrieved. For large tables, 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 all_users /* : Vec<User> */ = User::scan(client).all().await?;

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

Executes the scan 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 tables where loading everything into memory at once is undesirable.

Examples

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

let stream = User::scan(client).stream();
// Must pin the stream
let mut stream = pin!(stream);

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

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

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

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

Automatically follows pagination tokens until all items have been retrieved.

Errors

Returns Err if any DynamoDB page request fails.

Examples

use dynamodb_facade::ScanRequest;

let items = ScanRequest::<PlatformTable>::new(client).all().await?;
// items: Vec<Item<PlatformTable>>

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

Executes the scan 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::ScanRequest;
use futures_util::StreamExt;
use std::pin::pin;

let stream = ScanRequest::<PlatformTable>::new(client).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;
    }
}