Manage table partitions

Introduction

This page covers the Gravitino API for partitions. For what a partition is, the partition types, and which catalogs support managing them, see Partitions.

Partition management works on Hive and Doris catalogs. Iceberg, MySQL, and PostgreSQL catalogs manage partitions themselves and do not expose them here.

Partition operations

Add

The partition type must match the table's partitioning strategy. The three shapes are below.

Identity

Identity partition

{
  "type": "identity",
  "name": "dt=2026-08-02/country=us",
  "fieldNames": [["dt"], ["country"]],
  "values": [
    {"type": "literal", "dataType": "date", "value": "2026-08-02"},
    {"type": "literal", "dataType": "string", "value": "us"}
  ]
}

values must be in the same order as fieldNames. On a Hive table the partition name is ignored, since Hive derives it from the field names and values.

Range

Range partition

{
  "type": "range",
  "name": "p20260802",
  "upper": {"type": "literal", "dataType": "date", "value": "2026-08-02"},
  "lower": {"type": "literal", "dataType": "date", "value": "2026-08-01"}
}

List

List partition

{
  "type": "list",
  "name": "p_north_america",
  "lists": [
    [{"type": "literal", "dataType": "string", "value": "us"}],
    [{"type": "literal", "dataType": "string", "value": "ca"}]
  ]
}

REST

Add an identity partition

curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{
  "partitions": [
    {
      "type": "identity",
      "name": "dt=2026-08-02/country=us",
      "fieldNames": [["dt"], ["country"]],
      "values": [
        {"type": "literal", "dataType": "date", "value": "2026-08-02"},
        {"type": "literal", "dataType": "string", "value": "us"}
      ]
    }
  ]
}' http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/public/tables/orders/partitions

Java

Add an identity partition

Table orders = catalog.asTableCatalog().loadTable(
    NameIdentifier.of("public", "orders"));

Partition partition = Partitions.identity(
    new String[][] {{"dt"}, {"country"}},
    new Literal[] {
        Literals.dateLiteral(LocalDate.of(2026, 8, 2)),
        Literals.stringLiteral("us")
    });

orders.supportPartitions().addPartition(partition);

Get

REST

Get a partition

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  "http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/public/tables/orders/partitions/dt=2026-08-02%2Fcountry=us"

Java

Get a partition

Partition partition = orders.supportPartitions().getPartition(
    "dt=2026-08-02/country=us");

List

Listing returns names, or full partition objects when details=true is set.

REST

List partitions

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/public/tables/orders/partitions

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  "http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/public/tables/orders/partitions?details=true"

Java

List partitions

String[] names = orders.supportPartitions().listPartitionNames();
Partition[] partitions = orders.supportPartitions().listPartitions();

Drop

REST

Drop or purge a partition

curl -X DELETE -H "Accept: application/vnd.gravitino.v1+json" \
  "http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/public/tables/orders/partitions/dt=2026-08-02%2Fcountry=us"

curl -X DELETE -H "Accept: application/vnd.gravitino.v1+json" \
  "http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/public/tables/orders/partitions/dt=2026-08-02%2Fcountry=us?purge=true"

Java

Drop or purge a partition

boolean dropped = orders.supportPartitions().dropPartition(
    "dt=2026-08-02/country=us");

boolean purged = orders.supportPartitions().purgePartition(
    "dt=2026-08-02/country=us");

Dropping removes the partition metadata. Purging removes its data as well, and is not supported by every catalog.