1. Documentation
2. 2026.0 (Latest) 2025.1 2025.0 2024.1 2024.0 10.3 10.2 10.1 10.0 9.10 9.9 9.8 9.7 9.6 9.5 9.4 9.3 9.2 9.1 9.0 8.2 8.1 8.0 7.6
3. Developers
4. Python sdk
5. Core concepts
6. connections

Connections

Python operators can accept predefined connections as inputs. Click here to learn more about connections in the AI product suite.

To define an operator that uses a connection, declare a parameter of the specialized Connection type from altair_aitools.ext.io.connections. Each operator supports exactly one connection parameter, and the connection object is automatically propagated through the operator's outputs (there is no need to return it explicitly). They also possess a safety mechanism preventing accidental secret spilling in logs or the like by hiding the contents of secret values behind a SecretStr object, which behaves like a string, but prevents printing it contents to logs by accident.

At runtime, the connection is passed as a dict-like object. You can access its values using fully qualified keys. For example:

user = conn["credentials.user"]
host = conn["db_config.host"]

Alternatively, the get method can be used to safely retrieve values without raising a KeyError and to optionally unwrap SecretStr values:

user = conn.get("credentials.password", plain=True, default=None)

While SecretStr values behave like regular strings (inheriting from str), unwrapping them with plain=True may be necessary in some cases.

None: Additional libraries (e.g., for the MSSQL domain authentication) are not supported currently.

Supported Connection Types

The GenericConnection type can be used for connections to new things which do not have a corresponding connection in the AI product suite.

The DBConnection type provides additional helper methods built on top of SQLAlchemy:

• to_url(): Returns a sqlalchemy.engine.URL object.
• to_engine(): Returns a sqlalchemy.engine.Engine instance.
• connect(): Provides a context-managed connection to the database engine.

Note: To establish a database connection, SQLAlchemy must be installed in the Python environment, along with the appropriate driver package for the database type. The SDK has been tested with the following combinations:

For local development, use 127.0.0.1 instead of localhost to avoid common connection issues.

Example

import pandas as pd
from altair_aitools.ext.io.connections import DBConnection
from sqlalchemy import Table, MetaData, insert


def read_db_table(conn: DBConnection, table_name: str) -> pd.DataFrame:
    """Reads all records from the specified database table."""
    engine = conn.to_engine()
    df = pd.read_sql_table(table_name, con=engine)
    engine.dispose()
    return df


def insert_db_record(conn: DBConnection, table_name: str, id: int, name: str) -> None:
    """Inserts a single record into the specified database table."""
    engine = conn.to_engine()
    table = Table(
        table_name,
        MetaData(),
        autoload_with=engine
    )
    stmt = insert(table).values(id=id, name=name)
    with conn.connect() as connection:
        connection.execute(stmt)
        connection.commit()

Last but by no means least, we will explore working with custom data objects.