Struct dynamodb_expression::path::Path

pub struct Path { /* private fields */ }

Represents a DynamoDB document path. For example, foo[3][7].bar[2].baz.

You can use the many methods on Path for building DynamoDB expressions. For example, .set(), .if_not_exists(), or .remove() are some methods for creating update expressions. .attribute_not_exists(), .less_than(), and .contains() are some methods for creating condition and filter expressions.

When you’re ready to build an Expression, use Expression::builder.

When used in an Expression, attribute names in a Path are automatically handled as expression attribute names, allowing for names that would not otherwise be permitted by DynamoDB. For example, foo[3][7].bar[2].baz would become something similar to #0[3][7].#1[2].#2, and the names would be in the expression_attribute_names.

See also: Element, Name, IndexedField

There are many ways to create a Path

For creating a new Path:

• Parse from a string, as seen below. This is the preferred way. The only time when other constructors are needed is when you have an attribute name with a . in it that must not be treated as a separator for sub-attributes.
• Path::new_name and Path::new_indexed_field constructors
• Path::from for converting anything that’s Into<Element> into a Path (see also: Element)

For building a Path one step at a time:

• Use the += operator
• Use the + operator
• Path::append
• Path::from_iter

Parsing

The safest way to construct a Path is to parse it. This treats . as a separator for sub-attributes, and [n] as indexes into fields.

Since . is a valid character in an attribute name, see below for examples of how to construct a Path when an attribute name contains a ..

use dynamodb_expression::{path::Element, Path};

let path: Path = "foo".parse()?;
assert_eq!(
    Path::from_iter([
        Element::new_name("foo"),
    ]),
    path,
);

let path: Path = "foo[3]".parse()?;
assert_eq!(
    Path::from_iter([
        Element::new_indexed_field("foo", 3),
    ]),
    path,
);

let path: Path = "foo[3][7]".parse()?;
assert_eq!(
    Path::from_iter([
        Element::new_indexed_field("foo", [3, 7]),
    ]),
    path,
);

let path: Path = "foo[3][7].bar".parse()?;
assert_eq!(
    Path::from_iter([
        Element::new_indexed_field("foo", [3, 7]),
        Element::new_name("bar"),
    ]),
    path,
);

let path: Path = "bar.baz".parse()?;
assert_eq!(Path::from_iter([
        Element::new_name("bar"),
        Element::new_name("baz"),
    ]),
    path,
);

let path: Path = "baz[0].foo".parse()?;
assert_eq!(
    Path::from_iter([
        Element::new_indexed_field("baz", 0),
        Element::new_name("foo"),
    ]),
    path,
);

A special case: attribute names with . in them

If you have an attribute name with a . in it, and need it to not be treated as a separator for sub-attributes (such as a domain name), you can construct the Path a using Path::new_name that element of the path using Element::new_name.

use dynamodb_expression::{path::Element, Path};

let path = Path::new_name("example.com");
assert_eq!(
    Path::from_iter([
        Element::new_name("example.com"),
    ]),
    path,
);

let path = "foo".parse::<Path>()? + Path::new_name("example.com");
assert_eq!(
    Path::from_iter([
        Element::new_name("foo"),
        Element::new_name("example.com"),
    ]),
    path,
);

let mut path: Path = "foo[3]".parse()?;
path += Element::new_name("example.com");
assert_eq!(
    Path::from_iter([
        Element::new_indexed_field("foo", 3),
        Element::new_name("example.com"),
    ]),
    path,
);

Implementations

impl Path

pub fn new_name<T>(name: T) -> Self

where T: Into<Name>,

Constructs a Path for a single attribute name (with no indexes or sub-attributes). If you have a attribute name with one or more indexes, parse it from a string, or use Path::new_indexed_field. See the Path type documentation for more examples.

This treats . as a part of the attribute name rather than as a separator for sub-attributes. To build a Path that contains a . that is treated as a separator, see the examples in the documentation on the Path type.

Examples

use dynamodb_expression::path::{Path, Element};

let path = Path::new_name("foo");
assert_eq!(
    Path::from_iter([
        Element::new_name("foo"),
    ]),
    path,
);

let path = Path::new_name("foo.bar");
assert_eq!(
    Path::from_iter([
        Element::new_name("foo.bar"),
    ]),
    path,
);

