pola-rs/polars · error · ValueError

only a single SQL query string is accepted for adbc, got a {

Error message

only a single SQL query string is accepted for adbc, got a {qualified_type_name(query)!r} type

What it means

Raised by read_database_uri() when engine='adbc' and query is not a single string. Unlike connectorx, which can take multiple queries, the ADBC path executes exactly one SQL statement per call.

Source

Thrown at py-polars/src/polars/io/database/functions.py:520

            raise ValueError(msg)
        if pre_execution_query:
            issue_unstable_warning(
                "the 'pre-execution-query' parameter is considered unstable."
            )
        return _read_sql_connectorx(
            query,
            connection_uri=uri,
            partition_on=partition_on,
            partition_range=partition_range,
            partition_num=partition_num,
            protocol=protocol,
            schema_overrides=schema_overrides,
            pre_execution_query=pre_execution_query,
        )
    elif engine == "adbc":
        if not isinstance(query, str):
            msg = f"only a single SQL query string is accepted for adbc, got a {qualified_type_name(query)!r} type"
            raise ValueError(msg)
        if pre_execution_query:
            msg = "the 'adbc' engine does not support use of `pre_execution_query`"
            raise ValueError(msg)
        return _read_sql_adbc(
            query,
            connection_uri=uri,
            schema_overrides=schema_overrides,
            execute_options=execute_options,
        )
    else:
        msg = f"engine must be one of {{'connectorx', 'adbc'}}, got {engine!r}"
        raise ValueError(msg)

View on GitHub (pinned to df599052da)

Solutions

Pass one SQL string per call and loop over the queries yourself
Or use engine='connectorx', which accepts multiple queries in one call
Check the return shape: adbc returns a single DataFrame per call

Example fix

# before
pl.read_database_uri([q1, q2], uri, engine="adbc")

# after
frames = [pl.read_database_uri(q, uri, engine="adbc") for q in (q1, q2)]

Defensive patterns

Strategy: type-guard

Validate before calling

queries = [query] if isinstance(query, str) else list(query)
frames = [pl.read_database_uri(q, uri, engine="adbc") for q in queries]

Type guard

def is_single_query(query: object) -> TypeGuard[str]:
    return isinstance(query, str)

Prevention

Normalise query inputs to a list of strings and loop when engine='adbc'
Reserve multi-query batches for the connectorx engine
Validate query type in shared wrappers before dispatching to an engine

When it happens

Trigger: pl.read_database_uri(['SELECT ...', 'SELECT ...'], uri, engine='adbc'); passing a tuple of queries or a non-str object.

Common situations: Reusing a multi-query list that worked with the connectorx engine; generic code that batches several statements and chooses the engine dynamically.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/41f3b153bc258e2c. Report an issue: GitHub.