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_in_message=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_in_message=0,
     iterator=False, reset_index, sharding_keys])
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 | columns | filter | kw | max_in_message | reset_index (kw argument) | sharding_keys (kw argument) | table

backend
The backend type — "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_in_message

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
A list of item sharding-key values to query, for tables with a compound primary key; for example, ["january", "february", "march"].

  • Type: []str
  • Requirement: Optional
  • Default Value: 0

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:

  1. 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="kv", table=table, iterator="True")
    for df in dfs:
        display(df)
      

  2. 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("kv", table=table, filter="age>=11 AND age<15",
                     columns=["username", "age", "country", "city"])
    display(df)
  3. 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("kv", table=table, reset_index=True,
                     filter="age > 10 AND country IN ('US', 'UK')")
    display(df)
      

See Also