awswrangler.dynamodb.read_items

awswrangler.dynamodb.read_items(table_name: str, partition_values: Sequence[Any] | None = None, sort_values: Sequence[Any] | None = None, filter_expression: ConditionBase | str | None = None, key_condition_expression: ConditionBase | str | None = None, expression_attribute_names: Dict[str, str] | None = None, expression_attribute_values: Dict[str, Any] | None = None, consistent: bool = False, columns: Sequence[str] | None = None, allow_full_scan: bool = False, max_items_evaluated: int | None = None, as_dataframe: bool = True, boto3_session: Session | None = None) → DataFrame | List[Dict[str, Any]]

Read items from given DynamoDB table.

This function aims to gracefully handle (some of) the complexity of read actions available in Boto3 towards a DynamoDB table, abstracting it away while providing a single, unified entrypoint.

Under the hood, it wraps all the four available read actions: get_item, batch_get_item, query and scan.

Parameters:

  • table_name (str) – DynamoDB table name.

  • partition_values (Sequence[Any], optional) – Partition key values to retrieve. Defaults to None.

  • sort_values (Sequence[Any], optional) – Sort key values to retrieve. Defaults to None.

  • filter_expression (Union[ConditionBase, str], optional) – Filter expression as string or combinations of boto3.dynamodb.conditions.Attr conditions. Defaults to None.

  • key_condition_expression (Union[ConditionBase, str], optional) – Key condition expression as string or combinations of boto3.dynamodb.conditions.Key conditions. Defaults to None.

  • expression_attribute_names (Mapping[str, str], optional) – Mapping of placeholder and target attributes. Defaults to None.

  • expression_attribute_values (Mapping[str, Any], optional) – Mapping of placeholder and target values. Defaults to None.

  • consistent (bool) – If True, ensure that the performed read operation is strongly consistent, otherwise eventually consistent. Defaults to False.

  • columns (Sequence[str], optional) – Attributes to retain in the returned items. Defaults to None (all attributes).

  • allow_full_scan (bool) – If True, allow full table scan without any filtering. Defaults to False.

  • max_items_evaluated (int, optional) – Limit the number of items evaluated in case of query or scan operations. Defaults to None (all matching items).

  • as_dataframe (bool) – If True, return items as pd.DataFrame, otherwise as list/dict. Defaults to True.

  • boto3_session (boto3.Session, optional) – Boto3 Session. Defaults to None (the default boto3 Session will be used).

Raises:

  • exceptions.InvalidArgumentType – When the specified table has also a sort key but only the partition values are specified.

  • exceptions.InvalidArgumentCombination – When both partition and sort values sequences are specified but they have different lengths, or when provided parameters are not enough informative to proceed with a read operation.

Returns:

A Data frame containing the retrieved items, or a dictionary of returned items.

Return type:

Union[pd.DataFrame, List[Mapping[str, Any]]]

Examples

Reading 5 random items from a table

>>> import awswrangler as wr
>>> df = wr.dynamodb.read_items(table_name='my-table', max_items_evaluated=5)

Strongly-consistent reading of a given partition value from a table

>>> import awswrangler as wr
>>> df = wr.dynamodb.read_items(table_name='my-table', partition_values=['my-value'], consistent=True)

Reading items pairwise-identified by partition and sort values, from a table with a composite primary key

>>> import awswrangler as wr
>>> df = wr.dynamodb.read_items(
...     table_name='my-table',
...     partition_values=['pv_1', 'pv_2'],
...     sort_values=['sv_1', 'sv_2']
... )

Reading items while retaining only specified attributes, automatically handling possible collision with DynamoDB reserved keywords

>>> import awswrangler as wr
>>> df = wr.dynamodb.read_items(
...     table_name='my-table',
...     partition_values=['my-value'],
...     columns=['connection', 'other_col'] # connection is a reserved keyword, managed under the hood!
... )

Reading all items from a table explicitly allowing full scan

>>> import awswrangler as wr
>>> df = wr.dynamodb.read_items(table_name='my-table', allow_full_scan=True)

Reading items matching a KeyConditionExpression expressed with boto3.dynamodb.conditions.Key

>>> import awswrangler as wr
>>> from boto3.dynamodb.conditions import Key
>>> df = wr.dynamodb.read_items(
...     table_name='my-table',
...     key_condition_expression=(Key('key_1').eq('val_1') & Key('key_2').eq('val_2'))
... )

Same as above, but with KeyConditionExpression as string

>>> import awswrangler as wr
>>> df = wr.dynamodb.read_items(
...     table_name='my-table',
...     key_condition_expression='key_1 = :v1 and key_2 = :v2',
...     expression_attribute_values={':v1': 'val_1', ':v2': 'val_2'},
... )

Reading items matching a FilterExpression expressed with boto3.dynamodb.conditions.Attr

>>> import awswrangler as wr
>>> from boto3.dynamodb.conditions import Attr
>>> df = wr.dynamodb.read_items(
...     table_name='my-table',
...     filter_expression=Attr('my_attr').eq('this-value')
... )

Same as above, but with FilterExpression as string

>>> import awswrangler as wr
>>> df = wr.dynamodb.read_items(
...     table_name='my-table',
...     filter_expression='my_attr = :v',
...     expression_attribute_values={':v': 'this-value'}
... )

Reading items involving an attribute which collides with DynamoDB reserved keywords

>>> import awswrangler as wr
>>> df = wr.dynamodb.read_items(
...     table_name='my-table',
...     filter_expression='#operator = :v',
...     expression_attribute_names={'#operator': 'operator'},
...     expression_attribute_values={':v': 'this-value'}
... )