PolarDB:CREATE TABLE (modo AUTO)

Exemplo: Particionamento KEY (recomendado para a maioria dos casos)

Crie uma tabela particionada por name e id. Por padrão, o roteamento usa apenas a coluna name, deixando id disponível para futura divisão de partição quente:

CREATE TABLE key_tbl(
  id       bigint not null auto_increment,
  bid      int,
  name     varchar(30),
  birthday datetime not null,
  primary key(id)
)
PARTITION BY KEY(name, id)
PARTITIONS 8;

Para acionar o pruning de partição, inclua a primeira coluna de roteamento na cláusula WHERE:

-- Scans only one partition
SELECT id FROM key_tbl WHERE name = 'Jack';

Se a coluna name apresentar um ponto de congestionamento (hot spot), use ALTER TABLEGROUP para dividir com base na coluna id. Para detalhes, consulte ALTER TABLEGROUP.

Exemplo: Particionamento HASH (coluna única)

CREATE TABLE hash_tbl(
  id       bigint not null auto_increment,
  bid      int,
  name     varchar(30),
  birthday datetime not null,
  primary key(id)
)
PARTITION BY HASH(id)
PARTITIONS 8;

Para particionar por uma coluna datetime, use uma função de partição para convertê-la em inteiro:

CREATE TABLE hash_tbl_days(
  id       bigint not null auto_increment,
  bid      int,
  name     varchar(30),
  birthday datetime not null,
  primary key(id)
)
PARTITION BY HASH(TO_DAYS(birthday))
PARTITIONS 8;

Exemplo: Particionamento HASH (chave vetorial)

O PolarDB-X estende o particionamento HASH para suportar chaves de partição vetoriais (recurso indisponível no MySQL). Diferentemente do particionamento KEY, o roteamento usa todas as colunas da chave simultaneamente. Portanto, o pruning de partição exige condições em todas elas:

CREATE TABLE hash_tbl2(
  id       bigint not null auto_increment,
  bid      int,
  name     varchar(30),
  birthday datetime not null,
  primary key(id)
)
PARTITION BY HASH(name, birthday)
PARTITIONS 8;

-- Partition pruning: scans one partition (all key columns specified)
SELECT id FROM hash_tbl2 WHERE name = 'Jack' AND birthday = '1990-11-11';

-- No pruning: scans all partitions (incomplete key)
SELECT id FROM hash_tbl2 WHERE name = 'Jack';

Quando usar

• KEY partitioning — escolha padrão para distribuição uniforme de dados, com opção de dividir partições quentes posteriormente.

• HASH com função de partição — ideal para distribuir linhas por componente de tempo (ex.: ano, mês) em vez do timestamp bruto.

• HASH com chave vetorial — indicado quando as linhas devem ser roteadas pelo valor combinado de múltiplas colunas e não há necessidade de dividir partições quentes.

Limitações

Tipos de dados

Inteiro: BIGINT, BIGINT UNSIGNED, INT, INT UNSIGNED, MEDIUMINT, MEDIUMINT UNSIGNED, SMALLINT, SMALLINT UNSIGNED, TINYINT, TINYINT UNSIGNED

Data/hora: DATE, DATETIME, TIMESTAMP

String: CHAR, VARCHAR

Restrições de sintaxe

• Chaves de coluna única com coluna DATE, DATETIME ou TIMESTAMP podem usar funções de partição.

• Chaves de partição vetoriais não suportam funções de partição nem divisão de partição quente.

• Por padrão, uma tabela pode ter no máximo 8.192 partições.

• Uma chave de partição pode ter no máximo 5 colunas.

Exemplo: Particionamento RANGE COLUMNS

Particione uma tabela de pedidos por intervalos de order_id e order_time:

CREATE TABLE orders(
  order_id   int,
  order_time datetime not null
)
PARTITION BY RANGE COLUMNS(order_id, order_time)
(
  PARTITION p1 VALUES LESS THAN (10000, '2021-01-01'),
  PARTITION p2 VALUES LESS THAN (20000, '2021-01-01'),
  PARTITION p3 VALUES LESS THAN (30000, '2021-01-01'),
  PARTITION p4 VALUES LESS THAN (40000, '2021-01-01'),
  PARTITION p5 VALUES LESS THAN (50000, '2021-01-01'),
  PARTITION p6 VALUES LESS THAN (MAXVALUE, MAXVALUE)
);

Exemplo: Particionamento RANGE

Particione por trimestre usando TO_DAYS() para converter order_time em inteiro:

