Использование выражения партиционирования (рекомендуется)¶

Начиная с v3.0, StarRocks поддерживает выражение пртицирования (expression partitioning, ранее — automatic partitioning), более гибкий и удобный способ. Этот метод подходит для большинства сценариев, например для запросов и управления данными по непрерывным временным диапазонам или по ENUM‑значениям.

Достаточно указать простое выражение партиционирования при создании таблицы. Во время загрузки данных StarRocks автоматически создаёт партиции на основе данных и правила, заданного в выражении. Вам больше не нужно вручную создавать множество партиций на этапе создания таблицы и настраивать свойства динамического партиционирования.

Начиная с v3.4, использование выражений партицирования дополнительно оптимизировано: унифицированы все стратегии партиционирования и поддерживаются более сложные решения. Рекомендуется в большинстве случаев и в будущих релизах заменит другие стратегии.

Начиная с v3.5, StarRocks поддерживает слияние expression‑партиций на основе time‑функции для оптимизации эффективности хранения и производительности запросов.

Партиционирование на основе простого time‑функционального выражения¶

Если вы часто запрашиваете и управляете данными по непрерывным временным диапазонам, укажите столбец типа даты (DATE или DATETIME) в качестве столбца партиционирования и задайте год, месяц, день или час как гранулярность партиции в time‑функции. StarRocks автоматически создаст партиции и определит их границы начала и конца по загруженным данным и выражению партиционирования.

Однако в особых случаях, например когда исторические данные нужно делить по месяцам, а свежие — по дням, используйте range partitioning.

Синтаксис¶

PARTITION BY expression
...
[ PROPERTIES( { 'partition_live_number' = 'xxx' | 'partition_retention_condition' = 'expr' } ) ]

expression::=
    { date_trunc ( <time_unit> , <partition_column> ) |
      time_slice ( <partition_column> , INTERVAL <N> <time_unit> [ , boundary ] ) }

Параметры¶

expression¶

Обязательный: ДА Описание: Простое time‑выражение с функциями date_trunc или time_slice. Для time_slice параметр boundary передавать не нужно, поскольку допустимое значение — floor (значение ceil недопустимо).

time_unit¶

Обязательный: ДА Описание: Гранулярность партиционирования: hour, day, month или year. Гранулярность week не поддерживается. Для hour столбец партиционирования должен быть типа DATETIME, тип DATE не допускается.

partition_column¶

Обязательный: ДА Описание: Имя столбца партиционирования. Типы: только DATE или DATETIME. Допускает значения NULL Для date_trunc допустимы DATE и DATETIME; для time_slice — только DATETIME. Диапазон для DATE: [0000-01-01 ~ 9999-12-31]; для DATETIME: [0000-01-01 01:01:01 ~ 9999-12-31 23:59:59]. Поддерживается только один столбец партиционирования.

partition_live_number¶

Обязательный: НЕТ Описание: Число последних партиций, которые следует сохранять. Партиции упорядочиваются хронологически, при этом текущая дата берётся за опорную; более старые партиции удаляются. Планировщик FE управляет удалением; интервал настраивается параметром dynamic_partition_check_interval_seconds (по умолчанию 600 секунд). Пример: текущая дата 2023‑04‑04, partition_live_number = 2, имеются партиции p20230401, p20230402, p20230403, p20230404 — сохраняются p20230403 и p20230404, остальные удаляются. Если загружены «грязные» данные будущих дат (5 и 6 апреля), сохранятся p20230403, p20230404, p20230405, p20230406.

partition_retention_condition¶

Начиная с v3.5.0, нативные таблицы StarRocks поддерживают Common Partition Expression TTL.

partition_retention_condition: выражение, задающее партиции для динамического сохранения. Партиции, не удовлетворяющие условию, регулярно удаляются. Пример: 'partition_retention_condition' = 'dt >= CURRENT_DATE() - INTERVAL 3 MONTH'.

• Выражение может содержать только столбцы партиционирования и константы. Непартиционные столбцы не поддерживаются.

• Применение к List и Range: для List‑партиций поддерживается удаление по выражению; для Range‑партиций удаление возможно, только если предикаты поддерживаются механизмом отсечения партиций (partition pruning) в FE.

