Table
objects describe Registry Tables. A Table
object can either be instantiated via a call to Project.list_tables()
or directly using its ID.
Table
s are for the most part lazy, in that they don’t perform any network requests without an explicit call to Table.load()
or to a property getter. Two exceptions to this are Table.list_records()
and Table.update()
, both of which are discussed below.
Table.load()
, if called, will perform a network request and cache values for each of the Table
’s properties.Table.list_records()
will return a generator that yields a paginated dictionary of Record
s that are present in the calling Table
. The keys of this dictionary are Record IDs and the values are the corresponding Record
objects. This function also takes an optional keyword-only page_size
argument that dictates the size of the returned page. The value of this argument must be a postive integer. If not provided, the default is a page size of 100. Pages are ordered by Record ID, with lower IDs being yielded first.Table.list_records()
is below.
Table.list_records()
will always perform a network request for each returned page.
load_if_missing
boolean argument which, if True
, will call Account.load()
if the requested property has not been loaded already. This defaults to True
.
Table.get_display_name()
will return the display_name
of the calling Table
as a stringTable.get_columns()
will return a dictionary containing the columns of the calling Table
. The keys of the dictionary are column names, and its values are Column
objects. Column
is a convenience dataclass with the properties
Column.key
: the key of the column.Column.type
: the (python) type of the column.Column.upstream_type
: similar to Column.type
. However, this is a dataclass which contains an internal representation of the column’s data type, and should not be accessed or modified directly.Table
can be modified by using the Table.update()
function. Table.update()
returns a context manager (and hence must be called using with
syntax) with the following methods:
upsert_record(record_name: str, column_data: Dict[str, Any])
will either (up)date or in(sert) a record with name record_name
with the column values prescribed in column_data
.column_data
must be a valid column key (meaning that there must be a column in the calling Table
with the same key), and the value corresponding to that key must be same type as the column (meaning that it is an instance of the column’s (python) type).delete_record(name: str)
will delete the record with name name
. If no such record exists, the method call will be a noop.upsert_column(key: str, type: RegistryPythonType, *, required: bool = False)
will create a column with key key
and type type
. For now, updating column types (i.e. calling upsert_column
with a key that already exists, and a type that differs from the type of the column) is not allowed, and attempting to do so will raise an exception.pandas
Table
can be exported as a pandas.DataFrame
using the Table.get_dataframe()
function. This requires pandas
to be installed. Doing so will load the entire table from the network into memory, so it can be costly for larger tables.
delete_column(column_name: str)
Table
.
record 1
and record 2
, with the provided values for the column Size
.
When using an updater, no network requests are made until the end of the with
block. This mimics transactions in relational database systems, and has several similar behaviors, namely that
with
block, none of the updates made inside the with
block will be sent over the network, so no changes will be made to the Table
.with
block. This significantly boosts performance when a large amount of updates are made at once.