Skip to content

Commit 825c507

Browse files
committed
docs(readme): document OLAP-scoped LowCardinality/FixedString/CODEC/SAMPLE BY
Adds four sections to the ClickHouse Schema chapter covering the new `Feature\OLAP` modifiers. The narrative makes clear that the methods are dialect-scoped at the type level — calling them on `MySQL`, `PostgreSQL`, `SQLite`, or `MongoDB` builders is a compile-time error, not a runtime throw. Also extends the ClickHouse "Supports the ... interfaces" line to list `Views`, `Databases`, and `OLAP` alongside the existing entries.
1 parent 1499ffc commit 825c507

1 file changed

Lines changed: 68 additions & 1 deletion

File tree

README.md

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2033,7 +2033,7 @@ $result = $schema->table('events')
20332033

20342034
ClickHouse uses `Nullable(type)` wrapping for nullable columns, `Enum8(...)` for enums, `Tuple(Float64, Float64)` for points, and `TYPE minmax GRANULARITY 3` for indexes. Foreign keys, stored procedures, triggers, generated columns, and CHECK constraints throw `UnsupportedException`.
20352035

2036-
Supports the `TableComments`, `ColumnComments`, and `DropPartition` interfaces.
2036+
Supports the `TableComments`, `ColumnComments`, `DropPartition`, `Views`, `Databases`, and `OLAP` interfaces.
20372037

20382038
**Engine selection** — choose from 10 variants of the `Engine` enum:
20392039

@@ -2130,6 +2130,73 @@ $schema->table('events')
21302130

21312131
Setting names must match `[A-Za-z_][A-Za-z0-9_]*`; string values are restricted to `[A-Za-z0-9_.\-+/]*`. Use ints / floats / booleans for everything else. Other dialects ignore the call.
21322132

2133+
**LowCardinality** — wrap a column type in `LowCardinality(...)` for compact dictionary-encoded storage on string columns with a small number of distinct values (status enums, type discriminators, country codes, category labels):
2134+
2135+
```php
2136+
$schema->table('events')
2137+
->bigInteger('id')->primary()
2138+
->string('status')->lowCardinality()
2139+
->string('country')->lowCardinality()->nullable()
2140+
->create();
2141+
2142+
// CREATE TABLE `events` (`id` Int64, `status` LowCardinality(String),
2143+
// `country` Nullable(LowCardinality(String))) ENGINE = MergeTree() ORDER BY (`id`)
2144+
```
2145+
2146+
`Nullable` is applied outside `LowCardinality` to match ClickHouse's required wrapping order. The `lowCardinality()` method is only available on the ClickHouse builder — callers on other dialects (`MySQL`, `PostgreSQL`, `SQLite`, `MongoDB`) cannot reach this method at all.
2147+
2148+
**FixedString(N)** — fixed-length string column. Use for ISO codes, hash digests, and other values whose byte length is known and constant:
2149+
2150+
```php
2151+
$schema->table('locations')
2152+
->bigInteger('id')->primary()
2153+
->fixedString('country_code', 2) // ISO 3166-1 alpha-2
2154+
->fixedString('currency_code', 3) // ISO 4217
2155+
->fixedString('digest', 32) // raw MD5
2156+
->create();
2157+
2158+
// CREATE TABLE `locations` (`id` Int64, `country_code` FixedString(2),
2159+
// `currency_code` FixedString(3), `digest` FixedString(32))
2160+
// ENGINE = MergeTree() ORDER BY (`id`)
2161+
```
2162+
2163+
Length must be at least 1. The `fixedString()` method is only available on the ClickHouse builder — the type has no portable mapping.
2164+
2165+
**Column-level CODEC** — append one or more compression codecs to a column. Multiple `codec()` calls accumulate and emit `CODEC(c1, c2, ...)`:
2166+
2167+
```php
2168+
$schema->table('metrics')
2169+
->bigInteger('id')->primary()
2170+
->datetime('ts', 3)->codec('Delta(4)')->codec('LZ4') // monotonic timestamps
2171+
->bigInteger('value')->codec('T64')->codec('LZ4') // integer column
2172+
->string('payload')->codec('ZSTD(3)') // text column
2173+
->create();
2174+
2175+
// CREATE TABLE `metrics` (`id` Int64,
2176+
// `ts` DateTime64(3) CODEC(Delta(4), LZ4),
2177+
// `value` Int64 CODEC(T64, LZ4),
2178+
// `payload` String CODEC(ZSTD(3))) ENGINE = MergeTree() ORDER BY (`id`)
2179+
```
2180+
2181+
Each codec string is emitted verbatim; supply codec arguments inline (`'Delta(4)'`, `'ZSTD(3)'`). Codec strings must not be empty or contain a semicolon. The `codec()` method is only available on the ClickHouse builder.
2182+
2183+
**SAMPLE BY** — declare a sampling expression for approximate-query support (`SELECT ... SAMPLE k`). Emitted after `ORDER BY` and before `TTL` / `SETTINGS`:
2184+
2185+
```php
2186+
$schema->table('events')
2187+
->bigInteger('id')->primary()
2188+
->bigInteger('user_id')->unsigned()
2189+
->sampleBy('user_id')
2190+
->create();
2191+
2192+
// CREATE TABLE `events` (`id` Int64, `user_id` UInt64) ENGINE = MergeTree()
2193+
// ORDER BY (`id`) SAMPLE BY user_id
2194+
```
2195+
2196+
The expression is emitted verbatim and must not be empty or contain a semicolon. `SAMPLE BY` only applies to engines that take an `ORDER BY` clause (the MergeTree family); using it with `Memory`, `Log`, `TinyLog`, or `StripeLog` throws `UnsupportedException`. The `sampleBy()` method is only available on the ClickHouse builder.
2197+
2198+
These OLAP-shaped modifiers are exposed on the ClickHouse dialect via the `Feature\OLAP` marker interface. Dialect-specific Column/Table subclasses surface the methods only when the underlying dialect implements the feature — so calling `->lowCardinality()` or `->sampleBy()` on a `MySQL`, `PostgreSQL`, `SQLite`, or `MongoDB` builder fails at the type level, with no runtime branch needed.
2199+
21332200
### SQLite Schema
21342201

21352202
```php

0 commit comments

Comments
 (0)