Function sql

marimo/_sql/sql.py:80–213

Execute a SQL query. By default, this uses duckdb to execute the query. Any dataframes in the global namespace can be used inside the query. You can also pass a custom engine to execute queries against other databases. The custom engine can be a DB-API 2.0 compatible connectio

(
    query: str,
    *,
    output: bool = True,
    engine: DBAPIConnection | None = None,
)

@mddoc
def sql(
    query: str,
    *,
    output: bool = True,
    engine: DBAPIConnection | None = None,
) -> Any:
    """
    Execute a SQL query.

    By default, this uses duckdb to execute the query. Any dataframes in the global
    namespace can be used inside the query.

    You can also pass a custom engine to execute queries against other databases.
    The custom engine can be a DB-API 2.0 compatible connection (PEP 249), including
    DB-API wrappers provided by ADBC drivers.

    The result of the query is displayed in the UI if output is True.

    Args:
        query: The SQL query to execute.
        output: Whether to display the result in the UI. Defaults to True.
        engine: Optional SQL engine to use. Can be a SQLAlchemy, DuckDB, Clickhouse,
            Redshift, Ibis, or DB-API 2.0 compatible connection (including ADBC drivers).
               If None, uses DuckDB.

    Returns:
        The result of the query.
    """
    if query is None or query.strip() == "":
        return None

    sql_engine: QueryEngine[Any]
    if engine is None:
        DependencyManager.require_many(
            "to execute sql",
            *_default_duckdb_deps(),
            source="kernel",
        )
        sql_engine = DuckDBEngine(connection=None)
    else:
        for engine_cls in SUPPORTED_ENGINES:
            if engine_cls.is_compatible(engine):
                sql_engine = engine_cls(
                    connection=engine, engine_name=VariableName("custom")
                )  # type: ignore
                break
        else:
            raise ValueError(
                "Unsupported engine. Must be a SQLAlchemy, Ibis, Clickhouse, DuckDB, Redshift, StarRocks or DBAPI 2.0 compatible engine."
            )

    try:
        df = sql_engine.execute(query)
    except Exception as e:
        if is_sql_parse_error(e):
            # NB. raising _from_ creates a noisier stack trace, but preserves
            # the original exception context for debugging.
            raise MarimoSQLException(