> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# atoti.Session.connect

#### *classmethod* Session.connect(url, \*, authentication=None, certificate\_authority=None)

Connect to an existing session.

Here is a breakdown of the capabilities of the returned session:

<a id="local" />

* Local
  * If all the following conditions are met:

    <a id="a" />

    * 1. the target session requires authentication (e.g. it has [`security`](./atoti.config.session_config#atoti.SessionConfig.security) configured)

    <a id="b" />

    * 1. the provided *authentication* or *certificate\_authority* arguments grant ROLE\_ADMIN

    <a id="c" />

    * 1. the target session (the one at *url*) was [`started`](./atoti.Session.start#atoti.Session.start) with the same version of Atoti Python SDK (6.2.0b0)

    <a id="d" />

    * 1. the target session runs on the same host as the current Python process
  * Then all [`Session`](./atoti.session#atoti.Session) capabilities can be used except for:
    * [`endpoint()`](./atoti.endpoint#module-atoti.endpoint)
    * [`logs_path`](./atoti.Session.logs_path#atoti.Session.logs_path)
    * [`wait()`](./atoti.Session.wait#atoti.Session.wait)

<a id="remote" />

* Remote
  * If conditions [a.](#a), [b.](#b), and [c.](#c) are met but not [d.](#d) (i.e., not on the same host)
  * Then all [local](#local) capabilities are available except those needing a shared file system.
    For example:
    * [`load()`](./atoti.Table.load#atoti.Table.load) with [`CsvLoad`](./atoti.data_load.csv_load#atoti.CsvLoad) or [`ParquetLoad`](./atoti_parquet.parquet_load#atoti_parquet.ParquetLoad) and [`read_csv()`](./atoti.Session.read_csv#atoti.Session.read_csv) are not available (unless loading from [cloud storage](../getting_started/plugins#cloud-storage))
    * [`load()`](./atoti.Table.load#atoti.Table.load) with [`pyarrow.Table`](https://arrow.apache.org/docs/python/generated/pyarrow.Table.html#pyarrow.Table) or [`pandas.DataFrame`](https://pandas.pydata.org/pandas-docs/version/2.3/reference/api/pandas.DataFrame.html#pandas.DataFrame), [`read_arrow()`](./atoti.Session.read_arrow#atoti.Session.read_arrow) and [`read_pandas()`](./atoti.Session.read_pandas#atoti.Session.read_pandas) methods are not available
* No security management
  * If conditions [a.](#a) and [b.](#b) are meet, plus both:

    <a id="e" />

    * 1. the target session runs the same Atoti Server version (e.g. 6.2.0-beta for Atoti Python SDK 6.2.0b0)

    <a id="f" />

    * 1. the target session [is exposed to Atoti Python SDK](https://docs.activeviam.com/products/atoti/server/6.2/docs/starters/how-to/expose-app-to-python/)
  * Depending on whether [d.](#d) is met, either [local](#local) or [remote](#remote) capabilities are available, except for [`security`](./atoti.security#module-atoti.security) management features.
* Read-only
  * If only condition [e.](#e) is met (i.e. matching Atoti Server versions)
  * Then capabilities that modify the session data or data model are unavailable.
    However, some read-only capabilities remain accessible.
    For example:
    * Not available: [`create_table()`](./atoti.Session.create_table#atoti.Session.create_table), [`create_cube()`](./atoti.Session.create_cube#atoti.Session.create_cube), and [`read_csv()`](./atoti.Session.read_csv#atoti.Session.read_csv)
    * Available: [`atoti.tables.Tables.schema`](./atoti.tables.Tables.schema#atoti.tables.Tables.schema) and [`atoti.Table.query()`](./atoti.Table.query#atoti.Table.query)
* Minimal capabilities
  * Always available:
    * [`atoti.Session.link`](./atoti.Session.link#atoti.Session.link)
    * [`atoti.Session.query_mdx`](./atoti.Session.query_mdx#atoti.Session.query_mdx)
    * [`atoti.Cube.query`](./atoti.Cube.query#atoti.Cube.query)

<Note>
  Data and data model changes made from a connected session are not persisted on the target session.
  They will be lost if the target session is restarted.
</Note>

* **Parameters:**
  * **url** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – The base URL of the target session.
    The endpoint `f"{url}/versions/rest"` is expected to exist.
  * **authentication** ([*Authenticate*](./atoti.authentication.authenticate#atoti.Authenticate) *|* [*ClientCertificate*](./atoti.authentication.client_certificate#atoti.ClientCertificate) *|* *None*) – The method used to authenticate against the target session.
  * **certificate\_authority** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path) *|* *None*) – Path to the custom certificate authority file to use to verify the HTTPS connection.
    Required when the target session has been configured with an SSL certificate that is not signed by some trusted public certificate authority.
* **Return type:**
  [*Self*](https://docs.python.org/3/library/typing.html#typing.Self)

### Example

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> session_config = tt.SessionConfig(security=tt.SecurityConfig())
>>> target_session = tt.Session.start(session_config)
>>> _ = target_session.create_table("Example", data_types={"Id": "String"})
>>> target_session.security.individual_roles.update(
...     {"user": {"ROLE_USER"}, "admin": {"ROLE_USER", "ROLE_ADMIN"}},
... )
>>> password = "passwd"
>>> target_session.security.basic_authentication.credentials.update(
...     {"user": password, "admin": password}
... )
>>> admin_session = tt.Session.connect(
...     target_session.url,
...     authentication=tt.BasicAuthentication("admin", password),
... )
>>> table = admin_session.tables["Example"]
>>> table += ("foo",)
>>> table.head()
    Id
0  foo
```

The connected session must be granted ROLE\_ADMIN:

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> user_session = tt.Session.connect(
...     target_session.url,
...     authentication=tt.BasicAuthentication("user", password),
... )
>>> user_session.ready = False  
Traceback (most recent call last):
    ...
atoti._graphql.client.exceptions.GraphQLClientHttpError: HTTP status code: 400
```

<Callout icon="link">
  **See also**:
  [`start()`](./atoti.Session.start#atoti.Session.start)
</Callout>