Master ShardingSphere: 12 Sharding Strategies and Algorithms with Full Code Samples

Overview

ShardingSphere‑JDBC separates the sharding key (the column used for partitioning) from the sharding algorithm (the logic that maps the key value to a physical shard). This design enables a wide range of sharding scenarios without writing custom code.

All demo projects are available at: https://github.com/chengxy-nds/Springboot-Notebook/tree/master/shardingsphere101/shardingsphere-algorithms

Sharding Strategies

Standard Strategy

Applicable when a single sharding key is used. Supports =, IN, and range operators (BETWEEN, >, <, >=, <=). Requires shardingColumn and shardingAlgorithmName.

spring:
  shardingsphere:
    rules:
      sharding:
        tables:
          t_order:
            shardingColumn: order_id
            shardingAlgorithmName: standard_alg
        shardingAlgorithms:
          standard_alg:
            type: STANDARD
            props:
              sharding-column: order_id

Inline (Row‑Expression) Strategy

Suitable for simple single‑key scenarios. The algorithm is defined directly in algorithm-expression using a Groovy expression. By default only = and IN are supported; range queries can be enabled with allow-range-query-with-inline-sharding=true (which disables sharding and performs full‑table routing).

spring:
  shardingsphere:
    rules:
      sharding:
        shardingAlgorithms:
          t_order_inline:
            type: INLINE
            props:
              algorithm-expression: "t_order_${order_id % 3}"
              allow-range-query-with-inline-sharding: false

Complex Strategy

Handles multiple sharding keys. Use shardingColumns (comma‑separated) and a Groovy expression that combines the keys, e.g. (order_id + user_id) % 2. Must be paired with a COMPLEX algorithm.

spring:
  shardingsphere:
    rules:
      sharding:
        tables:
          t_order:
            shardingColumns: order_id,user_id
            shardingAlgorithmName: complex_inline_alg
        shardingAlgorithms:
          complex_inline_alg:
            type: COMPLEX_INLINE
            props:
              sharding-columns: order_id,user_id
              algorithm-expression: "t_order_${(order_id+user_id)%3}"

Hint Strategy

When the sharding key is absent from the SQL or the application wants to force routing, values are supplied programmatically via HintManager.

HintManager hint = HintManager.getInstance();
hint.addDatabaseShardingValue("t_order", 0);
hint.addTableShardingValue("t_order", 1);
// execute SQL
hint.close();

None (No Sharding) Strategy

Disables sharding; all operations are routed to every database and table (full‑table routing).

Sharding Algorithms

Automatic Sharding (auto‑tables)

Defines auto‑tables that automatically create physical tables based on a sharding algorithm.

spring:
  shardingsphere:
    rules:
      sharding:
        autoTables:
          t_order:
            actualDataSources: db${0..1}
            shardingStrategy:
              standard:
                shardingColumn: order_date
                shardingAlgorithmName: t_order_mod
        shardingAlgorithms:
          t_order_mod:
            type: MOD
            props:
              sharding-count: 6

MOD

Simple modulo algorithm: (shardingKey / dbInstance) % sharding-count. Only sharding-count is required.

type: MOD
props:
  sharding-count: 6

HASH_MOD

Applies a hash function before the modulo operation. Same configuration as MOD with type: HASH_MOD.

type: HASH_MOD
props:
  sharding-count: 6

VOLUME_RANGE

Distributes rows based on a fixed capacity per shard. Required properties: range-lower, range-upper, sharding-volume. Example: 10 rows per shard within the range 2‑20.

type: VOLUME_RANGE
props:
  range-lower: 2
  range-upper: 20
  sharding-volume: 10

BOUNDARY_RANGE

Uses explicit boundary values to map key ranges to shards. Property sharding-ranges defines the cut points (e.g., 10,20,30,40).

type: BOUNDARY_RANGE
props:
  sharding-ranges: 10,20,30,40

AUTO_INTERVAL

Time‑based interval sharding. Properties: datetime-lower, datetime-upper, sharding-seconds (duration of a single shard in seconds). Example creates a new shard for each year.

type: AUTO_INTERVAL
props:
  datetime-lower: '2023-01-01 00:00:00'
  datetime-upper: '2025-01-01 00:00:00'
  sharding-seconds: 31536000

INLINE (Standard Algorithm)

Row‑expression algorithm using Groovy. Supports only = and IN unless allow-range-query-with-inline-sharding is set to true (which disables sharding).