Примечания по использованию¶

• При загрузке StarRocks автоматически создаёт партиции на основе данных; если загрузка завершится неудачно, такие партиции не удаляются автоматически.

• По умолчанию максимум автоматически создаваемых партиций за одну загрузку равен 4096 и настраивается параметром FE auto_partition_max_creation_number_per_load.

• Правила именования партиций совпадают с правилами динамического партиционирования.

Примеры¶

Пример 1. Частые запросы по дням. Используйте date_trunc() со столбцом event_day и гранулярностью day. Данные одного дня в одной партиции; отсечение партиций значительно ускоряет запросы.

CREATE TABLE site_access1 (
    event_day DATETIME NOT NULL,
    site_id INT DEFAULT '10',
    city_code VARCHAR(100),
    user_name VARCHAR(32) DEFAULT '',
    pv BIGINT DEFAULT '0'
)
DUPLICATE KEY(event_day, site_id, city_code, user_name)
PARTITION BY date_trunc('day', event_day)
DISTRIBUTED BY HASH(event_day, site_id);

При загрузке двух строк ниже StarRocks автоматически создаст две партиции p20230226 и p20230227 с диапазонами [2023‑02‑26 00:00:00, 2023‑02‑27 00:00:00) и [2023‑02‑27 00:00:00, 2023‑02‑28 00:00:00) соответственно. Дальнейшие данные маршрутизируются в соответствующие партиции.

-- insert two data rows
INSERT INTO site_access1  
    VALUES ("2023-02-26 20:12:04",002,"New York","Sam Smith",1),
           ("2023-02-27 21:06:54",001,"Los Angeles","Taylor Swift",1);

-- view partitions
mysql > SHOW PARTITIONS FROM site_access1;
+-------------+---------------+----------------+---------------------+--------------------+--------+--------------+------------------------------------------------------------------------------------------------------+--------------------+---------+----------------+---------------+---------------------+--------------------------+----------+------------+----------+
| PartitionId | PartitionName | VisibleVersion | VisibleVersionTime  | VisibleVersionHash | State  | PartitionKey | Range                                                                                                | DistributionKey    | Buckets | ReplicationNum | StorageMedium | CooldownTime        | LastConsistencyCheckTime | DataSize | IsInMemory | RowCount |
+-------------+---------------+----------------+---------------------+--------------------+--------+--------------+------------------------------------------------------------------------------------------------------+--------------------+---------+----------------+---------------+---------------------+--------------------------+----------+------------+----------+
| 17138       | p20230226     | 2              | 2023-07-19 17:53:59 | 0                  | NORMAL | event_day    | [types: [DATETIME]; keys: [2023-02-26 00:00:00]; ..types: [DATETIME]; keys: [2023-02-27 00:00:00]; ) | event_day, site_id | 6       | 3              | HDD           | 9999-12-31 23:59:59 | NULL                     | 0B       | false      | 0        |
| 17113       | p20230227     | 2              | 2023-07-19 17:53:59 | 0                  | NORMAL | event_day    | [types: [DATETIME]; keys: [2023-02-27 00:00:00]; ..types: [DATETIME]; keys: [2023-02-28 00:00:00]; ) | event_day, site_id | 6       | 3              | HDD           | 9999-12-31 23:59:59 | NULL                     | 0B       | false      | 0        |
+-------------+---------------+----------------+---------------------+--------------------+--------+--------------+------------------------------------------------------------------------------------------------------+--------------------+---------+----------------+---------------+---------------------+--------------------------+----------+------------+----------+
2 rows in set (0.00 sec)

Пример 2. Для управления жизненным циклом партиций (сохранять только N последних и удалять устаревшие) используйте свойство partition_live_number.

CREATE TABLE site_access2 (
    event_day DATETIME NOT NULL,
    site_id INT DEFAULT '10',
    city_code VARCHAR(100),
    user_name VARCHAR(32) DEFAULT '',
    pv BIGINT DEFAULT '0'
) 
DUPLICATE KEY(event_day, site_id, city_code, user_name)
PARTITION BY date_trunc('month', event_day)
DISTRIBUTED BY HASH(event_day, site_id)
PROPERTIES(
    "partition_live_number" = "3" -- only retains the most recent three partitions
);

