read Method

On This Page

Description

Reads (consumes) item attributes from a NoSQL table into pandas DataFrames.

Note

By default, the method returns all user attributes (columns) of all the items (rows) in the specified NoSQL table. You can optionally restrict the read query by setting the filter parameter to a filter expression that restricts which items to read and/or setting the columns parameter to a list of item attributes to return for the read items (as restricted by the filter expression, if set).

Syntax

read(backend, table=''[, columns=None, filter='', max_rows_in_msg=0,
    iterator=False, **kw])

The following syntax statement replaces the kw parameter with the additional keyword arguments that can be passed for the NoSQL backend via this parameter:

read(backend, table=''[, columns=None, filter='', max_rows_in_msg=0,
     iterator=False, reset_index, sharding_keys, sort_key_range_start,
     sort_key_range_end])

Note

The method has additional parameters that aren't currently supported for the NoSQL backend. Therefore, when calling the method, be sure to explicitly specify the names of all parameters after table.

Parameters

backend

The backend type — "nosql" or "kv" for the NoSQL backend. See Backend Types.

Type: str

Requirement: Required

table

The relative path to the backend data — a directory in the target data container (as configured for the client object) that represents a NoSQL table. For example, "mytable" or "examples/nosql/my_table".

Type: str

Requirement: Required

iterator

Determines whether to return a pandas DataFrames iterator or a single DataFrame: True — return a DataFrames iterator; False (default) — return a single DataFrame.

Type: bool

Requirement: Optional

Valid Values: True | False

Default Value: False (return a single DataFrame)

filter

A platform filter expression that restricts which items (rows) to read. For example, "vendor=='Honda" AND color=='red'". Only attributes for items that match the filter criteria are returned. See Filter Expression for syntax details and examples.

Note

You can use the columns parameter to specify which attributes to return for the items that match the filter expression. For more information, see the notes in the method description.

Type: str

Requirement: Optional

columns

A list of item attributes (columns) to return. For example, ["vendor", "color", "km"]. By default, the method returns all of the items' user attributes.

Note

You can optionally use the filter parameter to restrict the items for which to return attributes. For more information, see the notes in the method description.

Type: []str

Requirement: Optional

max_rows_in_msg

The maximum number of table items (rows) to read in each message (i.e., the size of the read chunks).
When read returns a DataFrames iterator (when the iterator parameter is set to True), the size each of the returned DataFrames is the configured message size.

Type: int

Requirement: Optional

Default Value: 256

kw

This parameter is used for passing a variable-length list of additional keyword (named) arguments. See the following kw Arguments section for a list of additional arguments that are supported for the NoSQL backend via the kw parameter.

Type: ** — variable-length keyword arguments list

Requirement: Optional

kw Arguments

The NoSQL backend supports the following read arguments via the kw parameter for passing a variable-length list of additional keyword arguments:

reset_index

Determines whether to reset the index index column of the returned DataFrame: True — reset the index column by setting it to the auto-generated pandas range-index column; False (default) — set the index column to the table's primary-key attribute.

Type: bool

Requirement: Optional

Valid Values: True | False

Default Value: False

sharding_keys

[Tech Preview] A list of item sharding-key values to query to get by using a range scan. The sharding-key value is the part to the left of the leftmost period in a compound primary-key value (item name). For example, ["january", "february", "march"]. You can optionally use the sort_key_range_start and/or sort_key_range_end keyword arguments to restrict the search to a specific range of sorting keys (sort_key_range_start >= <sorting key> < sort_key_range_end).

Type: []str

Requirement: Optional

sort_key_range_start

[Tech Preview] The minimal sorting-key value of the items to get by using a range scan. The sorting-key value is the part to the right of the leftmost period in a compound primary-key value (item name). This argument is applicable only together with the sharding_keys keyword argument. The scan will return all items with the specified sharding-key values whose sorting-key values are greater than or equal to (>=) than the value of the sort_key_range_start argument and less than (<) the value of the sort_key_range_end argument (if set).

Type: str

Requirement: Optional

sort_key_range_end

[Tech Preview] The maximal sorting-key value of the items to get by using a range scan. The sorting-key value is the part to the right of the leftmost period in a compound primary-key value (item name). This argument is applicable only together with the sharding_keys keyword argument. The scan will return all items with the specified sharding-key values whose sorting-key values are greater than or equal to (>=) the value of the sort_key_range_start argument (if set) and less than (<) the value of the sort_key_range_end argument.

Type: str

Requirement: Optional

Return Value

When the value of the iterator parameter is True — returns a pandas DataFrames iterator.
When the value of the iterator parameter is False (default) — returns a single pandas DataFrame.

Examples

Following are some usage examples for the read method of the Frames NoSQL backend:

Read all items (rows) of a mytable table in the client's data container (table) into a DataFrames iterator (iterator = True):

table = "mytable"
dfs = client.read(backend="nosql", table=table, iterator="True")
for df in dfs:
    display(df)

Read from a mytable into a single DataFrame (default iterator value = False). Return only the specified item attributes (columns) for items whose age attribute value is greater or equal to 11 and less than 15 (filter).
```
table = "mytable"
df = client.read("nosql", table=table, filter="age>=11 AND age<15",
                 columns=["username", "age", "country", "city"])
display(df)
```
Read from a my_tables/students table in the client's data container (table) into a single DataFrame (default iterator value = False) and reset the index of the returned DataFrame (reset_index = True). Return only items whose age attribute value is greater than 10 and whose country attribute value is either "US" or "UK" (filter).
```
table = "/my_tables/students_11-15"
df = client.read("nosql", table=table, reset_index=True,
                 filter="age > 10 AND country IN ('US', 'UK')")
display(df)
```

read Method

Description

Syntax

Parameters

kw Arguments

Return Value

Examples

See Also