Struct GetItemRequest 

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

Builder for a DynamoDB GetItem request.

Constructed via DynamoDBItemOp::get (typed, with a concrete T) or GetItemRequest::new (stand-alone, raw output). The builder provides:

• Output format — the result can be deserialized into T. Call .raw() to receive an untyped Item<TD> instead (one-way).
• Projection — call .project() to limit which attributes are returned. This can only be called once and automatically switches to raw output, since the projected result may not contain all fields required for deserialization.

The builder implements IntoFuture, so it can be .awaited directly without calling .execute() explicitly.

Errors

Returns Err if the DynamoDB request fails or if deserialization of the returned attributes fails.

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId};

// Simple get
let user /* : Option<User> */ = User::get(client, KeyId::pk("user-1")).await?;

// Consistent read
let user /* : Option<User> */ = User::get(client, KeyId::pk("user-1"))
    .consistent_read()
    .await?;

Implementations

impl<TD: TableDefinition> GetItemRequest<TD>

pub fn new(client: Client, key: Key<TD>) -> Self

Creates a stand-alone GetItemRequest with raw output (T = (), O = Raw).

Use this when you do not have a concrete item type and want to work with the raw Item<TD> map directly. For typed access, prefer DynamoDBItemOp::get instead.

Examples

use dynamodb_facade::{GetItemRequest, Key};

let raw_item = GetItemRequest::<PlatformTable>::new(client, key).await?;

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

pub fn consistent_read(self) -> Self

Enables strongly consistent reads for this request.

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

let user /* : Option<User> */ = User::get(client, KeyId::pk("user-1"))
    .consistent_read()
    .await?;

pub fn into_inner(self) -> GetItemFluentBuilder

Consumes the builder and returns the underlying SDK GetItemFluentBuilder.

Use this escape hatch when you need to set options not exposed by this facade, such as expression_attribute_names for a manual projection, or when integrating with code that expects the raw SDK builder.

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId};

let sdk_builder = User::get(client, KeyId::pk("user-1")).into_inner();
// configure sdk_builder further, then call .send().await

impl<TD: TableDefinition, T, O: OutputFormat> GetItemRequest<TD, T, O, NoProjection>

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

Applies a projection expression, limiting the attributes returned.

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::{AttributeDefinition, DynamoDBItemOp, KeyId, Projection};

// Fetch only the "name" and "email" attributes
let partial /* : Option<Item<PlatformTable>> */ =
    User::get(client, KeyId::pk("user-1"))
        .project(Projection::new(["name", Email::NAME]))
        .await?;
// partial: contains only "PK", "SK", "name" and "email"

impl<TD: TableDefinition, T, P: ProjectionState> GetItemRequest<TD, T, Typed, P>

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

Switches the output format from Typed to Raw.

After calling .raw(), execute returns Option<Item<TD>> instead of Option<T>. This transition is one-way — you cannot switch back to Typed.

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId};

let raw_item = User::get(client, KeyId::pk("user-1"))
    .raw()
    .await?;
// raw_item: Option<Item<PlatformTable>>
if let Some(item) = raw_item {
    let name = item.get("name");
}

impl<TD: TableDefinition, T: DynamoDBItem<TD> + DeserializeOwned, P: ProjectionState> GetItemRequest<TD, T, Typed, P>

pub fn execute(self) -> impl Future<Output = Result<Option<T>>> + Send + 'static

Sends the GetItem request and returns the item deserialized as T.

Returns Ok(None) if no item exists for the given key.

This method is also available implicitly via .await because GetItemRequest implements IntoFuture.

Errors

Returns Err if the DynamoDB request fails or if deserialization of the returned attributes fails.

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId};

let user /* : Option<User> */ = User::get(client, KeyId::pk("user-1"))
    .consistent_read()
    .execute()
    .await?;

impl<TD: TableDefinition, T, P: ProjectionState> GetItemRequest<TD, T, Raw, P>

pub fn execute( self, ) -> impl Future<Output = Result<Option<Item<TD>>>> + Send + 'static

Sends the GetItem request and returns the raw item map.

Returns Ok(None) if no item exists for the given key.

This method is also available implicitly via .await because GetItemRequest implements IntoFuture.

Errors

Returns Err if the DynamoDB request fails.

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId};

let raw = User::get(client, KeyId::pk("user-1"))
    .raw()
    .execute()
    .await?;
// raw: Option<Item<PlatformTable>>
if let Some(item) = raw {
    let name = item.get("name");
}