atoti.Session#

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.

Parameters:
  • 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, str | Path]) –

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

    Note

    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.

    Note

    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 (Collection[str | 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 (Collection[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.

    Note

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

    See https://web.dev/samesite-cookies-explained 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_external_table

Add a table from an external database to the session.

close

Close this session and free all the associated resources.

closed

Return whether the session is closed or not.

connect_to_external_database

Connect to an external database using DirectQuery.

create_cube

Create a cube based on the passed table.

create_scenario

Create a new source scenario.

create_table

Create a table from a schema.

cubes

Cubes of the session.

delete_scenario

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

endpoint

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

explain_mdx_query

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_translations_template

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

link

Display a link to this session.

logs_path

Path to the session logs file.

name

Name of the session.

port

Port on which the session is exposed.

query_mdx

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

read_arrow

Read an Arrow Table into a table.

read_csv

Read a CSV file into a table.

read_numpy

Read a NumPy 2D array into a new table.

read_pandas

Read a pandas DataFrame into a table.

read_parquet

Read a Parquet file into a table.

read_spark

Read a Spark DataFrame into a table.

read_sql

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

ready

Whether the session is ready or not.

scenarios

Names of the source scenarios of the session.

security

start_transaction

Start a transaction to batch several table operations.

tables

Tables of the session.

wait

Wait for the underlying server subprocess to terminate.

widget

Display an Atoti widget to explore the session interactively.