Contrast the above result of Path::new_name("foo.bar") with parsing, which treats . as a separator for sub-attributes:

let path = "foo.bar".parse().unwrap();
assert_eq!(
    Path::from_iter([
        Element::new_name("foo"),
        Element::new_name("bar"),
    ]),
    path,
);

pub fn new_indexed_field<N, I>(name: N, indexes: I) -> Self

where N: Into<Name>, I: Indexes,

Constructs a Path for an indexed field element of a document path. For example, foo[3] or foo[7][4]. If you have a attribute name with no indexes, you can pass an empty collection, parse from a string, or use Path::new_name. See the Path type documentation for more examples.

This treats . as a part of an attribute name rather than as a separator for sub-attributes. To build a Path that contains a . that is treated as a separator, see the examples in the documentation on the Path type.

The indexes parameter, here, can be an array, slice, Vec of, or single usize.

Examples

use dynamodb_expression::Path;

assert_eq!("foo[3]", Path::new_indexed_field("foo", 3).to_string());
assert_eq!("foo[3]", Path::new_indexed_field("foo", [3]).to_string());
assert_eq!("foo[3]", Path::new_indexed_field("foo", &[3]).to_string());
assert_eq!("foo[3]", Path::new_indexed_field("foo", vec![3]).to_string());

assert_eq!("foo[7][4]", Path::new_indexed_field("foo", [7, 4]).to_string());
assert_eq!("foo[7][4]", Path::new_indexed_field("foo", &[7, 4]).to_string());
assert_eq!("foo[7][4]", Path::new_indexed_field("foo", vec![7, 4]).to_string());

assert_eq!("foo", Path::new_indexed_field("foo", []).to_string());
assert_eq!("foo", Path::new_indexed_field("foo", &[]).to_string());
assert_eq!("foo", Path::new_indexed_field("foo", vec![]).to_string());

See also: IndexedField, Element::new_indexed_field

pub fn append(&mut self, other: Path)

Appends another Path to the end of this one, separated with a ..

Notice that each of these examples produces the same Path: foo[3][7].bar[2].baz

See also: Element, Name

use dynamodb_expression::{path::{Element, Name}, Path};

let mut path: Path = "foo[3][7]".parse()?;
path.append("bar[2].baz".parse()?);
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

// You can start with an empty `Path` and append one element at a time.
let mut path = Path::default();
path.append(Element::new_indexed_field("foo", [3, 7]).into());
path.append(Element::new_indexed_field("bar", 2).into());
path.append(Element::new_name("baz").into());
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

let mut path = Path::default();
path.append(("foo", [3, 7]).into());
path.append(("bar", 2).into());
path.append(Name::from("baz").into());
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

pub fn is_empty(&self) -> bool

Returns true if the Path contains no attributes.

Hint: you can use Path::append to add attributes to a Path.

impl Path

Methods related to building condition and filter expressions.

pub fn equal<T>(self, right: T) -> Condition

where T: Into<Operand>,

Check if the value at this Path is equal to the given value.

DynamoDB documentation.

pub fn not_equal<T>(self, right: T) -> Condition

where T: Into<Operand>,

Check if the value at this Path is not equal to the given value.

DynamoDB documentation.

pub fn greater_than<T>(self, right: T) -> Condition

where T: Into<Operand>,

Check if the value at this Path is greater than the given value.

DynamoDB documentation.

pub fn greater_than_or_equal<T>(self, right: T) -> Condition

where T: Into<Operand>,

Check if the value at this Path is greater than or equal to the given value.

DynamoDB documentation.

pub fn less_than<T>(self, right: T) -> Condition

where T: Into<Operand>,

Check if the value at this Path is less than the given value.

DynamoDB documentation.

pub fn less_than_or_equal<T>(self, right: T) -> Condition

where T: Into<Operand>,

Check if the value at this Path is less than or equal to the given value.

DynamoDB documentation.

pub fn between<L, U>(self, lower: L, upper: U) -> Condition

where L: Into<Operand>, U: Into<Operand>,

The DynamoDB BETWEEN operator. True if self is greater than or equal to lower, and less than or equal to upper.

See also: Between, Key::between

use dynamodb_expression::{Num, Path};

