Struct Condition 

pub struct Condition<'a>(/* private fields */);

Composable DynamoDB condition expression builder.

Condition<'a> represents a single DynamoDB condition expression that can be used as a ConditionExpression, or FilterExpression. Conditions are built from static constructor methods and composed with the & (BitAnd), | (BitOr), and ! (Not) operators, or with the variadic and and or methods.

Attribute names that are DynamoDB reserved words are automatically escaped with # expression attribute name placeholders. You never need to manage placeholder names manually.

Display

Condition implements Display in two modes:

• Default ({}) — resolves all placeholders inline for human-readable debugging: PK = S("USER#user-1")
• Alternate ({:#}) — shows the raw expression with #name / :value placeholders and separate name/value maps, matching what DynamoDB receives: PK = :c0\n values: { :c0 = S("USER#user-1") }

Examples

Simple equality condition:

use dynamodb_facade::Condition;

let cond = Condition::eq("role", "instructor");
assert_eq!(format!("{cond}"), r#"role = S("instructor")"#);

Composing conditions with operators:

use dynamodb_facade::Condition;

let cond = Condition::exists("email")
    & !Condition::eq("role", "banned");
assert_eq!(
    format!("{cond}"),
    r#"(attribute_exists(email) AND (NOT role = S("banned")))"#
);

Variadic composition:

use dynamodb_facade::{Comparison, Condition};

let cond = Condition::and([
    Condition::eq("role", "student"),
    Condition::size_gt("tags", 0),
    Condition::exists("enrolled_at"),
]);
assert_eq!(
    format!("{cond}"),
    r#"(role = S("student") AND size(tags) > N("0") AND attribute_exists(enrolled_at))"#
);

Implementations

impl<'a> Condition<'a>

pub fn cmp( attr: impl Into<Cow<'a, str>>, cmp: Comparison, value: impl IntoAttributeValue, ) -> Self

Creates a condition that compares an attribute to a value using the given operator.

This is the general form underlying the convenience methods eq, ne, lt, le, gt, and ge.

Examples

use dynamodb_facade::{Comparison, Condition};

let cond = Condition::cmp("progress", Comparison::Ge, 0.75);
assert_eq!(format!("{cond}"), r#"progress >= N("0.75")"#);

pub fn eq(attr: impl Into<Cow<'a, str>>, value: impl IntoAttributeValue) -> Self

Creates an equality condition: attr = value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::eq("role", "instructor");
assert_eq!(format!("{cond}"), r#"role = S("instructor")"#);

pub fn ne(attr: impl Into<Cow<'a, str>>, value: impl IntoAttributeValue) -> Self

Creates a not-equal condition: attr <> value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::ne("role", "banned");
assert_eq!(format!("{cond}"), r#"role <> S("banned")"#);

pub fn lt(attr: impl Into<Cow<'a, str>>, value: impl IntoAttributeValue) -> Self

Creates a less-than condition: attr < value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::lt("progress", 1.0);
assert_eq!(format!("{cond}"), r#"progress < N("1")"#);

pub fn le(attr: impl Into<Cow<'a, str>>, value: impl IntoAttributeValue) -> Self

Creates a less-than-or-equal condition: attr <= value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::le("max_enrollments", 100);
assert_eq!(format!("{cond}"), r#"max_enrollments <= N("100")"#);

pub fn gt(attr: impl Into<Cow<'a, str>>, value: impl IntoAttributeValue) -> Self

Creates a greater-than condition: attr > value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::gt("enrolled_at", 0);
assert_eq!(format!("{cond}"), r#"enrolled_at > N("0")"#);

pub fn ge(attr: impl Into<Cow<'a, str>>, value: impl IntoAttributeValue) -> Self

Creates a greater-than-or-equal condition: attr >= value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::ge("progress", 0.5);
assert_eq!(format!("{cond}"), r#"progress >= N("0.5")"#);

pub fn between( attr: impl Into<Cow<'a, str>>, low: impl IntoAttributeValue, high: impl IntoAttributeValue, ) -> Self

Creates a range condition: attr BETWEEN low AND high (inclusive).

Examples

use dynamodb_facade::Condition;

let cond = Condition::between("enrolled_at", 1_700_000_000, 1_800_000_000);
assert_eq!(
    format!("{cond}"),
    r#"enrolled_at BETWEEN N("1700000000") AND N("1800000000")"#
);

pub fn is_in( attr: impl Into<Cow<'a, str>>, values: impl IntoIterator<Item = impl IntoAttributeValue>, ) -> Self

Creates a membership condition: attr IN (val1, val2, ...).

Examples

use dynamodb_facade::Condition;

let cond = Condition::is_in("role", ["student", "instructor"]);
assert_eq!(
    format!("{cond}"),
    r#"role IN (S("student"), S("instructor"))"#
);

pub fn exists(attr: impl Into<Cow<'a, str>>) -> Self

Creates an attribute-existence condition: attribute_exists(attr).

Evaluates to true when the named attribute is present on the item, regardless of its value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::exists("email");
assert_eq!(format!("{cond}"), "attribute_exists(email)");

pub fn not_exists(attr: impl Into<Cow<'a, str>>) -> Self

Creates an attribute-absence condition: attribute_not_exists(attr).

Evaluates to true when the named attribute is absent from the item. Commonly used to implement create-only semantics (e.g. “put only if item does not exist”).

Examples

use dynamodb_facade::Condition;

let cond = Condition::not_exists("deleted_at");
assert_eq!(format!("{cond}"), "attribute_not_exists(deleted_at)");

pub fn begins_with( attr: impl Into<Cow<'a, str>>, prefix: impl IntoAttributeValue, ) -> Self

Creates a prefix condition: begins_with(attr, prefix).

Evaluates to true when the string attribute starts with the given prefix.

Examples

use dynamodb_facade::Condition;

let cond = Condition::begins_with("SK", "ENROLL#");
assert_eq!(format!("{cond}"), r#"begins_with(SK, S("ENROLL#"))"#);

pub fn contains( attr: impl Into<Cow<'a, str>>, value: impl IntoAttributeValue, ) -> Self

Creates a containment condition: contains(attr, value).

For string attributes, evaluates to true when the attribute contains value as a substring. For set attributes, evaluates to true when the set contains value as an element.

Examples

use dynamodb_facade::Condition;

let cond = Condition::contains("tags", "rust");
assert_eq!(format!("{cond}"), r#"contains(tags, S("rust"))"#);

pub fn size_cmp( attr: impl Into<Cow<'a, str>>, cmp: Comparison, value: usize, ) -> Self

Creates a size comparison condition: size(attr) <op> value.

Compares the size of an attribute (string length, list/map/set cardinality, or binary length) to a usize using the given Comparison operator. This is the general form underlying the convenience methods size_eq, size_ne, size_lt, size_le, size_gt, and size_ge.

Examples

use dynamodb_facade::{Comparison, Condition};

let cond = Condition::size_cmp("tags", Comparison::Ge, 1);
assert_eq!(format!("{cond}"), r#"size(tags) >= N("1")"#);

pub fn size_eq(attr: impl Into<Cow<'a, str>>, value: usize) -> Self

Creates a size-equal condition: size(attr) = value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::size_eq("tags", 3);
assert_eq!(format!("{cond}"), r#"size(tags) = N("3")"#);

pub fn size_ne(attr: impl Into<Cow<'a, str>>, value: usize) -> Self

Creates a size-not-equal condition: size(attr) <> value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::size_ne("tags", 0);
assert_eq!(format!("{cond}"), r#"size(tags) <> N("0")"#);

pub fn size_lt(attr: impl Into<Cow<'a, str>>, value: usize) -> Self

Creates a size-less-than condition: size(attr) < value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::size_lt("content", 1000);
assert_eq!(format!("{cond}"), r#"size(content) < N("1000")"#);

pub fn size_le(attr: impl Into<Cow<'a, str>>, value: usize) -> Self

Creates a size-less-than-or-equal condition: size(attr) <= value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::size_le("bio", 500);
assert_eq!(format!("{cond}"), r#"size(bio) <= N("500")"#);

pub fn size_gt(attr: impl Into<Cow<'a, str>>, value: usize) -> Self

Creates a size-greater-than condition: size(attr) > value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::size_gt("tags", 0);
assert_eq!(format!("{cond}"), r#"size(tags) > N("0")"#);

pub fn size_ge(attr: impl Into<Cow<'a, str>>, value: usize) -> Self

Creates a size-greater-than-or-equal condition: size(attr) >= value.

Examples

use dynamodb_facade::Condition;

let cond = Condition::size_ge("email", 5);
assert_eq!(format!("{cond}"), r#"size(email) >= N("5")"#);

pub fn and(conditions: impl IntoIterator<Item = Condition<'a>>) -> Self

Creates a condition that is true when all of the given conditions are true.

Nested And conditions are flattened automatically. An empty iterator produces a no-op condition that renders as <none> and is silently dropped when applied to a builder.

For combining a fixed number of conditions, the & operator is more ergonomic.

Examples

use dynamodb_facade::Condition;

let cond = Condition::and([
    Condition::exists("email"),
    Condition::eq("role", "student"),
    Condition::gt("enrolled_at", 0),
]);
assert_eq!(
    format!("{cond}"),
    r#"(attribute_exists(email) AND role = S("student") AND enrolled_at > N("0"))"#
);

Empty iterator produces a no-op:

use dynamodb_facade::Condition;

let cond = Condition::and([] as [Condition; 0]);
assert_eq!(format!("{cond}"), "<none>");

The & operator produce the same result:

use dynamodb_facade::Condition;

let cond1 = Condition::and([
    Condition::exists("email"),
    Condition::eq("role", "student"),
    Condition::gt("enrolled_at", 0),
]);

let cond2 = Condition::exists("email")
    & Condition::eq("role", "student")
    & Condition::gt("enrolled_at", 0);
assert_eq!(format!("{cond1}"), format!("{cond2}"));

pub fn or(conditions: impl IntoIterator<Item = Condition<'a>>) -> Self

Creates a condition that is true when any of the given conditions is true.

Nested Or conditions are flattened automatically. An empty iterator produces a no-op condition that renders as <none> and is silently dropped when applied to a builder.

For combining a fixed number of conditions, the | operator is more ergonomic.

Examples

use dynamodb_facade::Condition;

let cond = Condition::or([
    Condition::not_exists("deleted_at"),
    Condition::eq("role", "admin"),
]);
assert_eq!(
    format!("{cond}"),
    r#"(attribute_not_exists(deleted_at) OR role = S("admin"))"#
);

Empty iterator produces a no-op:

use dynamodb_facade::Condition;

let cond = Condition::or([] as [Condition; 0]);
assert_eq!(format!("{cond}"), "<none>");

The | operator produce the same result:

use dynamodb_facade::Condition;

let cond1 = Condition::or([
    Condition::not_exists("deleted_at"),
    Condition::eq("role", "admin"),
]);

let cond2 = Condition::not_exists("deleted_at")
    | Condition::eq("role", "admin");
assert_eq!(format!("{cond1}"), format!("{cond2}"));

Trait Implementations

impl<'a> BitAnd for Condition<'a>

Combines two conditions with AND: lhs & rhs.

Equivalent to Condition::and([lhs, rhs]). Nested And conditions are flattened automatically.

Examples

use dynamodb_facade::Condition;

let cond = Condition::exists("email") & Condition::eq("role", "student");
assert!(format!("{cond}").contains("AND"));
assert_eq!(
    format!("{cond}"),
    r#"(attribute_exists(email) AND role = S("student"))"#
);

type Output = Condition<'a>

The resulting type after applying the & operator.

fn bitand(self, rhs: Self) -> Self::Output

Performs the & operation.

impl<'a> BitOr for Condition<'a>

Combines two conditions with OR: lhs | rhs.

Equivalent to Condition::or([lhs, rhs]). Nested Or conditions are flattened automatically.

Examples

use dynamodb_facade::Condition;

let cond = Condition::not_exists("deleted_at") | Condition::eq("role", "admin");
assert_eq!(
    format!("{cond}"),
    r#"(attribute_not_exists(deleted_at) OR role = S("admin"))"#
);

type Output = Condition<'a>

The resulting type after applying the | operator.

fn bitor(self, rhs: Self) -> Self::Output

Performs the | operation.

impl<'a> Clone for Condition<'a>

fn clone(&self) -> Condition<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Condition<'a>

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

Formats the value using the given formatter.

impl Display for Condition<'_>

Formats the condition for display.

Two modes are supported:

• Default ({}) — resolves all #name and :value placeholders inline, producing a human-readable string useful for debugging: PK = S("USER#user-1")
• Alternate ({:#}) — shows the raw DynamoDB expression with placeholder names, followed by the name and value maps on separate lines. This matches what is actually sent to DynamoDB: PK = :c0\n values: { :c0 = S("USER#user-1") }

An empty condition (e.g. Condition::and([])) renders as <none> in both modes.

Examples

use dynamodb_facade::Condition;

let cond = Condition::eq("PK", "USER#user-1");

// Default: placeholders resolved inline.
assert_eq!(format!("{cond}"), r#"PK = S("USER#user-1")"#);

// Alternate: raw expression + maps.
assert_eq!(format!("{cond:#}"), "PK = :c0\n  values: { :c0 = S(\"USER#user-1\") }");

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

Formats the value using the given formatter.

impl<'a> Not for Condition<'a>

Negates a condition: NOT cond.

Applying ! twice cancels out — !!cond returns the original condition.

Examples

use dynamodb_facade::Condition;

let cond = !Condition::eq("role", "banned");
assert_eq!(format!("{cond}"), r#"(NOT role = S("banned"))"#);

// Double negation cancels out.
let cond = !!Condition::exists("email");
assert_eq!(format!("{cond}"), "attribute_exists(email)");

type Output = Condition<'a>

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.