[Feature]: Onboarding Profiling: Tracer bullet — schema + first-N sample end-to-end

Parent PRD

#172

What to build

The first end-to-end slice of the onboarding data profiling feature. This establishes the full backend-to-frontend stack: new Pydantic models, a ProfileQueryBuilder utility (pure SQL generation), a ProfilingManager controller, FastAPI routes, and a TableProfiler React component with Schema and Sample tabs.

Backend:

• New profiling.py Pydantic models: SchemaInfo, ColumnInfo, SampleRequest, SampleResponse, SampleMode enum, TableCount
• New ProfileQueryBuilder: pure functions that take FQN + parameters → SQL strings. Start with build_sample_query(fqn, mode=first, limit) and build_count_query(fqn).
• New ProfilingManager: get_schema(fqn) via UC tables API, get_count(fqn) via UC metadata or SQL fallback, get_sample(fqn, mode=first, limit) via Statement Execution API. Uses OBO workspace client. Stateless.
• New profiling_routes.py with three endpoints:
  • GET /api/profiling/{fqn:path}/schema
  • GET /api/profiling/{fqn:path}/count
  • GET /api/profiling/{fqn:path}/sample?mode=first&limit=100
• Startup wiring: instantiate ProfilingManager, add to app.state, add dependency getter
• Hard guardrails: max limit of 10,000 rows, query timeout

Frontend:

• New TableProfiler component: inline panel with two tabs (Schema, Sample Data)
• Props: fqn, assetType ("table" | "view"), optional initialSchema, onClose, defaultMode, defaultLimit
• Schema tab loads instantly from /schema endpoint; Sample tab fetches on mount with first-N mode
• Results cached in React state within the component (no re-fetch on tab switch)
• Error states: no warehouse configured → schema works, sample disabled with banner; permission denied → friendly message; table not found → clear message

Tests:

• Unit tests for ProfileQueryBuilder.build_sample_query and build_count_query
• Unit tests for ProfilingManager with mocked WorkspaceClient (schema retrieval, error handling)
• Integration test for routes with TestClient

See PRD #172 sections "API Design", "Error Handling", and "Testing Decisions" for full details.

Acceptance criteria

• GET /api/profiling/{fqn}/schema returns column names, types, and comments from UC metadata
• GET /api/profiling/{fqn}/count returns row count
• GET /api/profiling/{fqn}/sample?mode=first&limit=100 returns first 100 rows as JSON
• limit parameter is capped at 10,000
• Frontend TableProfiler component renders with Schema and Sample tabs
• Schema tab loads without warehouse; Sample tab shows banner when no warehouse configured
• Permission denied and table-not-found errors show friendly messages (non-fatal)
• ProfileQueryBuilder unit tests cover first-N sample and count SQL generation
• ProfilingManager unit tests cover schema retrieval and error handling with mocked workspace client

Blocked by

None — can start immediately.

User stories addressed

• User story 1
• User story 9
• User story 12
• User story 24
• User story 25

Start with PRD #172, especially its API Design, Error Handling, and Testing Decisions sections, then map the backend work across profiling.py, ProfileQueryBuilder, ProfilingManager, and profiling_routes.py. Review the TableProfiler entry point and the named unit and TestClient integration tests; done means the listed schema, count, sample, guardrail, error-state, and frontend acceptance criteria are covered.