Пример 3. Частые запросы по неделям. Используйте time_slice() со столбцом event_day и интервалом 7 дней. Данные недели — в одной партиции; отсечение партиций ускоряет запросы.

CREATE TABLE site_access(
    event_day DATETIME NOT NULL,
    site_id INT DEFAULT '10',
    city_code VARCHAR(100),
    user_name VARCHAR(32) DEFAULT '',
    pv BIGINT DEFAULT '0'
)
DUPLICATE KEY(event_day, site_id, city_code, user_name)
PARTITION BY time_slice(event_day, INTERVAL 7 day)
DISTRIBUTED BY HASH(event_day, site_id)

Партиционирование на основе column expression (с v3.1)¶

Если вы часто запрашиваете и управляете данными по какому‑то атрибуту, достаточно указать соответствующий столбец как столбец партиционирования — StarRocks автоматически создаст партиции по его значениям.

Однако, если в таблице есть столбец city, и вы часто ищете по странам и городам, используйте list partitioning, чтобы хранить данные по нескольким городам одной страны в одной партиции.

Синтаксис¶

PARTITION BY expression
...

expression::=
    partition_columns 
    
partition_columns::=
    <column>, [ <column> [,...] ]

Параметры¶

partition_columns¶

Обязательный: ДА Описание: Имена столбцов партиционирования. Допустимые значения: строки (кроме BINARY), даты и дата‑время, целые числа, boolean. Допускается NULL. Каждая партиция может содержать только одно значение для каждого столбца партиционирования. Чтобы включить несколько значений одного столбца в одну партицию, используйте List partitioning.

Примечания по использованию¶

• При загрузке StarRocks автоматически создаёт партиции на основе данных; если загрузка завершится неудачно, такие партиции не удаляются автоматически.

• По умолчанию максимум автоматически создаваемых партиций за одну загрузку — 4096, настраивается параметром FE auto_partition_max_creation_number_per_load.

• Правила именования: при нескольких столбцах значения соединяются символом _ в имени партиции: p<value1>_<value2>_.... Например, для столбцов dt и province (оба строковые) и строки с 2022-04-01 и beijing будет создана партиция p20220401_beijing.

Примеры¶

Пример 1. Частые запросы по времени и конкретным городам. При создании таблицы укажите столбцы dt и city в выражении партиционирования — данные одного дня и города будут в одной партиции, что ускоряет запросы.

CREATE TABLE t_recharge_detail1 (
    id bigint,
    user_id bigint,
    recharge_money decimal(32,2), 
    city varchar(20) not null,
    dt varchar(20) not null
)
DUPLICATE KEY(id)
PARTITION BY dt,city
DISTRIBUTED BY HASH(`id`);

Вставьте одну строку:

INSERT INTO t_recharge_detail1 
    VALUES (1, 1, 1, 'Houston', '2022-04-01');

Просмотр партиций. Видно, что по загруженным данным автоматически создана партиция p20220401_Houston. Дальнейшие данные с теми же значениями dt и city будут попадать в неё.

MySQL > SHOW PARTITIONS from t_recharge_detail1\G
*************************** 1. row ***************************
             PartitionId: 16890
           PartitionName: p20220401_Houston
          VisibleVersion: 2
      VisibleVersionTime: 2023-07-19 17:24:53
      VisibleVersionHash: 0
                   State: NORMAL
            PartitionKey: dt, city
                    List: (("2022-04-01", 'Houston'))
         DistributionKey: id
                 Buckets: 6
          ReplicationNum: 3
           StorageMedium: HDD
            CooldownTime: 9999-12-31 23:59:59
LastConsistencyCheckTime: NULL
                DataSize: 2.5KB
              IsInMemory: false
                RowCount: 1
1 row in set (0.00 sec)

Партиционирование на основе сложного time‑выражения (с v3.4)¶

С v3.4.0 expression partitioning поддерживает любые выражения, возвращающие типы DATE или DATETIME, что покрывает ещё более сложные сценарии.

Например, можно определить столбец Unix‑timestamp и использовать функцию from_unixtime() прямо в выражении партиционирования, вместо задания отдельного generated‑столбца DATE/DATETIME.

