A DSL interface providing support for "low-level" DynamoDB filter/condition expressions. The methods and properties in this interface create boolean expressions to filter item results (e.g., in Scan or Query operations). Expressions are typically formed by getting a reference to an attribute path via the attr property and then exercising some operation or function upon it.

For example:

filter {
    attr["foo"] eq 42
}

This example creates an expression which checks whether an attribute named foo is equal to the value 42.

(Non-)Relationship to schema

The expressions formed by FilterDsl are referred to as "low-level" filter expressions. This is because they are not restricted by or adherent to any defined schema. Instead, they are a DSL convenience layer over literal DynamoDB expression strings and expression attribute value maps. As such they provide minimal type correctness and may allow you to form expressions which are invalid given the shape of your data, such as attributes which don't exist, comparisons with mismatched data types, etc.

Attributes

Every filter condition contains at least one attribute. Attributes are referenced by attribute paths, analogous to document paths in DynamoDB. Attribute paths consist of one or more elements, which are either names (e.g., of a top-level attribute or a nested key in a map attribute) or indices (i.e., into a list). The first (and often only) element of an attribute path is a name.

Getting a top-level attribute

All attribute paths start with a top-level attribute expression, created by the attr function:

attr["foo"] // References the top-level attribute "foo"

Note, the attribute foo may not exist for a given item or for an entire table.

Nesting

Sometimes values are nested inside other attributes like lists and maps. Filter expressions can operate on those nested values by forming a more detailed attribute path using the [] operator or get functions on a path.

For example, consider an item structure such as:

{
    "foo": "Hello",
    "bar": {
        "baz": [
            "Yay",
            null,
            42,
            true
        ]
    }
}

The value "Yay" can be referenced with the following DSL syntax:

attr["bar"]["baz"][0]

That is, in the top-level attribute bar, in the value keyed by baz, the element at index 0.

Equalities/inequalities

A very common filter condition is verifying whether some attribute is equal (or unequal) to another value—either a literal value or the value of another attribute. These comparisons are available by using the following functions:

• eq — checks if two values are equal (equivalent to Kotlin's == operator)

• neq — checks if two values are not equal (equivalent to Kotlin's != operator)

• lt — checks if a value is less than another value (equivalent to Kotlin's < operator)

• lte — checks if a value is less than or equal to another value (equivalent to Kotlin's <= operator)

• gt — checks if a value is greater than another value (equivalent to Kotlin's > operator)

• gte — checks if a value is greater than or equal to another value (equivalent to Kotlin's >= operator)

For example:

attr["foo"] eq 5           // Checks whether the value of attribute `foo` is `5`
attr["bar"] gt attr["baz"] // Checks whether the value of attribute `bar` is greater than attribute `baz`

Ranges and sets

Expressions can check whether some attribute value is in a given range or set of possible values. These checks are available via the isBetween or isIn functions:

// Checks whether the value of attribute `foo` is between 40 and 60 (inclusive)
attr["foo"] isIn 40..60

// Checks whether the value of attribute `foo` is either 1, 2, 4, 8, 16, or 32
attr["bar"] isIn setOf(1, 2, 4, 8, 16, 32)

// Checks whether the value of attribute `baz` is between the value of `foo` and the value of `bar`
attr["baz"].isBetween(attr["foo"], attr["bar"])

Boolean logic

The previous sections dealt with singular conditions (e.g., a == b, c in (d, e, f), etc.). But complex queries may involve multiple conditions or negative conditions akin to the boolean operations AND (&&), OR (||, and NOT (!). This logic is available via the and, or, and not functions:

and(
    attr["foo"] eq 42,
    attr["bar"] neq 42,
)

This block checks for value of the attribute foo equalling 42 and the value of attribute bar not equalling 42. This is logically equivalent to the Kotlin syntax:

(foo == 42 && bar != 42)

These boolean functions can be composed in various ways:

or(
    attr["foo"] eq "apple",
    and(
        attr["bar"] lt attr["baz"],
        attr["baz"] gte 42,
    ),
    not(
        attr["qux"] in setOf("ready", "set", "go"),
    ),
)

This complex DSL code checks that at least one of three conditions is met (boolean OR):

• The value of attribute foo is "apple"

• The value of attribute bar is less than the value of baz –and– the value of baz is greater/equal to 42

• The value of attribute qux is not one of "ready", "steady", or "go"

This is logically equivalent to the Kotlin syntax:

(foo == "apple") || (bar < baz && baz >= 42) || qux !in setOf("ready", "steady", "go")

Other functions/properties

Several additional filter expressions are possible via the following methods/properties:

• contains — Checks if a string/list attribute value contains the given value

• exists — Checks if any value (including null) exists for an attribute. The low-level DynamoDB function for this is attribute_exists.

• notExists — Checks if no value is present for an attribute (i.e., the attribute is "undefined" for an item). The low-level DynamoDB function for this is attribute_not_exists.

• isOfType — Checks if an attribute value is of the given type. The low-level DynamoDB function for this is attribute_type.

• size — Gets the size of an attribute (e.g., number of elements in list/map/set, the length of a string, etc.)

• startsWith — Checks if a string attribute value starts with the given value. The low-level DynamoDB function for this is begins_with.

For example:

attr["foo"] contains 13 // Checks whether the value of attribute `foo` contains the value `13`
attr["bar"].exists()    // Checks whether any value exists for `bar` (including `null`)