type: INLINE
props:
  algorithm-expression: "t_order_${order_id % 3}"
  allow-range-query-with-inline-sharding: false

INTERVAL

Time‑range sharding with customizable suffix pattern and interval unit. Key properties: datetime-pattern: format of the sharding key (Java DateTimeFormatter). datetime-lower / datetime-upper: inclusive lower and exclusive upper bounds. sharding-suffix-pattern: suffix for physical tables (e.g., yyyyMM). datetime-interval-unit and datetime-interval-amount: unit and step size (e.g., MONTHS, 1).

type: INTERVAL
props:
  datetime-pattern: "yyyy-MM-dd HH:mm:ss"
  datetime-lower: "2024-01-01 00:00:00"
  datetime-upper: "2024-06-30 23:59:59"
  sharding-suffix-pattern: "yyyyMM"
  datetime-interval-unit: "MONTHS"
  datetime-interval-amount: 1

COSID_MOD

Modulo algorithm based on CosId distributed IDs. Requires mod (shard count) and logic-name-prefix (table prefix).

type: COSID_MOD
props:
  mod: 3
  logic-name-prefix: t_order_

COSID_INTERVAL

Fixed‑time‑range sharding using CosId. Includes time‑zone, prefix, suffix pattern, and interval settings.

type: COSID_INTERVAL
props:
  zone-id: "Asia/Shanghai"
  logic-name-prefix: t_order_
  sharding-suffix-pattern: "yyyyMM"
  datetime-lower: "2024-01-01 00:00:00"
  datetime-upper: "2024-12-31 00:00:00"
  datetime-interval-unit: "MONTHS"
  datetime-interval-amount: 1

COSID_INTERVAL_SNOWFLAKE

Same as COSID_INTERVAL but the underlying ID generator uses the Snowflake algorithm for better distribution under high throughput.

type: COSID_INTERVAL_SNOWFLAKE
props:
  zone-id: "Asia/Shanghai"
  logic-name-prefix: t_order_
  sharding-suffix-pattern: "yyyyMM"
  datetime-lower: "2024-01-01 00:00:00"
  datetime-upper: "2024-12-31 00:00:00"
  datetime-interval-unit: "MONTHS"
  datetime-interval-amount: 1

COMPLEX_INLINE

Combines multiple sharding keys with a Groovy expression. Requires sharding-columns and algorithm-expression. Must be used with the COMPLEX strategy.

type: COMPLEX_INLINE
props:
  sharding-columns: order_id,user_id
  algorithm-expression: "t_order_${(order_id+user_id)%3}"
  allow-range-query-with-inline-sharding: false

HINT_INLINE

Force routing via programmatic hints. The expression receives the value supplied by HintManager (default variable value).

type: HINT_INLINE
props:
  algorithm-expression: "db${Integer.valueOf(value) % 2}"

type: HINT_INLINE
props:
  algorithm-expression: "t_order_${Integer.valueOf(value) % 3}"

Usage example:

HintManager hint = HintManager.getInstance();
hint.clearShardingValues();
hint.addDatabaseShardingValue("t_order", 0);
hint.addTableShardingValue("t_order", 1);
jdbcTemplate.execute("INSERT INTO t_order(id,order_date,order_id,order_number,customer_id,total_amount,interval_value,user_id) VALUES (1,'2024-03-20 00:00:00',1,'1',1,1.00,'2024-01-01 00:00:00',1);");
hint.close();

Key Considerations

Range queries are not supported by INLINE and COMPLEX_INLINE unless explicitly enabled, which disables sharding and falls back to full‑table routing.

When using VOLUME_RANGE, values below range‑lower are placed in the first shard, and values above range‑upper are placed in the last shard. AUTO_INTERVAL and INTERVAL require the sharding key to be a datetime string matching datetime-pattern.

CosId‑based algorithms provide uniform distribution for high‑throughput workloads.

Hint‑based routing should be used only with the hint strategy; otherwise an error is thrown.

Summary

ShardingSphere‑JDBC offers twelve built‑in sharding algorithms covering automatic, standard, complex, and hint‑based categories. Selecting the appropriate strategy and algorithm depends on the business requirements such as key cardinality, query patterns, data volume, and time‑based partitioning. The provided YAML examples and code snippets illustrate how to configure each algorithm and verify data distribution.