С v3.4.4 поддерживается отсечение партиций для большинства функций, связанных с DATETIME.

Примеры¶

Пример 1. У каждой строки есть Unix‑timestamp, частые запросы по дням. В выражении используйте столбец timestamp с функцией from_unixtime() и задайте дневную гранулярность.

CREATE TABLE orders (
    ts BIGINT NOT NULL,
    id BIGINT NOT NULL,
    city STRING NOT NULL
)
PARTITION BY from_unixtime(ts,'%Y%m%d');

Пример 2. У каждой строки INT‑timestamp и хранение по месяцам. Используйте cast() и str_to_date() для преобразования в тип DATE и задайте date_trunc('month', ...).

CREATE TABLE orders_new (
    ts INT NOT NULL,
    id BIGINT NOT NULL,
    city STRING NOT NULL
)
PARTITION BY date_trunc('month', str_to_date(CAST(ts as STRING),'%Y%m%d'));

Примечания по использованию¶

Отсечение партиций применимо для следующих случаев сложных выражений:

• Если PARTITION BY from_unixtime(ts), то запросы с фильтром вида ts>1727224687 будут отнесены к нужным партициям.

• Если PARTITION BY str2date(CAST(ts AS string),'%Y%m'), то запросы с предикатом ts = "20240506" будут отсечены.

• Эти случаи также применимы к смешанным выражениям.

Партиционирование на основе смешанного выражения (с v3.4)¶

С v3.4.0 expression partitioning поддерживает несколько столбцов партиционирования, один из которых — time‑функциональное выражение.

Примеры¶

Пример 1. У каждой строки Unix‑timestamp; частые запросы по дням и конкретному городу. Используйте столбец timestamp с from_unixtime() и столбец city как столбцы партиционирования.

CREATE TABLE orders (
    ts BIGINT NOT NULL,
    id BIGINT NOT NULL,
    city STRING NOT NULL
)
PARTITION BY from_unixtime(ts,'%Y%m%d'), city;

Управление партициями¶

Загрузка данных в партиции¶

При загрузке данных StarRocks автоматически создаёт партиции по данным и правилу, заданному выражением.

Обратите внимание: если при создании использовалось expression partitioning и необходимо применить INSERT OVERWRITE для перезаписи данных в конкретной партиции (независимо от того, создана ли она), сейчас нужно явно указать диапазон партиции в PARTITION(). Это отличается от Range и List, где достаточно имени партиции в PARTITION (<partition_name>).

Если использовано time‑выражение и нужно перезаписать данные в конкретной партиции, укажите дату/дата‑время начала этой партиции (с учётом заданной гранулярности). Если партиция отсутствует, она может быть создана автоматически при загрузке.

INSERT OVERWRITE site_access1 PARTITION(event_day='2022-06-08 20:12:04')
    SELECT * FROM site_access2 PARTITION(p20220608);

Если использовано column expression и нужно перезаписать данные в конкретной партиции, укажите значения столбцов партиционирования, содержащиеся в этой партиции. При отсутствии партиции она может быть создана автоматически при загрузке.

INSERT OVERWRITE t_recharge_detail1 PARTITION(dt='2022-04-02',city='texas')
    SELECT * FROM t_recharge_detail2 PARTITION(p20220402_texas);

Просмотр партиций¶

Чтобы просмотреть сведения об автоматически созданных партициях, используйте SHOW PARTITIONS FROM <table_name>. Оператор SHOW CREATE TABLE <table_name> возвращает только синтаксис выражения партиционирования, заданный при создании.