CREATE TABLE orders_quarterly(
  id         int,
  order_time datetime not null
)
PARTITION BY RANGE(TO_DAYS(order_time))
(
  PARTITION p1 VALUES LESS THAN (TO_DAYS('2021-01-01')),
  PARTITION p2 VALUES LESS THAN (TO_DAYS('2021-04-01')),
  PARTITION p3 VALUES LESS THAN (TO_DAYS('2021-07-01')),
  PARTITION p4 VALUES LESS THAN (TO_DAYS('2021-10-01')),
  PARTITION p5 VALUES LESS THAN (TO_DAYS('2022-01-01')),
  PARTITION p6 VALUES LESS THAN (MAXVALUE)
);

Quando usar

• RANGE COLUMNS — ideal para particionamento por intervalo de datas ou IDs com chaves multicolumnares ou requisitos de divisão de partição quente.

• RANGE — adequado para particionamento baseado em data de coluna única com uso de função de extração de tempo.

Limitações

Tipos de dados

Inteiro: BIGINT, BIGINT UNSIGNED, INT, INT UNSIGNED, MEDIUMINT, MEDIUMINT UNSIGNED, SMALLINT, SMALLINT UNSIGNED, TINYINT, TINYINT UNSIGNED

Data/hora: DATE, DATETIME (TIMESTAMP não suportado em RANGE COLUMNS; use UNIX_TIMESTAMP() em RANGE)

String: CHAR, VARCHAR (apenas RANGE COLUMNS; não suportado em RANGE)

Restrições de sintaxe

• Não use NULL como limite de intervalo.

• Se uma consulta especificar NULL para chave de partição RANGE, o PolarDB-X tratará o NULL como valor mínimo durante o roteamento.

• Por padrão, uma tabela pode ter no máximo 8.192 partições.

• Uma chave de partição pode ter no máximo 5 colunas.

Exemplo: Particionamento LIST COLUMNS

Particione uma tabela regional de pedidos por país e cidade:

CREATE TABLE orders_region(
  id         int,
  country    varchar(64),
  city       varchar(64),
  order_time datetime not null
)
PARTITION BY LIST COLUMNS(country, city)
(
  PARTITION p1 VALUES IN (('China', 'Hangzhou'), ('China', 'Beijing')),
  PARTITION p2 VALUES IN (('United States', 'New York'), ('United States', 'Chicago')),
  PARTITION p3 VALUES IN (('Russia', 'Moscow'))
);

Exemplo: Particionamento LIST

Particione por ano usando YEAR() para extrair um inteiro de order_time:

CREATE TABLE orders_by_year(
  id         int,
  country    varchar(64),
  city       varchar(64),
  order_time datetime not null
)
PARTITION BY LIST(YEAR(order_time))
(
  PARTITION p1 VALUES IN (1990,1991,1992,1993,1994,1995,1996,1997,1998,1999),
  PARTITION p2 VALUES IN (2000,2001,2002,2003,2004,2005,2006,2007,2008,2009),
  PARTITION p3 VALUES IN (2010,2011,2012,2013,2014,2015,2016,2017,2018,2019)
);

Exemplo: Partição DEFAULT (LIST COLUMNS)

Adicione uma partição DEFAULT para capturar linhas sem correspondência em outras partições. Apenas uma partição DEFAULT é permitida, e ela deve ser definida por último:

CREATE TABLE orders_region_default(
  id         int,
  country    varchar(64),
  city       varchar(64),
  order_time datetime not null
)
PARTITION BY LIST COLUMNS(country, city)
(
  PARTITION p1 VALUES IN (('China', 'Hangzhou'), ('China', 'Beijing')),
  PARTITION p2 VALUES IN (('United States', 'New York'), ('United States', 'Chicago')),
  PARTITION p3 VALUES IN (('Russia', 'Moscow')),
  PARTITION pd VALUES IN (DEFAULT)
);

Exemplo: Partição DEFAULT (LIST)

O particionamento LIST também suporta partição DEFAULT para rotear valores inteiros sem correspondência:

CREATE TABLE orders_by_year_default(
  id         int,
  country    varchar(64),
  city       varchar(64),
  order_time datetime not null
)
PARTITION BY LIST(YEAR(order_time))
(
  PARTITION p1 VALUES IN (1990,1991,1992,1993,1994,1995,1996,1997,1998,1999),
  PARTITION p2 VALUES IN (2000,2001,2002,2003,2004,2005,2006,2007,2008,2009),
  PARTITION p3 VALUES IN (2010,2011,2012,2013,2014,2015,2016,2017,2018,2019),
  PARTITION pd VALUES IN (DEFAULT)
);

Quando usar

• LIST COLUMNS — projetado para particionamento categórico em colunas string (ex.: país, região) ou múltiplas colunas.

