class atoti.Session#

The primary entry point for Atoti applications.

A session is a process holding data in tables and aggregating it in cubes. It also serves a web app for data exploration accessible with link.

__init__(*, name='Unnamed', app_extensions={}, authentication=None, branding=None, client_certificate=None, extra_jars=(), https=None, i18n=None, java_options=(), jwt=None, logging=None, port=0, ready=True, same_site=None, user_content_storage=None, **kwargs)#

Create a session.

This will start an Atoti Server in a new process. If the JAVA_HOME environment variable is not defined or if it points to an unsupported Java version, the JVM from jdk4py will be used instead.

  • name (str | None) –

    The name of the session.

    For a better prototyping experience in notebooks, creating a session with the same name as an already running session will close the older one. Pass None to opt out of this behavior.

  • app_extensions (Mapping[str, Path]) –

    Mapping from the name of an extension (i.e. name property in their package.json) to the path of its dist directory.


    This feature is not part of the community edition: it needs to be unlocked.

    Extensions can enhance the app in many ways such as:

    • Adding new type of widgets.

    • Attaching custom menu items or titlebar buttons to a set of widgets.

    • Providing other React contexts to the components rendered by the app.

    The app extension template can be used as a starting point.

    See also

    Available extensions in atoti.app_extension.

  • authentication (BasicAuthenticationConfig | KerberosConfig | LdapConfig | OidcConfig | None) –

    The configuration to enable authentication on the session.


    This feature is not part of the community edition: it needs to be unlocked.

  • branding (BrandingConfig | None) – The config to customize some elements of the UI to change its appearance.

  • client_certificate (ClientCertificateConfig | None) – The config to enable client certificate based authentication on the session.

  • extra_jars (Sequence[Path] | Set[Path]) – The paths to the JARs to add to the classpath of the Java process when starting the session.

  • https (HttpsConfig | None) – The config providing certificates to enable HTTPS on the session.

  • i18n (I18nConfig | None) – The config to internationalize the session.

  • java_options (Sequence[str] | Set[str]) –

    The additional options to pass when starting the Java process (e.g. for optimization or debugging purposes).

    In particular, the -Xmx option can be set to increase the amount of RAM that the session can use.

    If this option is not specified, the JVM default memory setting is used which is 25% of the machine memory.

  • jwt (JwtConfig | None) – The config to set the key pair used to validate JWTs when authenticating with the session.

  • logging (LoggingConfig | None) – The config describing how to handle session logs.

  • port (int) –

    The port on which the session will be exposed.

    Defaults to a random available port.

  • ready (bool) – The initial value of ready.

  • same_site (Literal['none', 'strict'] | None) –

    The value to use for the SameSite attribute of the HTTP cookie sent by the session when authentication is configured.


    This feature is not part of the community edition: it needs to be unlocked.

    See for more information.

    Setting it to none requires the session to be served through HTTPS.

    Defaults to lax.

  • user_content_storage (Path | str | UserContentStorageConfig | None) – The location of the database where the user content will be stored. The user content is what is not part of the data sources, such as the dashboards, widgets, and filters saved in the application. If a path to a directory is given, it will be created if needed. When None, the user content is kept in memory and is thus lost when the session is closed.


Add a table from an external database to the session.


Close this session and free all the associated resources.


Return whether the session is closed or not.


Connect to an external database using DirectQuery.


Create a cube based on the passed table.


Create a new source scenario.


Create an empty table with columns of the given types.


Cubes of the session.


Delete the source scenario with the provided name if it exists.


Create a custom endpoint at /atoti/pyapi/{route}.


Run the query but, instead of returning its result, return the explanation of how it was executed containing a summary, global timings, and the query plan with all the retrievals.


Export a template containing all translatable values in the session's cubes.


Display a link to this session.


Path to the session logs file.


Name of the session.


Port on which the session is exposed.


Execute an MDX query and return its result as a pandas DataFrame.


Read an Arrow Table into a table.


Read a CSV file into a table.


Read a NumPy 2D array into a new table.


Read a pandas DataFrame into a table.


Read a Parquet file into a table.


Read a Spark DataFrame into a table.


Create a table from the result of the passed SQL query.


Whether the session is ready or not.


Names of the source scenarios of the session.



Start a transaction to batch several table operations.


Tables of the session.


Wait for the underlying server subprocess to terminate.


Display an Atoti widget to explore the session interactively.