MySQL > SHOW PARTITIONS FROM t_recharge_detail1;
+-------------+-------------------+----------------+---------------------+--------------------+--------+--------------+-----------------------------+-----------------+---------+----------------+---------------+---------------------+--------------------------+----------+------------+----------+
| PartitionId | PartitionName     | VisibleVersion | VisibleVersionTime  | VisibleVersionHash | State  | PartitionKey | List                        | DistributionKey | Buckets | ReplicationNum | StorageMedium | CooldownTime        | LastConsistencyCheckTime | DataSize | IsInMemory | RowCount |
+-------------+-------------------+----------------+---------------------+--------------------+--------+--------------+-----------------------------+-----------------+---------+----------------+---------------+---------------------+--------------------------+----------+------------+----------+
| 16890       | p20220401_Houston | 2              | 2023-07-19 17:24:53 | 0                  | NORMAL | dt, city     | (("2022-04-01", 'Houston')) | id              | 6       | 3              | HDD           | 9999-12-31 23:59:59 | NULL                     | 2.5KB    | false      | 1        |
| 17056       | p20220402_texas   | 2              | 2023-07-19 17:27:42 | 0                  | NORMAL | dt, city     | (("2022-04-02", 'texas'))   | id              | 6       | 3              | HDD           | 9999-12-31 23:59:59 | NULL                     | 2.5KB    | false      | 1        |
+-------------+-------------------+----------------+---------------------+--------------------+--------+--------------+-----------------------------+-----------------+---------+----------------+---------------+---------------------+--------------------------+----------+------------+----------+
2 rows in set (0.00 sec)

Слияние нескольких expression‑партиций¶

В управлении данными частая задача — настроить гранулярность партиций для оптимизации запросов и хранения. Для повышения эффективности StarRocks поддерживает слияние нескольких expression‑партиций более мелкой гранулярности в партиции более крупной гранулярности, например объединение дневных партиций в месячные. Объединяются партиции, попадающие в заданный диапазон времени.

Синтаксис¶

ALTER TABLE [<db_name>.]<table_name>
PARTITION BY <time_expr>
[WHERE <time_range_column>] BETWEEN <start_time> AND <end_time>

Параметры¶

PARTITION BY <time_expr>¶

Обязательный: ДА Описание: Новая временная гранулярность, например PARTITION BY date_trunc('month', dt).

WHERE <time_range_column> BETWEEN <start_time> AND <end_time>¶

Обязательный: ДА Описание: Диапазон времени партиций для слияния. Партиции в этом диапазоне будут объединены по правилу из PARTITION BY.

Пример¶

Объединить партиции таблицы site_access1, изменив гранулярность с «день» на «месяц», для диапазона 2024-01-01 — 2024-03-31:

ALTER TABLE site_access1 PARTITION BY date_trunc('month', event_day)
BETWEEN '2024-01-01' AND '2024-03-31';

После слияния:

• Дневные партиции 2024-01-01..2024-01-31 объединяются в месячную 2024-01.

• Дневные 2024-02-01..2024-02-29 — в 2024-02.

• Дневные 2024-03-01..2024-03-31 — в 2024-03.

Примечания по использованию¶

• Поддерживается только для expression‑партиций на основе time‑функций.

• Слияние партиций с несколькими столбцами партиционирования не поддерживается.

• Нельзя выполнять слияние параллельно со Schema Change/DML‑операциями.

Ограничения¶

• С v3.1.0 режим shared‑data поддерживает time function expression, а с v3.1.1 — column expression.

• Создание таблиц с expression partitioning через CTAS пока не поддерживается.

• Загрузка данных через Spark Load в такие таблицы не поддерживается.

• При удалении партиции, созданной по column expression, оператором ALTER TABLE <table_name> DROP PARTITION <partition_name> данные из неё удаляются без возможности восстановления.

• Начиная с v3.4.0, v3.3.8, v3.2.13 и v3.1.16 поддерживаются backup/restore таблиц с expression partitioning.

Приложение¶

Поддерживаемые time‑функции¶

Expression partitioning поддерживает следующие функции:

Time‑функции:

• timediff

• datediff

• to_days

• years_add/sub

• quarters_add/sub

• months_add/sub

• weeks_add/sub

• date_add/sub

• days_add/sub

• hours_add/sub

• minutes_add/sub

• seconds_add/sub

• milliseconds_add/sub

• date_trunc

• date_format(YmdHiSf/YmdHisf)

• str2date(YmdHiSf/YmdHisf)

• str_to_date(YmdHiSf/YmdHisf)

• to_iso8601

• to_date

• unix_timestamp

• from_unixtime(YmdHiSf/YmdHisf)

• time_slice

Прочие функции:

• add

• subtract

• cast