## Summary
- Catalog enrichment for `query_mode='remote'` rows: `rows`, `size_bytes`, `partition_by`, `clustered_by` per table (BQ + Keboola providers).
- `/api/v2/schema/{id}` cache miss: 2 BQ jobs → 1 (-50%) via shared `fetch_bq_columns_full`.
- All four catalog/schema/sample/metadata caches flush on registry change; single-row re-warm scheduled.
- Automatic cache warmup at server startup (bounded concurrency, opt-out via `AGNES_SKIP_CACHE_WARMUP=1`).
- SSE-driven freshness toolbar on `/admin/tables` with progress bar, log, and per-row badge.
- New admin doc `docs/admin/query-modes.md` — single source of truth on `local` / `remote` / `materialized` choice.
Closes #155.
Closes #156.
## Test plan
- [x] 65+ targeted tests pass across 11 new test modules + 3 modified ones.
- [x] No DB migration; no wire-break; `MIN_COMPAT_CLI_VERSION` unchanged.
- [ ] Reviewer: register a remote BQ table via `/admin/tables`, observe the toolbar populates within ~2 s and the per-row badge transitions warming → fresh.
- [ ] Reviewer: trigger `Re-warm all`, verify SSE log scrolls and `cacheWarmupBar` progresses.
- [ ] Reviewer: edit a registered row's bucket, verify `agnes schema <id>` returns updated columns immediately (no 1-hour staleness).
- [ ] Reviewer: confirm `agnes admin register-table --query-mode remote` prints the new IAM-smoke-check hint.
## Notable design decisions
- BigQuery `INFORMATION_SCHEMA.TABLE_STORAGE` is the only valid scope for size+rows (verified live 2026-05-07; dataset-scoped doesn't exist). Region resolved from `instance.yaml.data_source.bigquery.location` → `bq.client().get_dataset(...)` → fall back to legacy `__TABLES__`.
- VIEW handling: TABLE_STORAGE returns no rows for views, fall through to `__TABLES__` (also empty) → `TableMetadata(rows=None, size_bytes=None, partition_by=..., clustered_by=...)`. Null size signals analyst Claude to apply existing CLAUDE.md guidance.
- `size_bytes` is `active_logical_bytes + long_term_logical_bytes` — full BQ scan reads both; reporting only active undercounts aged partitioned tables.
- Source-agnostic provider seam: per-source `connectors/<source>/metadata.py:fetch(MetadataRequest)`; dispatcher in `app/api/v2_catalog.py:_metadata_provider_for` lazily imports per source_type so a Keboola-only deployment doesn't pay the BQ-extension import cost.
- Warmup non-blocking: FastAPI `lifespan` schedules `asyncio.create_task(_warm_catalog_caches_bg)` before `yield`. Per-row failures isolated.
## Out of scope
- Profile / column histograms / dimension cardinality for remote tables (separate issue).
- Onboarding nudge ("you have 0 remote tables, consider registering some BQ ones") — separate UX call.
- Provider plug-in registration via entry-points (the dispatch table is a hardcoded if-tree today; one line per future source).
## Release
Bumps `pyproject.toml` 0.46.1 → 0.47.0 (main shipped 0.46.0 + 0.46.1 during this PR — see commit `d98976ec`). New CHANGELOG section under `## [0.47.0] — 2026-05-07`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/keboola/agnes-the-ai-analyst/pull/223" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1" alt="Open in Devin Review">
</picture>
</a>
<!-- devin-review-badge-end -->
75 lines
2.7 KiB
Python
75 lines
2.7 KiB
Python
"""Keboola metadata provider — happy + unconfigured + api-error paths."""
|
|
|
|
from unittest.mock import MagicMock, patch
|
|
|
|
import pytest
|
|
|
|
from app.api._metadata_models import MetadataRequest, TableMetadata
|
|
|
|
|
|
@pytest.fixture
|
|
def req():
|
|
return MetadataRequest(
|
|
table_id="orders", bucket="in.c-crm", source_table="orders",
|
|
)
|
|
|
|
|
|
def test_happy_path_returns_populated_metadata(req, monkeypatch):
|
|
from connectors.keboola import metadata
|
|
# KeboolaClient(token=None, url=None) reads env vars; pretend they're set.
|
|
monkeypatch.setenv("KEBOOLA_STACK_URL", "https://connection.keboola.com")
|
|
monkeypatch.setenv("KEBOOLA_STORAGE_TOKEN", "tok")
|
|
|
|
with patch("connectors.keboola.metadata.KeboolaStorageClient") as MockStorage:
|
|
instance = MockStorage.return_value
|
|
instance.get_table_info.return_value = {
|
|
"rowsCount": 1234,
|
|
"dataSizeBytes": 500_000,
|
|
"primaryKey": ["id"],
|
|
}
|
|
result = metadata.fetch(req)
|
|
|
|
assert result == TableMetadata(
|
|
rows=1234,
|
|
size_bytes=500_000,
|
|
partition_by=None,
|
|
clustered_by=None,
|
|
)
|
|
|
|
|
|
def test_returns_none_when_unconfigured(req, monkeypatch):
|
|
"""No KEBOOLA_STACK_URL / KEBOOLA_STORAGE_TOKEN env → return None."""
|
|
from connectors.keboola import metadata
|
|
monkeypatch.delenv("KEBOOLA_STACK_URL", raising=False)
|
|
monkeypatch.delenv("KEBOOLA_STORAGE_TOKEN", raising=False)
|
|
assert metadata.fetch(req) is None
|
|
|
|
|
|
def test_returns_none_on_storage_api_error(req, monkeypatch):
|
|
"""`StorageApiError` from get_table_info → log + return None."""
|
|
from connectors.keboola import metadata
|
|
from connectors.keboola.storage_api import StorageApiError
|
|
monkeypatch.setenv("KEBOOLA_STACK_URL", "https://x.keboola.com")
|
|
monkeypatch.setenv("KEBOOLA_STORAGE_TOKEN", "tok")
|
|
|
|
with patch("connectors.keboola.metadata.KeboolaStorageClient") as MockStorage:
|
|
instance = MockStorage.return_value
|
|
instance.get_table_info.side_effect = StorageApiError(
|
|
"404 not found", status=404, body={},
|
|
)
|
|
assert metadata.fetch(req) is None
|
|
|
|
|
|
def test_table_id_uses_bucket_dot_source_table(req, monkeypatch):
|
|
"""Storage API path is `<bucket>.<source_table>`."""
|
|
from connectors.keboola import metadata
|
|
monkeypatch.setenv("KEBOOLA_STACK_URL", "https://x.keboola.com")
|
|
monkeypatch.setenv("KEBOOLA_STORAGE_TOKEN", "tok")
|
|
|
|
with patch("connectors.keboola.metadata.KeboolaStorageClient") as MockStorage:
|
|
instance = MockStorage.return_value
|
|
instance.get_table_info.return_value = {
|
|
"rowsCount": 0, "dataSizeBytes": 0,
|
|
}
|
|
metadata.fetch(req)
|
|
instance.get_table_info.assert_called_once_with("in.c-crm.orders")
|