cocoindex-io/cocoindex · error · ImportError

google-cloud-bigquery is required to use the BigQuery connec

Error message

google-cloud-bigquery is required to use the BigQuery connector. Please install cocoindex[bigquery].

What it means

Raised by _connect in the BigQuery connector when the google-cloud-bigquery package (or its google.oauth2 dependency) is not installed. The connector lazily imports it at connection time and converts the ImportError into an actionable message pointing at the cocoindex[bigquery] extra.

Source

Thrown at python/cocoindex/connectors/bigquery/_target.py:406

) -> tuple[QueryParam, ...]:
    pk_columns = [table_schema.columns[pk] for pk in table_schema.primary_key]
    params: list[QueryParam] = []
    idx = 0
    for key in keys:
        for key_idx, value in enumerate(key):
            col = pk_columns[key_idx]
            params.append(QueryParam(f"p{idx}", _query_param_type(col), value))
            idx += 1
    return tuple(params)


@contextmanager
def _connect(config: ConnectionConfig) -> Iterator[Any]:
    try:
        from google.cloud import bigquery  # type: ignore[import-not-found]
        from google.oauth2 import service_account  # type: ignore[import-not-found]
    except ImportError as e:
        raise ImportError(
            "google-cloud-bigquery is required to use the BigQuery connector. "
            "Please install cocoindex[bigquery]."
        ) from e

    credentials = None
    if config.credentials_path:
        credentials = service_account.Credentials.from_service_account_file(  # type: ignore[no-untyped-call]
            config.credentials_path
        )

    client = bigquery.Client(
        project=config.project,
        credentials=credentials,
        location=config.location,
    )
    try:
        yield client
    finally:

View on GitHub (pinned to e84aa99b32)

Solutions

1. Install the extra: `pip install "cocoindex[bigquery]"` (or `uv add "cocoindex[bigquery]"`).
2. Verify the import works: `python -c "from google.cloud import bigquery"`.
3. If using service-account auth, also confirm google-auth/google-oauth2 are present (they come with the extra).

Example fix

// before
pip install cocoindex
// after
pip install "cocoindex[bigquery]"

try:
    import google.cloud.bigquery  # noqa
except ImportError:
    raise SystemExit('Run: pip install "cocoindex[bigquery]"')

try:
    app.update()
except ImportError as e:
    if "cocoindex[bigquery]" in str(e):
        # surface install hint to user
        ...

When it happens

Trigger: Declaring/using a BigQuery target (which triggers _apply_actions -> _connect) in an environment where `pip install cocoindex[bigquery]` was not run.

Common situations: Installing base cocoindex in CI or a fresh venv without extras; switching to the BigQuery connector in an existing project; using a slim Docker image that omits optional dependencies.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• aiohttp is required for Doris connector. Install it with: pi
• pymysql is required for Doris connector DDL operations. Inst
• Primary key column '{pk}' not found in columns: {list(self.c
• record_type must be a record type (dataclass, NamedTuple, Py
• Invalid BigQuery {kind}: {name!r}

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/8025d3f3b278b50d. Report an issue: GitHub.