let condition = Path::new_name("age").between(Num::new(10), Num::new(90));
assert_eq!(r#"age BETWEEN 10 AND 90"#, condition.to_string());

pub fn in_<I, T>(self, items: I) -> Condition

where I: IntoIterator<Item = T>, T: Into<Operand>,

A DynamoDB IN operation. True if the value from the Operand (the op parameter) is equal to any value in the list (the items parameter).

The DynamoDB allows the list to contain up to 100 values. It must have at least 1.

See also: In

use dynamodb_expression::{condition::In, operand::Operand, Path};

let condition = "name".parse::<Path>()?.in_(["Jack", "Jill"]);
assert_eq!(r#"name IN ("Jack","Jill")"#, condition.to_string());

pub fn attribute_exists(self) -> Condition

The DynamoDB attribute_exists function. True if the item contains the attribute specified by Path.

use dynamodb_expression::Path;

let condition = Path::new_name("foo").attribute_exists();
assert_eq!("attribute_exists(foo)", condition.to_string());

pub fn attribute_not_exists(self) -> Condition

The DynamoDB attribute_not_exists function. True if the item does not contain the attribute specified by Path.

use dynamodb_expression::Path;

let condition = Path::new_name("foo").attribute_not_exists();
assert_eq!("attribute_not_exists(foo)", condition.to_string());

pub fn attribute_type(self, attribute_type: Type) -> Condition

The DynamoDB attribute_type function. True if the attribute at the specified Path is of the specified data type.

use dynamodb_expression::{condition::attribute_type::Type, Path};

let condition = Path::new_name("foo").attribute_type(Type::String);
assert_eq!("attribute_type(foo, S)", condition.to_string());

pub fn begins_with<T>(self, prefix: T) -> Condition

where T: Into<StringOrRef>,

The DynamoDB begins_with function. True if the attribute specified by the Path begins with a particular substring.

begins_with can take a string or a reference to an extended attribute value. Here’s an example.

See also: Ref

use dynamodb_expression::{condition::BeginsWith, value::Ref, Path};

let begins_with = Path::new_name("foo").begins_with("T");
assert_eq!(r#"begins_with(foo, "T")"#, begins_with.to_string());

let begins_with = Path::new_name("foo").begins_with(Ref::new("prefix"));
assert_eq!(r#"begins_with(foo, :prefix)"#, begins_with.to_string());

pub fn contains<V>(self, operand: V) -> Condition

where V: Into<Value>,

The DynamoDB contains function. True if the attribute specified by Path is one of the following:

• A String that contains a particular substring.
• A Set that contains a particular element within the set.
• A List that contains a particular element within the list.

The operand must be a String if the attribute specified by path is a String. If the attribute specified by path is a Set, the operand must be the sets element type.

See also: Contains

use dynamodb_expression::{Num, Path};

// String
let condition = "foo".parse::<Path>()?.contains("Quinn");
assert_eq!(r#"contains(foo, "Quinn")"#, condition.to_string());

// Number
let condition = "foo".parse::<Path>()?.contains(Num::new(42));
assert_eq!(r#"contains(foo, 42)"#, condition.to_string());

// Binary
let condition = "foo".parse::<Path>()?.contains(Vec::<u8>::from("fish"));
assert_eq!(r#"contains(foo, "ZmlzaA==")"#, condition.to_string());

pub fn size(self) -> Size

The DynamoDB size function. Returns a number representing an attributes size.

use dynamodb_expression::{Num, Path};

let condition = Path::new_name("foo").size().greater_than(Num::new(0));
assert_eq!("size(foo) > 0", condition.to_string());

impl Path

Methods related to building update expressions.

See also: Update

pub fn assign<T>(self, value: T) -> Assign

where T: Into<Value>,

👎Deprecated since 0.2.0-beta.6: Use .set(value) instead

pub fn set<T>(self, value: T) -> Assign

where T: Into<Value>,

Represents assigning a value of a attribute, list, or map.

See also: Update

use dynamodb_expression::{Num, Path, update::Update};

let assign = Path::new_name("name").set("Jill");
assert_eq!(r#"name = "Jill""#, assign.to_string());

let update = Update::from(assign);
assert_eq!(r#"SET name = "Jill""#, update.to_string());

pub fn math(self) -> MathBuilder

Use for doing math on a numeric attribute.

Sets this as the destination in a Math builder.

See also: Update

Examples

use dynamodb_expression::{Path, update::Update};

let math = Path::new_name("foo").math().add(4);
assert_eq!("foo = foo + 4", math.to_string());

let math = Path::new_name("foo").math().src(Path::new_name("bar")).sub(7);
assert_eq!("foo = bar - 7", math.to_string());

let update = Update::from(math);
assert_eq!("SET foo = bar - 7", update.to_string());

pub fn list_append(self) -> ListAppendBuilder

Represents an update expression to append elements to a list.

See also: Update

Examples

use dynamodb_expression::{Num, Path, update::Update};

let list_append = "foo".parse::<Path>().unwrap().list_append().list([7, 8, 9].map(Num::new));
assert_eq!("foo = list_append(foo, [7, 8, 9])", list_append.to_string());

let update = Update::from(list_append);
assert_eq!("SET foo = list_append(foo, [7, 8, 9])", update.to_string());

If you want to add the new values to the beginning of the list instead, use the .before() method.

use dynamodb_expression::{Num, Path, update::Update};

let list_append = "foo".parse::<Path>().unwrap().list_append().before().list([1, 2, 3].map(Num::new));
assert_eq!("foo = list_append([1, 2, 3], foo)", list_append.to_string());

let update = Update::from(list_append);
assert_eq!("SET foo = list_append([1, 2, 3], foo)", update.to_string());

pub fn if_not_exists(self) -> IfNotExistsBuilder

Represents an update expression to set an attribute if it doesn’t exist.

See also: Update

Examples

use dynamodb_expression::{Num, Path, update::Update};

let if_not_exists = "foo".parse::<Path>().unwrap().if_not_exists().set(Num::new(7));
assert_eq!("foo = if_not_exists(foo, 7)", if_not_exists.to_string());

let update = Update::from(if_not_exists);
assert_eq!("SET foo = if_not_exists(foo, 7)", update.to_string());

pub fn delete<T>(self, set: T) -> Delete

where T: Into<Set>,

Creates a DELETE statement for an update expression, for removing one or more items from a value that is a set.

See also: Update

Examples

use dynamodb_expression::{Path, update::Update, value::StringSet};

let delete = Path::new_name("foo").delete(StringSet::new(["a", "b", "c"]));
assert_eq!(r#"DELETE foo ["a", "b", "c"]"#, delete.to_string());

let update = Update::from(delete);
assert_eq!(r#"DELETE foo ["a", "b", "c"]"#, update.to_string());

pub fn add<T>(self, value: T) -> Add

where T: Into<AddValue>,

Represents an DynamoDB ADD statement in an update expression.

The DynamoDB documentation recommends against using ADD:

In general, we recommend using SET rather than ADD.

To increment or decrement a number value, use Path::math.

To append items to a list, use Path::list_append.

See also: AddValue, Update, Set

Examples

use dynamodb_expression::{Num, Path, update::Update};

let add = Path::new_name("foo").add(Num::from(1));
assert_eq!("ADD foo 1", add.to_string());

let update = Update::from(add);
assert_eq!("ADD foo 1", update.to_string());

pub fn remove(self) -> Remove

Creates an update expression to remove attributes from an item, or elements from a list.

See also: Remove, Update

Examples

use dynamodb_expression::{Path, update::Update};

let remove = Path::new_name("foo").remove();
assert_eq!(r#"REMOVE foo"#, remove.to_string());

let update = Update::from(remove);
assert_eq!(r#"REMOVE foo"#, update.to_string());

let remove = Path::new_indexed_field("foo", [8]).remove();
assert_eq!(r#"REMOVE foo[8]"#, remove.to_string());

let update = Update::from(remove);
assert_eq!(r#"REMOVE foo[8]"#, update.to_string());

impl Path

pub fn key(self) -> Key

Turns this Path into a Key, for building a key condition expression.

See also: Key

use dynamodb_expression::{key::KeyCondition, Expression, Num, Path};

let key_condition: KeyCondition = "id"
    .parse::<Path>()?
    .key()
    .equal(Num::new(42))
    .and("category".parse::<Path>()?.key().begins_with("hardware."));

let expression = Expression::builder().with_key_condition(key_condition).build();

Trait Implementations

impl<T> Add<T> for Path

where T: Into<Path>,

fn add(self, rhs: T) -> Self::Output

Allows for using the + operator to combine two Paths.

Notice that each of these examples produces the same path: foo[3][7].bar[2].baz

use dynamodb_expression::{path::{Element, Name}, Path};

let path: Path = "foo[3][7]".parse()?;
let path = path + "bar[2].baz".parse::<Path>()?;
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

// You can `+` anything that is `Into<Path>` (or `Into<Element>`)

let path = Path::new_indexed_field("foo", [3, 7]) +
    Element::new_indexed_field("bar", 2) +
    Element::new_name("baz");
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

let path = Path::from(("foo", [3, 7])) +
    ("bar", 2) +
    Name::from("baz");
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

type Output = Path

The resulting type after applying the + operator.

impl<T> AddAssign<T> for Path

where T: Into<Path>,

fn add_assign(&mut self, rhs: T)

Allows for using the += operator to combine two Paths.

Notice that each of these examples produces the same path: foo[3][7].bar[2].baz

use dynamodb_expression::{path::{Element, Name}, Path};

let mut path: Path = "foo[3][7]".parse()?;
path += "bar[2].baz".parse::<Path>()?;
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

// You can `+=` anything that is `Into<Path>` (or `Into<Element>`)

let mut path = Path::default();
path += Path::new_indexed_field("foo", [3, 7]);
path += Element::new_indexed_field("bar", 2);
path += Element::new_name("baz");
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

let mut path = Path::default();
path += Path::from(("foo", [3, 7]));
path += ("bar", 2);
path += Name::from("baz");
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

impl Clone for Path

fn clone(&self) -> Path

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Path

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

Formats the value using the given formatter.

impl Default for Path

fn default() -> Path

Returns the “default value” for a type.

impl Display for Path

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

Formats the value using the given formatter.

impl From<Path> for String

fn from(path: Path) -> Self

Converts to this type from the input type.

impl From<Path> for Vec<Element>

fn from(path: Path) -> Self

Converts to this type from the input type.

impl<T> From<T> for Path

where T: Into<Element>,

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T> FromIterator<T> for Path

where T: Into<Path>,

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = T>,

Comines multiple items into a single Path, with each element separated by .. Items must be Into<Path>.

Notice that each of these examples produces the same Path: foo[3][7].bar[2].baz

use dynamodb_expression::{path::Element, Path};

// `Path` items
let path: Path = [
        "foo[3][7]".parse::<Path>()?,
        "bar[2]".parse::<Path>()?,
        "baz".parse::<Path>()?,
    ]
    .into_iter()
    .collect();
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

// `Element` items
let path: Path = [
        Element::new_indexed_field("foo", [3, 7]),
        Element::new_indexed_field("bar", 2),
        Element::new_name("baz"),
    ]
    .into_iter()
    .collect();
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

// `Into<Element>` items
let path: Path = [
        ("foo", vec![3, 7]),
        ("bar", vec![2]),
        ("baz", vec![]),
    ]
    .into_iter()
    .collect();
assert_eq!("foo[3][7].bar[2].baz", path.to_string());

impl FromStr for Path

type Err = PathParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Path

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Path

fn cmp(&self, other: &Path) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Path

fn eq(&self, other: &Path) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Path

fn partial_cmp(&self, other: &Path) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TryFrom<Path> for Name

fn try_from(path: Path) -> Result<Self, Self::Error>

A Path consisting of a single, unindexed attribute can be converted into a Name.

let path: Path = "foo".parse().unwrap();
let name = Name::try_from(path).unwrap();
assert_eq!(Name::from("foo"), name);

If the Path has indexes, or has sub-attributes, it cannot be converted, and the original Path is returned.

let path: Path = "foo[0]".parse().unwrap();
let err = Name::try_from(path.clone()).unwrap_err();
assert_eq!(path, err);

let path: Path = "foo.bar".parse().unwrap();
let err = Name::try_from(path.clone()).unwrap_err();
assert_eq!(path, err);

type Error = Path

The type returned in the event of a conversion error.

impl Eq for Path

impl StructuralEq for Path

impl StructuralPartialEq for Path