• LIST — indicado para particionamento categórico em coluna inteira única ou derivada de tempo.

• Adicione uma DEFAULT partition caso novos valores de categoria possam surgir após a criação da tabela.

Limitações

Tipos de dados

Inteiro: BIGINT, BIGINT UNSIGNED, INT, INT UNSIGNED, MEDIUMINT, MEDIUMINT UNSIGNED, SMALLINT, SMALLINT UNSIGNED, TINYINT, TINYINT UNSIGNED

Data/hora: DATE, DATETIME

String: CHAR, VARCHAR (apenas LIST COLUMNS)

Restrições de sintaxe

• LIST COLUMNS não suporta colunas TIMESTAMP.

• O particionamento LIST exige colunas de chave de partição inteiras.

• Nenhum dos tipos suporta divisão de partição quente.

• Por padrão, uma tabela pode ter no máximo 8.192 partições.

• Uma chave de partição pode ter no máximo 5 colunas.

Como funciona

O COHASH aplica uma função de partição (como RIGHT, LEFT ou SUBSTR) a cada coluna de chave de partição para extrair a parte compartilhada e, em seguida, usa hash consistente no resultado. Como a parte compartilhada é idêntica entre as colunas, as linhas caem na mesma partição independentemente da coluna consultada.

Exemplo: Particionamento COHASH

Particione uma tabela de pedidos pelos últimos seis caracteres de order_id e buyer_id:

CREATE TABLE t_orders(
  id         bigint not null auto_increment,
  order_id   bigint,
  buyer_id   bigint,
  order_time datetime not null,
  primary key(id)
)
PARTITION BY CO_HASH(
  RIGHT(order_id, 6),  -- last six characters of order_id
  RIGHT(buyer_id, 6)   -- last six characters of buyer_id
)
PARTITIONS 8;

Quando order_id e buyer_id compartilham os mesmos seis últimos caracteres, ambas as consultas a seguir são roteadas para a mesma partição:

SELECT * FROM t_orders WHERE order_id = 100234;
SELECT * FROM t_orders WHERE buyer_id = 100234;

Migração do RANGE_HASH do PolarDB-X 1.0

Se a instância de origem usar RANGE_HASH(order_id, buyer_id, 6), utilize a mesma sintaxe no banco de dados de destino. O PolarDB-X converte automaticamente para a definição equivalente CO_HASH:

CREATE TABLE orders(
  id       bigint not null auto_increment,
  buyer_id bigint,
  order_id bigint,
  primary key(id)
)
PARTITION BY RANGE_HASH(order_id, buyer_Id, 6)
PARTITIONS 8;

COHASH vs KEY vs HASH

Notas de uso

• Você é responsável por manter a similaridade das colunas. O PolarDB-X verifica os resultados de roteamento, mas não impõe que a parte similar designada seja idêntica entre as colunas. Se uma linha inserida tiver valores diferentes na parte similar, ela poderá ser roteada silenciosamente para uma partição inesperada.

• Restrições de DML. Para evitar roteamento inconsistente:

  • Um INSERT ou REPLACE em que as colunas de chave de partição de uma linha roteiam para partições diferentes é rejeitado.

  • Um UPDATE ou UPSERT que modifica colunas de chave de partição deve atualizar todas elas. Se os novos valores rotearem para partições diferentes, a instrução será rejeitada.

  • As mesmas restrições aplicam-se a DML na tabela primária quando a tabela possui índice secundário global (GSI) COHASH.

• Zeros à esquerda em colunas inteiras. Ao aplicar função de partição como RIGHT(c1, 4) a coluna inteira, o resultado é automaticamente convertido para valor numérico (ex.: '0034' torna-se 34). Isso garante que c1 = 1000034 e c2 = 34 sejam roteados para a mesma partição conforme esperado.

Quando usar

Use COHASH quando uma tabela tiver duas ou mais colunas cujos valores estejam sempre correlacionados por sufixo ou prefixo compartilhado, e você precise que consultas pontuais equivalentes em qualquer dessas colunas atinjam uma única partição.

Limitações

Funções de partição: apenas RIGHT, LEFT, SUBSTR. Não há suporte a funções aninhadas.

Tipos de dados: BIGINT, INT, MEDIUMINT, SMALLINT, TINYINT (e variantes UNSIGNED); DECIMAL (parte decimal deve ser zero); CHAR, VARCHAR. Tipos de data/hora não são suportados.

Restrições de sintaxe

• Todas as colunas de chave de partição devem compartilhar o mesmo conjunto de caracteres, collation e definição de comprimento/precisão.

• Ao usar a sintaxe RANGE_HASH, o valor de comprimento deve ser positivo.

