atoti.table module

class atoti.table.Table(_name, _java_api, _scenario='Base', _columns=<factory>)

Represents a single table.


Add one or multiple rows to the table.

If a row with the same keys already exist in the table, it will be overridden by the passed one.


rows (Union[Tuple[Any, …], Mapping[str, Any]]) –

The rows to add. Rows can either be:

  • Tuples of values in the correct order.

  • Column name to value mappings.

All rows must share the shame shape.

property columns: Sequence[str]

Columns of the table.

Return type



Delete rows where the values for each column match those specified.

Each set of coordinates can only contain one value for each column. To specify multiple values for one column, multiple mappings must be passed.


coordinates (Mapping[str, Any]) – Mappings between table columns and values. Rows matching the provided mappings will be deleted from the table. If None, all the rows of the table will be deleted.


>>> df = pd.DataFrame(
...     columns=["City", "Price"],
...     data=[
...         ("London", 240.0),
...         ("New York", 270.0),
...         ("Paris", 200.0),
...     ],
... )
>>> table = session.read_pandas(df, keys=["City"], table_name="Cities")
>>> table.head()
London    240.0
New York  270.0
Paris     200.0
>>> table.drop({"City": "Paris"})
>>> table.head()
London    240.0
New York  270.0
>>> table.drop()
>>> table.head()
Empty DataFrame
Columns: [Price]
Index: []

Return n rows of the table as a pandas DataFrame.

Return type


join(other, *, mapping=None)

Define a reference between this table and another.

There are two different possible situations when creating references:

  • All the key columns of the other table are mapped: this is a normal reference.

  • Only some of the key columns of the other table are mapped: this is a partial reference:

    • The columns from the base table used in the mapping must be attached to hierarchies.

    • The un-mapped key columns of the other table will be converted into hierarchies.

Depending on the cube creation mode, the join will also generate different hierarchies and measures:

  • manual: The un-mapped keys of the other table will become hierarchies.

  • no_measures: All of the key columns and non-numeric columns from the other table will be converted into hierarchies. No measures will be created in this mode.

  • auto: The same hierarchies will be created as in the no_measures mode. Additionally, columns of the base table containing numeric values (including arrays), except for columns which are keys, will be converted into measures. Columns of the other table with these types will not be converted into measures.

  • other (Table) – The other table to reference.

  • mapping (Optional[Mapping[str, str]]) – The column mapping of the reference. Defaults to the columns with the same names in the two tables.

property keys: Sequence[str]

Names of the key columns of the table.

Return type


load_csv(path, *, separator=None, encoding='utf-8', process_quotes=True, array_separator=None, date_patterns=None)

Load a CSV into this scenario.

  • path (Union[Path, str]) –

    The path to the CSV file to load.

    .gz, .tar.gz and .zip files containing compressed CSV(s) are also supported.

    The path can also be a glob pattern (e.g. path/to/directory/**.*.csv).

  • separator (Optional[str]) – The character separating the values of each line. the separator will be detected automatically.

  • encoding (str) – The encoding to use to read the CSV.

  • process_quotes (bool) –

    Whether double quotes should be processed to follow the official CSV specification:

    • True:

      • Each field may or may not be enclosed in double quotes (however some programs, such as Microsoft Excel, do not use double quotes at all). If fields are not enclosed with double quotes, then double quotes may not appear inside the fields.

      • A double quote appearing inside a field must be escaped by preceding it with another double quote.

      • Fields containing line breaks, double quotes, and commas should be enclosed in double-quotes.

    • False: all double-quotes within a field will be treated as any regular character, following Excel’s behavior. In this mode, it is expected that fields are not enclosed in double quotes. It is also not possible to have a line break inside a field.

    • None: The behavior will be inferred from the first lines of the CSV file.

  • array_separator (Optional[str]) – The character separating array elements. Setting it to a non-None value will parse all the columns containing this separator as arrays.

  • date_patterns (Optional[Mapping[str, str]]) – A column name to date pattern mapping that can be used when the built-in date parsers fail to recognize the formatted dates in the passed files.

load_kafka(bootstrap_server, topic, *, group_id, batch_duration=1000, consumer_config=None, deserializer=KafkaDeserializer(name='io.atoti.loading.kafka.impl.serialization.JsonDeserializer'))

Consume a Kafka topic and stream its records in the table.


This method requires the atoti-kafka plugin.

The records’ key deserializer default to StringDeserializer.

  • bootstrap_server (str) – host[:port] that the consumer should contact to bootstrap initial cluster metadata.

  • topic (str) – Topic to subscribe to.

  • group_id (str) – The name of the consumer group to join.

  • batch_duration (int) – Milliseconds spent batching received records before publishing them to the table. If 0, received records are immediately published to the table. Must not be negative.

  • consumer_config (Optional[Mapping[str, str]]) – Mapping containing optional parameters to set up the KafkaConsumer. The list of available params can be found here.

  • deserializer (KafkaDeserializer) – Deserialize Kafka records’ value to atoti table rows. Use atoti_kafka.create_deserializer() to create custom ones.


Load a NumPy 2D array into this scenario.


array (ndarray) – The 2D array to load.


Load a pandas DataFrame into this scenario.


dataframe (DataFrame) – The DataFrame to load.

load_parquet(path, **kwargs)

Load a Parquet file into this scenario.


path (Union[Path, str]) – The path to the Parquet file. If a path pointing to a directory is provided, all of the files with the .parquet extension in the directory will be loaded into the same table and, as such, they are all expected to share the same schema. The path can also be a glob pattern (e.g. path/to/directory/**.*.parquet).


Load a Spark DataFrame into this scenario.


dataframe – The dataframe to load.

load_sql(query, *, url, driver=None)

Load the result of the passed SQL query into the table.


This method requires the atoti-sql plugin.

  • query (str) – The result of this SQL query will be loaded into the table.

  • url (str) –

    The JDBC connection URL of the database. The jdbc: prefix is optional but the database specific part (such as h2: or mysql:) is mandatory. For instance:

    • h2:file:/home/user/database/file/path;USER=username;PASSWORD=passwd

    • mysql://localhost:7777/example?user=username&password=passwd

    • postgresql://postgresql.db.server:5430/example?user=username&password=passwd

    More examples can be found here.

  • driver (Optional[str]) – The JDBC driver used to load the data. If None, the driver is inferred from the URL. Drivers can be found in the atoti_sql.drivers module.


>>> table = session.create_table("Cities", types={"ID": tt.type.INT, "CITY": tt.type.STRING, "MY_VALUE": tt.type.NULLABLE_DOUBLE}, keys=["ID"])
>>> table.load_sql(
...     url=f"h2:file:{RESOURCES}/h2-database;USER=root;PASSWORD=pass",
... )
>>> len(table)
property loading_report:

Table loading report.

Return type


property name: str

Name of the table.

Return type


property scenario: ScenarioName

Scenario on which the table is.

Return type

NewType()(ScenarioName, str)

property scenarios: atoti.table.TableScenarios

All the scenarios the table can be on.

Return type


class atoti.table.TableScenarios(_java_api, _table)

Scenarios of a table.