Expressions

BaseExpression

class cerami.datatype.expression.BaseExpression(expression, datatype, value)

The base class for all expressions.

Expressions are objects that are generated by datatypes that are used in requests - querying, filtering, updating etc.

expression

a string representing to define the type of expression. For example, it can be “=” to perform an equality expression

datatype

a DynamoDataType that the expresion is for

value

anything that is used in the expression

expression_attribute_name

DynamoDB has a list of reserved words, but since the list is so long and impossible to remember, there are likely collisions with a table’s columns. For this reason, most DynamoDB requests has an option ExpressionAttributeNames, which is a dict which makes an arbitrary string back to the column name. The ExpressionAttributeName must start with a “#”.

For example, you may have a column called “action” (which is a reserved word). An expression_attribute_name is automatically generated that prevents an error.

expression_attribute_value_name

DynamoDB requires all of its Expressions to use a unique string that gets mapped to its ExpressionAttributeValues dict. This string must start with a “:”. All expression_attribute_value_names include the column_name of the datatype and a series of random characters to ensure there are no collisions when multiple expressions are used in a request

For example:

expression = BaseExpression("=", Parent.email, "test@test.com")
expression.expression_attribute_name # <== "#__email"
expression.expression_attribute_value_name # <== ":_email_xfdww"

Parent.query.filter(expression).build()
{
    "TableName": "people",
    "FilterExpression": "#__email = :_email_xfdww",
    "ExpressionAttributeNames": {
        "#__email": "email"
    },
    "ExpressionAttributeValues": {
        ":_email_xfdww": {
            "S": "test@test.com"
        }
    }
}

__init__(expression, datatype, value)

constructor for the BaseExpression

Parameters

• expression – a string representing to define the type of expression. For example, it can be “=” to perform an equality expression

• datatype – a DynamoDataType that the expresion is for

• value – anything that is used in the expression

attribute_map()

return the value and its condition_type by calling a Datatype Translator

This is only used by Keyable right now. But i think this should be deprecated because its confusing and doesnt really add any value

value_dict()

return the expected dict for expression-attribute-values

This is used by many of different requests when building search_attributes. Most requests require the ExpressionAttributeValue option. This will build that corresponding property for this particular expression

Returns

a dict that can be used in ExpressionAttributeValue options

For example:

expression = Expression("=", Parent.name, "Mom")
expression.value_dict() # <== {":_name_abc12":{"S": "Mom"}}

EqualityExpression

class cerami.datatype.expression.EqualityExpression(expression, datatype, value)

An expression class for performing any equality checks

They are used when filtering (greater than, less than, equals, etc.) but are also used for setting and updating attributes using the equals sign.

ArithmeticExpression

class cerami.datatype.expression.ArithmeticExpression(expression, datatype, value)

An expression class for arithmetic operations.

This is just a convenience class to logically separate its use from EqualityExpressions. This class is only used in Number datatypes and currently only in Number.add and Number.subtract

BeginsWithExpression

class cerami.datatype.expression.BeginsWithExpression(datatype, value)

A class to generate a BEGINS WITH expression for querying/scanning

When using with a QueryRequest, a BeginsWithExpression can only be used on the sort key. It cannot be used on the partition key

For example:

# You can use Person.email.begins_with instead!
expression = BeginsWithExpression(Person.email, "test")
Email.scan.filter(expression).build()
{
    "TableName": "people",
    "FilterExpression": "begins_with(#__email, :_email_xfdww)",
    "ExpressionAttributeNames": {
        "#__email": "email"
    },
    "ExpressionAttributeValues": {
        ":_email_xfdww": {
            "S": "test@test.com"
        }
    }
}

__init__(datatype, value)

constructor for BeginsWithExpression

Parameters

• datatype – a DynamoDataType that the expression is for

• value – a substring to check the column begins with

attribute_map()

return the value and its condition_type by calling a Datatype Translator

This is only used by Keyable right now. But i think this should be deprecated because its confusing and doesnt really add any value

value_dict()

return the expected dict for expression-attribute-values

This is used by many of different requests when building search_attributes. Most requests require the ExpressionAttributeValue option. This will build that corresponding property for this particular expression

Returns

a dict that can be used in ExpressionAttributeValue options

For example:

expression = Expression("=", Parent.name, "Mom")
expression.value_dict() # <== {":_name_abc12":{"S": "Mom"}}

InExpression

class cerami.datatype.expression.InExpression(datatype, value)

A class to generate an IN expression for filtering

For example:

