read Method
Description
Reads (consumes) item attributes from a NoSQL table into pandas DataFrames.
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
Syntax
read(backend, table=''[, columns=None, filter='', max_rows_in_msg=0,
iterator=False, **kw])
The following syntax statement replaces the
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])
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
Parameters
- backend
The backend type —
"nosql"or"kv"for the NoSQL backend. See Backend Types.- Type:
str
- Requirement: Required
- Type:
- 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
- Type:
- 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)
- Type:
- 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- Type:
str
- Requirement: Optional
- Type:
- 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- Type:
[]str
- Requirement: Optional
- Type:
- max_rows_in_msg
The maximum number of table items (rows) to read in each message (i.e., the size of the read chunks).
Whenread returns a DataFrames iterator (when theiterator parameter is set toTrue), the size each of the returned DataFrames is the configured message size.- Type:
int
- Requirement: Optional
- Default Value:
256
- Type:
- 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
- Type:
kw Arguments
The NoSQL backend supports the following
- 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
- Type:
- 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 thesort_key_range_start and/orsort_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
- Type:
- 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 thesharding_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 thesort_key_range_start argument and less than (<) the value of thesort_key_range_end argument (if set).- Type:
str
- Requirement: Optional
- Type:
- 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 thesharding_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 thesort_key_range_start argument (if set) and less than (<) the value of thesort_key_range_end argument.- Type:
str
- Requirement: Optional
- Type:
Return Value
- When the value of the
iterator parameter isTrue— returns a pandas DataFrames iterator. - When the value of the
iterator parameter isFalse(default) — returns a single pandas DataFrame.
Examples
Following are some usage examples for the
-
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 (defaultiterator value =False). Return only the specified item attributes (columns ) for items whoseage 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 (defaultiterator value =False) and reset the index of the returned DataFrame (reset_index =True). Return only items whoseage attribute value is greater than 10 and whosecountry 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)