Immutable. This exact content is served forever at /api/v1/blob/d89fe40e3a1b95f9.
---
name: cosid-sharding
description: Design, implement, and validate CosId database sharding with core ModCycle, IntervalTimeline, CachedSharding, and SnowflakeLocalDateTimeConvertor APIs or ShardingSphere COSID_MOD, COSID_INTERVAL, and COSID_INTERVAL_SNOWFLAKE algorithms. Use for modulo routing, date/time partitions, Snowflake timestamp routing, exact/IN/range behavior, effective nodes, suffix naming, or routing tests. Do not use for choosing an ID generator unless sharding is the primary concern.
---
# Design CosId Sharding
Treat core Java sharding APIs and ShardingSphere configuration as separate integration surfaces. Verify the target CosId and ShardingSphere versions before copying property names.
## Workflow
1. Identify the sharding key type and every query operator that must route: exact, `IN`, and range.
2. Define physical nodes, naming, bounds, and future partition provisioning before selecting an algorithm.
3. Choose `ModCycle` for fixed-count numeric distribution or `IntervalTimeline` for time partitions.
4. Add Snowflake conversion only when the ID layout is known and aligned with the parser.
5. Build a routing matrix that covers boundaries, out-of-range values, and full-range queries.
## Core Algorithms
| API | Use | Important behavior |
|---|---|---|
| `ModCycle<T>` | Fixed number of numeric nodes | Exact route is `value % divisor`; current implementation requires non-negative values |
| `IntervalTimeline` | Bounded `LocalDateTime` partitions | Exact values outside the effective interval throw `IllegalArgumentException` |
| `SnowflakeLocalDateTimeConvertor` | Convert Snowflake `Long` or radix-62 `String` to time | Parser must match the generator epoch and bit layout |
| `CachedSharding<T>` | Reuse identical range results | `@Beta` and backed by an unbounded cache; use only for demonstrably low-cardinality repeated ranges |
### Modulo Example
```java
ModCycle<Long> sharding = new ModCycle<>(4, "t_order_");
String exact = sharding.sharding(42L); // t_order_2
Collection<String> range = sharding.sharding(Range.closed(1L, 10L));
```
A range spanning at least `divisor` consecutive values routes to every node. Open and unbounded ranges must be included in tests. Do not pass negative values unless the implementation has been changed to use floor-mod semantics.
### Interval Example
```java
IntervalTimeline timeline = new IntervalTimeline(
"t_order_",
Range.closed(
LocalDateTime.of(2024, 1, 1, 0, 0),
LocalDateTime.of(2024, 12, 31, 23, 59, 59)
),
IntervalStep.of(ChronoUnit.MONTHS),
DateTimeFormatter.ofPattern("yyyyMM")
);
String exact = timeline.sharding(LocalDateTime.of(2024, 3, 15, 10, 30));
Collection<String> range = timeline.sharding(Range.closed(
LocalDateTime.of(2024, 3, 1, 0, 0),
LocalDateTime.of(2024, 4, 30, 23, 59, 59)
));
```
Supported `IntervalStep` units are years, months, days, hours, minutes, and seconds. Ensure the suffix format is unique for the selected step.
### Snowflake Conversion
```java
SnowflakeIdStateParser parser = SnowflakeIdStateParser.of(snowflakeId);
SnowflakeLocalDateTimeConvertor convertor =
new SnowflakeLocalDateTimeConvertor(parser);
LocalDateTime time = convertor.toLocalDateTime(snowflakeId.generate());
```
The converter accepts only `Long` and radix-62 `String` values. It is not a general converter for arbitrary numeric types or custom string encodings.
## ShardingSphere
CosId algorithm availability and properties vary by ShardingSphere release. Inspect the target artifact or official source before emitting a type. When `COSID_MOD` is available, its divisor property is named `mod`, not `divisor`:
```yaml
rules:
- !SHARDING
tables:
t_order:
actualDataNodes: ds_0.t_order_$->{0..3}
tableStrategy:
standard:
shardingColumn: order_id
shardingAlgorithmName: t_order_mod
shardingAlgorithms:
t_order_mod:
type: COSID_MOD
props:
mod: 4
logic-name-prefix: t_order_
```
For ordinary time keys, configure an available `COSID_INTERVAL` implementation with `datetime-lower`, `datetime-upper`, `sharding-suffix-pattern`, `datetime-interval-unit`, and `datetime-interval-amount`.
Handle Snowflake interval routing by version:
- Prefer the core API shown above when application code owns routing; `SnowflakeIdStateParser.of(snowflakeId)` follows the actual generator's epoch and bit layout.
- In Apache ShardingSphere 5.4.0, `COSID_INTERVAL_SNOWFLAKE` reads only `epoch` and `zone-id` and hardcodes the default millisecond Snowflake layout. Use it only for that layout; `id-name` does not align a custom generator.
- For every other ShardingSphere release, verify that the CosId plugin and requested properties exist. Do not emit `COSID_INTERVAL_SNOWFLAKE` merely because an older document lists it.
- For a custom bit layout, use a version-verified integration that resolves the actual generator or a minimal `StandardShardingAlgorithm` that delegates to `SnowflakeIdStateParser` and `IntervalTimeline`.
Ensure `actualDataNodes` enumerates only valid physical suffixes; a daily numeric range such as `${20240101..20241231}` also generates impossible dates and must not be used.
## Validation Matrix
Test at least:
- first and last exact key for every boundary node;
- one `IN` set spanning multiple nodes;
- closed, open, unbounded, empty, and out-of-domain ranges;
- negative input rejection for `ModCycle`;
- an interval transition such as month-end or year-end;
- Snowflake values generated with the actual epoch, unit, and bit layout;
- equality between algorithm effective nodes and provisioned physical nodes.
## Response Contract
Return the chosen algorithm, physical naming model, minimal Java or version-matched ShardingSphere configuration, and the routing matrix. Call out any partition provisioning or cache-growth risk explicitly.