API Parameters

Most Model APIs and some Table APIs accept a params hash argument that controls the API operation.

Params

These are the parameter values for the params argument.

Property	Type	Description
add	object	Used to atomically add a value to an attribute. Set to an object containing the attribute name and value to add. Example: add:
batch	object	Accumulated batched API calls. Invoke with Table.batch*
capacity	string	Set to INDEXES, TOTAL or NONE to control the capacity metric. Returned in items.capacity
client	object	Set to a DynamoDB DocumentClient instance to overide the table default client. Defaults to null
consistent	boolean	Set to true to stipulate that consistent reads are required.
context	object	Optional context hash of properties to blend with API properties when creating or updating items. This overrides the Table.context. Setting to {} is a useful one-off way to ignore the context for this API.
count	boolean	Return a count of matching items instead of the result set for a find/query. The count is returned as a count property in the returned items array. Default false.
delete	object	Used to delete items from a set attribute. Set to an object containing the attribute name and item to delete. Example: delete:
execute	boolean	Set to true to execute the API. If false, return the formatted command and do not execute. Note: if set on an update of a unique field which requires a transaction and multiple commands, the commands will not be returned. To see the commands, set the parmas.log to true. Execute defaults to true.
exists	boolean	Set to true for create, delete or update APIs to verify if an item of the same key exists or not. Defaults to false for create, null for delete and true for update Set to null to disable checking either way.
fields	array	List of properties to return. This sets the ProjectionExpression. Default null.
follow	boolean	Refetch the item using the returned keys to retrieve the full item. Useful for indexes that are KEYS_ONLY. Default null.
hidden	boolean	Return hidden attributes in Javascript properties. Default Table params.hidden.
index	string	Name of index to utilize. Defaults to 'primary'
limit	number	Set to the maximum number of items to return from a find / scan.
log	boolean	Set to true to force the API call to be logged at the 'data' level. Requires that a 'logger' be defined via the Table constructor. Defaults to false.
many	boolean	Set to true to enable deleting multiple items. Default to false.
noerror	boolean	Sto to true to suppress some logginer errors. Defaults to false.
next	object	Starting key for the result set. This is used to set the ExclusiveStartKey when doing a find/scan. Typically set to the result.next value returned on a previous find/scan.
prev	object	Starting key for the result set when requesting a previous page. This is used to set the ExclusiveStartKey when doing a find/scan in reverse order. Typically set to the result.prev value returned on a previous find/scan.
parse	boolean	Parse DynamoDB response into native Javascript properties. Defaults to true.
partial	boolean	Allow partial object updates for this API call. This overrides any field schema, or Table constructor "partial" definitions. Default is null.
postFormat	function	Hook to invoke on the formatted API command just before execution. Passed the model and cmd, expects updated cmd to be returned. Cmd is an object with properties for the relevant DynamoDB API.
remove	array	Set to a list of of attributes to remove from the item.
reprocess	boolean	Set to true to enable batchWrite to retry unprocessed items. Defaults to true
return	string	Controls the returned values for create() and update() via the ReturnValues DynamoDB API parameter. Set to true, false or 'ALL_NEW', 'ALL_OLD', 'NONE', 'UPDATED_OLD' or 'UPDATED_NEW'. The value true, is an alias for ALL_NEW. The value false is an alias for 'NONE'. The create() API defaults to 'ALL_NEW'. The update() API defaults to 'ALL_NEW' unless the item has unique properties the return parameter must be specified. For update() calls on items that have unique attributes defined in the schema, you can set to 'get' to perform a transparent get() to retrieve the updated item. This is necessary as updating unique items uses transactions which do not return the updated value.
reverse	boolean	Set to true to reverse the order of items returned.
select	string	Determine the returned attributes. Set to ALL_ATTRIBUTES
set	object	Used to atomically set attribute vaules to an expression value. Set to an object containing the attribute names and values to assign. The values are expressions similar to Where Clauses with embedded ${attributeReferences} and {values}. See Where Clause for more details.
stats	object	Set to an object to receive performance statistics for find/scan. Defaults to null.
substitutions	object	Variables that can be referenced in a where clause. Values will be added to ExpressionAttributeValues when used.
throw	boolean	Set to false to not throw exceptions when an API request fails. Defaults to true.
transaction	object	Accumulated transactional API calls. Invoke with Table.transaction
type	string	Add a type condition to the create, delete or update API call. Set type to the DynamoDB required type.
where	string	Define a filter or update conditional expression template. Use ${attribute} for attribute names, @{var} for variable substitutions and {value} for values. OneTable will extract attributes and values into the relevant ExpressionAttributeNames and ExpressionAttributeValues.

Stats

If stats is defined, find/query/scan operations will return the following statistics in the stats object:

• count -- Number of items returned
• scanned -- Number of items scanned
• capacity -- DynamoDB consumed capacity units

Transformations

The transform property may be used to format data prior to writing into the database and parse it when reading back. This can be useful to convert to alternate data representations in your table. The transform signature is:

value = transform(model, operation, name, value, properties)

The operation parameter is set to read or write. The name argument is set to the field attribute name.