Add premium geo dimension columns to usage events

[lohanidamodar]

What

Adds nine event-only premium geo dimensions to the usage schema, sourced from the premium geo service (appwrite/geo-premium) /ips/{ip} response and consumed by cloud's StatsUsage worker (CLO-4541):

city, continentCode, subdivisions, isp, autonomousSystemNumber, autonomousSystemOrganization, connectionType, connectionUsageType, connectionOrganization

Changes

• Metric::EVENT_COLUMNS / getEventSchema() — the 9 columns as optional strings (event-only; absent from the gauge schema).
• Adapter/ClickHouse::getColumnType() — lower-cardinality dims (continentCode, subdivisions, connectionType, connectionUsageType, autonomousSystemNumber) map to LowCardinality(Nullable(String)); the high-cardinality dims (city, isp, autonomousSystemOrganization, connectionOrganization) to plain Nullable(String).
• Existing tables auto-materialize the columns on setup() via the ensureDimColumns → ADD COLUMN IF NOT EXISTS path. Gauges, primary keys, and indexes are unchanged.
• Tests + CHANGELOG (0.10.0).

Compatibility

Purely additive and backward-compatible. Intended release: 0.10.0 (cloud pins 0.10.*).

Notes

A one-off idempotent ClickHouse backfill script for existing production tables is kept out of this PR (ops artifact, run manually).

[greptile-apps]

Greptile Summary

This PR adds nine event-only premium geo dimension columns (city, continentCode, subdivisions, isp, autonomousSystemNumber, autonomousSystemOrganization, connectionType, connectionUsageType, connectionOrganization) sourced from the appwrite/geo-premium service, targeting the 0.10.0 release.

• Five lower-cardinality dims (continentCode, subdivisions, connectionType, connectionUsageType, autonomousSystemNumber) are mapped to LowCardinality(Nullable(String)) in ClickHouse; the four high-cardinality dims (city, isp, autonomousSystemOrganization, connectionOrganization) use plain Nullable(String). All nine receive CODEC(ZSTD(3)), consistent with the existing pattern for similar columns.
• Changes are purely additive: columns are absent from the gauge schema and primary key, and existing tables auto-materialize them via the ADD COLUMN IF NOT EXISTS path on setup().
• New unit tests cover the type-routing logic via reflection (no live ClickHouse required) and assert event-only presence across schema and column constant.

Confidence Score: 5/5

Purely additive schema change with no gauge or primary-key impact; safe to merge.

All nine columns are correctly scoped to event-only paths, the ClickHouse type and codec assignments are consistent with existing patterns, and the idempotent ADD COLUMN IF NOT EXISTS migration path prevents any breakage on existing tables. Tests cover both column-type routing logic and schema-level constraints.

No files require special attention.

Important Files Changed

Filename	Overview
src/Usage/Metric.php	Adds 9 premium geo columns to EVENT_COLUMNS and getEventSchema() as optional strings; columns are correctly absent from the gauge schema. Size 2 for continentCode is appropriate for 2-letter continent codes.
src/Usage/Adapter/ClickHouse.php	Correctly routes 5 lower-cardinality dims to LowCardinality(Nullable(String)) and all 9 new columns to ZSTD(3) codec, consistent with the existing pattern for osVersion/deviceModel/etc.
tests/Usage/Adapter/ClickHouseColumnTypeTest.php	New unit test using reflection to validate LowCardinality vs Nullable(String) routing for all 9 premium geo columns without requiring a live ClickHouse instance.
tests/Usage/Adapter/ClickHouseSchemaTest.php	Extends existing schema DDL assertions to cover continentCode, connectionType, city, and isp; also verifies the new columns are absent from the low-cardinality primary key list.
tests/Usage/MetricTest.php	Adds testPremiumGeoColumnsArePresentAsEventStrings() which asserts all 9 columns exist in EVENT_COLUMNS and the event schema as optional strings, and are absent from the gauge schema.
CHANGELOG.md	Promotes Unreleased section to 0.10.0 with accurate documentation of all 9 new columns and their ClickHouse type assignments.

_{Reviews (2): Last reviewed commit: "Add premium geo dimension columns to usa..." | Re-trigger Greptile}

[greptile-apps]

autonomousSystemNumber is defined with size 255 while every other new premium geo string column in the same block uses 256. Given that the other fields in this group (city, subdivisions, isp, etc.) all use 256, this looks like an accidental mismatch rather than a deliberate choice — ASNs are short strings, so the difference has no practical impact, but the inconsistency is worth correcting for schema coherence.

Suggested change

	$stringColumn('autonomousSystemNumber', 255),
	$stringColumn('autonomousSystemNumber', 256),

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/Usage/Metric.php
Line: 643

Comment:
`autonomousSystemNumber` is defined with `size` 255 while every other new premium geo string column in the same block uses 256. Given that the other fields in this group (`city`, `subdivisions`, `isp`, etc.) all use 256, this looks like an accidental mismatch rather than a deliberate choice — ASNs are short strings, so the difference has no practical impact, but the inconsistency is worth correcting for schema coherence.

```suggestion
            $stringColumn('autonomousSystemNumber', 256),
```

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!