# You can use Person.name.in_ instead!
expression = InExpression(Person.name, ["Mom", "Dad"])
Person.scan.filter(expression).build()
{
    "TableName": "people",
    "FilterExpression": "#__name IN (:_name_qmtxc, :_name_wzhlh)",
    "ExpressionAttributeNames": {
        "#__name": "name"
    },
    "ExpressionAttributeValues": {
        ":_name_qmtxc": {
            "S": "Mom"
        },
        ":_name_wzhlh": {
            "S": "Dad"
        }
    }
}

__init__(datatype, value)

constructor for InExpression

Parameters

• datatype – a DynamoDataType that the expression is for

• value – an array of values

attribute_map()

return the value and its condition_type by calling a Datatype Translator

This is only used by Keyable right now. But i think this should be deprecated because its confusing and doesnt really add any value

value_dict()

return the expected dict for expression-attribute-values

This is used by many of different requests when building search_attributes. Most requests require the ExpressionAttributeValue option. This will build that corresponding property for this particular expression. Since the value is an array, this method overrides the BaseExpression implementation.

Returns

a dict that can be used in ExpressionAttributeValue options

BetweenExpression

class cerami.datatype.expression.BetweenExpression(datatype, greater_than, less_than)

A class to generate a BETWEEN expression for querying/scanning

When using with a QueryRequest, a BetweenExpression can only be used on the sort key. It cannot be used on the partition key.

For example:

# You can use Person.age.between instead!
expression = BetweenExpression(Person.age, 10, 20)
Person.scan.filter(expression).build()
{
   "TableName": "people",
   "FilterExpression": "#__age BETWEEN :_email_xfdww AND :_email_xcaf",
   "ExpressionAttributeNames": {
        "#__email": "email",
   },
   "ExpressionAttributeValues": {
        ":_email_xfdww": {
            "N": 10,
        },
        ":_email_xcaf": {
            "N": 20,
        },
   },
}

attribute_map()

return the value and its condition_type by calling a Datatype Translator

This is only used by Keyable right now. But i think this should be deprecated because its confusing and doesnt really add any value

value_dict()

return the expected dict for expression-attribute-values

This is used by many of different requests when building search_attributes. Most requests require the ExpressionAttributeValue option. This will build that corresponding property for this particular expression. Since the value is an array, this method overrides the BaseExpression implementation.

Returns

a dict that can be used in ExpressionAttributeValue options

ListAppendExpression

class cerami.datatype.expression.ListAppendExpression(datatype, value)

A class to generate list_append expressions for UpdateRequests

When using an UpdateRequest, a ListAppendExpression can be used for any List datatype.

For example:

# you can use Person.toys.append() instead!
expression = ListAppendExpression(Person.toys, [{"color": "red", "name": "car"}])
Person.update.key(Person.email == "test@test.com").set(expression).build()
 {
     "TableName": "people",
     "ReturnValues": "ALL_NEW",
     "Key": {
         "email": {
             "S": "test@test.com"
         }
     },
     "UpdateExpression": "SET #__toys = list_append(#__toys, :_toys_ihkiy)",
     "ExpressionAttributeNames": {
         "#__toys": "toys"
     },
     "ExpressionAttributeValues": {
         ":_toys_ihkiy": {
             "L": [
                 {
                     "M": {
                         "color": {
                             "S": "red"
                         },
                         "name": {
                             "S": "car"
                         }
                     }
                 }
             ]
         }
     }
 }

__init__(datatype, value)

constructor for ListAppendExpression

Parameters

• datatype – a DynamoDataType that the expression is for

• value – a an array to append to the existing datatype column

attribute_map()

return the value and its condition_type by calling a Datatype Translator

This is only used by Keyable right now. But i think this should be deprecated because its confusing and doesnt really add any value

value_dict()

return the expected dict for expression-attribute-values

This is used by many of different requests when building search_attributes. Most requests require the ExpressionAttributeValue option. This will build that corresponding property for this particular expression

Returns

a dict that can be used in ExpressionAttributeValue options

For example:

expression = Expression("=", Parent.name, "Mom")
expression.value_dict() # <== {":_name_abc12":{"S": "Mom"}}

UpdateRemoveExpression

class cerami.datatype.expression.UpdateRemoveExpression(datatype)

A class use specifically for UpdateRequest.remove()

A remove expression does not require any values since it just needs the column_name. There isnt an example worth providing for this class. Remove expressions should really only be invoked through UpdateRequest.remove()

__init__(datatype)

Constructor for UpdateRemoveExpression

Parameters

datatype – a DynamoDataType that should be removed from a record

value_dict()

there is no value for this expression so return an empty dict

Normally, the value_dict() of an expression will return dictionary mapping the unique name to the value formatted for DynamoDB. However, an UpdateRemoveExpression has no values, which is why this returns an empty dict. Because UpdateRequest.update_expression() automatically tries to add the values for any expression, it is important this returns an empty dict so it does not break DynamoDB when submitting the request

Returns

an empty dict