• Por padrão, uma tabela pode ter no máximo 8.192 partições.

• Uma chave de partição pode ter no máximo 5 colunas.

Exemplo: Subpartições com modelo

Três partições de nível 1 LIST COLUMNS, cada uma com quatro subpartições KEY — 12 partições físicas no total:

CREATE TABLE sp_tbl_list_key_tp(
  id         int,
  country    varchar(64),
  city       varchar(64),
  order_time datetime not null,
  PRIMARY KEY(id)
)
PARTITION BY LIST COLUMNS(country, city)
SUBPARTITION BY KEY(id) SUBPARTITIONS 4
(
  PARTITION p1 VALUES IN (('China', 'Hangzhou')),
  PARTITION p2 VALUES IN (('Russia', 'Moscow')),
  PARTITION pd VALUES IN (DEFAULT)
);

Exemplo: Subpartições sem modelo

Três partições de nível 1 LIST COLUMNS com 2, 3 e 4 subpartições respectivamente — 9 partições físicas no total:

CREATE TABLE sp_tbl_list_key_ntp(
  id         int,
  country    varchar(64),
  city       varchar(64),
  order_time datetime not null,
  PRIMARY KEY(id)
)
PARTITION BY LIST COLUMNS(country, city)
SUBPARTITION BY KEY(id)
(
  PARTITION p1 VALUES IN (('China', 'Hangzhou')) SUBPARTITIONS 2,
  PARTITION p2 VALUES IN (('Russia', 'Moscow'))  SUBPARTITIONS 3,
  PARTITION pd VALUES IN (DEFAULT)               SUBPARTITIONS 4
);

Quando usar

Use partições de nível 2 quando estratégia unidimensional levar a distorção de dados ou granularidade insuficiente. Por exemplo, particione pedidos por região (LIST) e depois por ID dentro de cada região (KEY).

Limitações

• O total de partições físicas (soma de todas as partições de nível 2 em todas as de nível 1) não pode exceder 8.192 por padrão.

• Nomes de subpartições devem ser únicos e não podem duplicar nomes de partição de nível 1.

• Mantenha baixo o produto das contagens de nível 1 e nível 2 para evitar sobrecarga excessiva de partições.

CREATE TABLE auto_part_tbl(
  id   bigint not null auto_increment,
  bid  int,
  name varchar(30),
  primary key(id),
  index idx_name (name)
);

SHOW CREATE TABLE auto_part_tbl;

| auto_part_tbl | CREATE TABLE `auto_part_tbl` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `bid` int(11) DEFAULT NULL,
    `name` varchar(30) DEFAULT NULL,
    PRIMARY KEY (`id`),
    INDEX `idx_name` (`name`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8 |

SHOW FULL CREATE TABLE auto_part_tbl;

| auto_part_tbl | CREATE PARTITION TABLE `auto_part_tbl` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `bid` int(11) DEFAULT NULL,
    `name` varchar(30) DEFAULT NULL,
    PRIMARY KEY (`id`),
    GLOBAL INDEX /* idx_name_$a870 */ `idx_name` (`name`)
        PARTITION BY KEY (`name`, `id`) PARTITIONS 16,
    LOCAL KEY `_local_idx_name` (`name`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8
PARTITION BY KEY(`id`)
PARTITIONS 16
/* tablegroup = `tg108` */ |

EXPLAIN SELECT * FROM tbl_int    WHERE a = 12345678;
-- LogicalView(tables="tbl_int[p260]", ...)

EXPLAIN SELECT * FROM tbl_bigint WHERE a = 12345678;
-- LogicalView(tables="tbl_bigint[p477]", ...)

-- tbl_varchar_cs uses utf8_bin
EXPLAIN SELECT a FROM tbl_varchar_cs WHERE a IN ('AbcD');
-- LogicalView(tables="tbl_varchar_cs[p29]", ...)

EXPLAIN SELECT a FROM tbl_varchar_cs WHERE a IN ('abcd');
-- LogicalView(tables="tbl_varchar_cs[p11]", ...)  -- different partition

-- tbl_varchar_ci uses utf8_general_ci
EXPLAIN SELECT a FROM tbl_varchar_ci WHERE a IN ('AbcD');
-- LogicalView(tables="tbl_varchar_ci[p4]", ...)

EXPLAIN SELECT a FROM tbl_varchar_ci WHERE a IN ('abcd');
-- LogicalView(tables="tbl_varchar_ci[p4]", ...)   -- same partition

INSERT INTO tbl_smallint VALUES (12345678), (-12345678);
-- Stored as 32767 and -32768

SELECT * FROM tbl_smallint WHERE a = 12345678;
-- Routes to the same partition as WHERE a = 32767