Struct KeyCondition 

pub struct KeyCondition<'a, KS: KeySchema, S: KeyConditionState = PkOnly>(/* private fields */);

Builder for DynamoDB key condition expressions.

KeyCondition builds the KeyConditionExpression used in Query operations. It enforces that:

1. A partition key equality condition is always provided (via pk).
2. Sort key methods (sk_eq, sk_begins_with, etc.) are only available for composite-key schemas (tables or indexes with a sort key).
3. At most one sort key condition can be added, as required by the DynamoDB API.

In practice you rarely name KS or S directly — they are inferred from the item type’s key schema when using the generated T::key_condition(pk_id) helper.

Examples

PK-only query (all enrollments for a user):

use dynamodb_facade::{KeyCondition, TableSchema};

// Targets all items with PK = "USER#user-1"
let kc = KeyCondition::<TableSchema<PlatformTable>>::pk("USER#user-1");
assert_eq!(format!("{kc}"), r#"PK = S("USER#user-1")"#);

// Or you may prefer for the same result:
use dynamodb_facade::DynamoDBItemOp;
let kc = User::key_condition("user-1");
assert_eq!(format!("{kc}"), r#"PK = S("USER#user-1")"#);

PK + SK prefix query:

use dynamodb_facade::{KeyCondition, TableSchema};

let kc = KeyCondition::<TableSchema<PlatformTable>>::pk("USER#user-1")
    .sk_begins_with("ENROLL#");
assert_eq!(format!("{kc}"), r#"(PK = S("USER#user-1") AND begins_with(SK, S("ENROLL#")))"#);

// Or you may prefer for the same result:
use dynamodb_facade::DynamoDBItemOp;
let kc = Enrollment::key_condition("user-1").sk_begins_with("ENROLL#");
assert_eq!(format!("{kc}"), r#"(PK = S("USER#user-1") AND begins_with(SK, S("ENROLL#")))"#);

Implementations

impl<'a, KS: KeySchema> KeyCondition<'a, KS>

pub fn pk(value: impl IntoAttributeValue) -> Self

Creates a key condition with a partition key equality constraint: PK = value.

This is the required starting point for all key conditions. The partition key attribute name is taken from the key schema KS at compile time.

Examples

use dynamodb_facade::{KeyCondition, TableSchema};

let kc = KeyCondition::<TableSchema<PlatformTable>>::pk("USER#user-1");
assert_eq!(format!("{kc}"), r#"PK = S("USER#user-1")"#);

// Or you may prefer for the same result:
use dynamodb_facade::DynamoDBItemOp;
let kc = User::key_condition("user-1");
assert_eq!(format!("{kc}"), r#"PK = S("USER#user-1")"#);

impl<'a, KS: CompositeKeySchema> KeyCondition<'a, KS>

pub fn sk_eq( self, value: impl IntoAttributeValue, ) -> KeyCondition<'a, KS, WithSk>

Adds a sort key equality constraint: SK = value.

Examples

use dynamodb_facade::DynamoDBItemOp;
let kc = Enrollment::key_condition("user-1").sk_eq("ENROLL#course-42");
assert_eq!(format!("{kc}"), r#"(PK = S("USER#user-1") AND SK = S("ENROLL#course-42"))"#);

pub fn sk_lt( self, value: impl IntoAttributeValue, ) -> KeyCondition<'a, KS, WithSk>

Adds a sort key less-than constraint: SK < value.

Examples

use dynamodb_facade::DynamoDBItemOp;

let kc = Enrollment::key_condition("user-1").sk_lt("ENROLL#z");
assert_eq!(format!("{kc}"), r#"(PK = S("USER#user-1") AND SK < S("ENROLL#z"))"#);

pub fn sk_le( self, value: impl IntoAttributeValue, ) -> KeyCondition<'a, KS, WithSk>

Adds a sort key less-than-or-equal constraint: SK <= value.

Examples

use dynamodb_facade::DynamoDBItemOp;

let kc = Enrollment::key_condition("user-1").sk_le("ENROLL#z");
assert_eq!(format!("{kc}"), r#"(PK = S("USER#user-1") AND SK <= S("ENROLL#z"))"#);

pub fn sk_gt( self, value: impl IntoAttributeValue, ) -> KeyCondition<'a, KS, WithSk>

Adds a sort key greater-than constraint: SK > value.

Examples

use dynamodb_facade::DynamoDBItemOp;

let kc = Enrollment::key_condition("user-1").sk_gt("ENROLL#2024");
assert_eq!(format!("{kc}"), r#"(PK = S("USER#user-1") AND SK > S("ENROLL#2024"))"#);

pub fn sk_ge( self, value: impl IntoAttributeValue, ) -> KeyCondition<'a, KS, WithSk>

Adds a sort key greater-than-or-equal constraint: SK >= value.

Examples

use dynamodb_facade::DynamoDBItemOp;

let kc = Enrollment::key_condition("user-1").sk_ge("ENROLL#2024");
assert_eq!(format!("{kc}"), r#"(PK = S("USER#user-1") AND SK >= S("ENROLL#2024"))"#);

pub fn sk_between( self, low: impl IntoAttributeValue, high: impl IntoAttributeValue, ) -> KeyCondition<'a, KS, WithSk>

Adds a sort key range constraint: SK BETWEEN low AND high (inclusive).

Examples

use dynamodb_facade::DynamoDBItemOp;

let kc = Enrollment::key_condition("user-1").sk_between("ENROLL#2024-01", "ENROLL#2024-12");
assert_eq!(
    format!("{kc}"),
    r#"(PK = S("USER#user-1") AND SK BETWEEN S("ENROLL#2024-01") AND S("ENROLL#2024-12"))"#,
);

pub fn sk_begins_with( self, prefix: impl IntoAttributeValue, ) -> KeyCondition<'a, KS, WithSk>

Adds a sort key prefix constraint: begins_with(SK, prefix).

This is the most common sort key condition for hierarchical single-table designs, where sort keys are prefixed by entity type (e.g. "ENROLL#").

Examples

use dynamodb_facade::DynamoDBItemOp;

let kc = Enrollment::key_condition("user-1").sk_begins_with("ENROLL#2025");
assert_eq!(
    format!("{kc}"),
    r#"(PK = S("USER#user-1") AND begins_with(SK, S("ENROLL#2025")))"#,
);

Trait Implementations

impl<'a, KS: Clone + KeySchema, S: Clone + KeyConditionState> Clone for KeyCondition<'a, KS, S>

fn clone(&self) -> KeyCondition<'a, KS, S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, KS: Debug + KeySchema, S: Debug + KeyConditionState> Debug for KeyCondition<'a, KS, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<KS: KeySchema, S: KeyConditionState> Display for KeyCondition<'_, KS, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.