Skip to main content
The Types class provides the type system for Apache Iceberg, defining primitive and complex data types supported in Iceberg schemas.

​
Overview

Iceberg’s type system includes:
  • Primitive types (boolean, int, long, float, double, date, time, timestamp, string, uuid, fixed, binary, decimal)
  • Complex types (struct, list, map)
  • Special types (variant, geometry, geography)

​
Primitive Types

​
Boolean

Types.BooleanType.get()
Example: 
import org.apache.iceberg.types.Types;

Type boolType = Types.BooleanType.get();

​
Integer (32-bit)

Types.IntegerType.get()

​
Long (64-bit)

Types.LongType.get()

​
Float (32-bit)

Types.FloatType.get()

​
Double (64-bit)

Types.DoubleType.get()

​
Date

Date without time, stored as days from 1970-01-01. 
Types.DateType.get()

​
Time

Time of day without date, stored as microseconds from midnight. 
Types.TimeType.get()

​
Timestamp

Timestamp with microsecond precision. 
// With timezone (stored as UTC)
Types.TimestampType.withZone()

// Without timezone (local time)
Types.TimestampType.withoutZone()
Example: 
Type timestamptz = Types.TimestampType.withZone();
Type timestamp = Types.TimestampType.withoutZone();

// Check if timezone aware
TimestampType ts = (TimestampType) timestamptz;
boolean adjusts = ts.shouldAdjustToUTC(); // true

​
Timestamp Nano

Timestamp with nanosecond precision. 
Types.TimestampNanoType.withZone()
Types.TimestampNanoType.withoutZone()

​
String

Variable-length UTF-8 string. 
Types.StringType.get()

​
UUID

Universally unique identifier (128-bit). 
Types.UUIDType.get()

​
Fixed

Fixed-length byte array. 
Types.FixedType.ofLength(int length)
Example: 
Type fixed16 = Types.FixedType.ofLength(16);
Types.FixedType fixedType = (Types.FixedType) fixed16;
int len = fixedType.length(); // 16

​
Binary

Variable-length byte array. 
Types.BinaryType.get()

​
Decimal

Fixed-point decimal with precision and scale. 
Types.DecimalType.of(int precision, int scale)
Parameters:
  • precision - Total number of digits (max 38)
  • scale - Number of digits after decimal point
Example: 
Type decimal = Types.DecimalType.of(10, 2); // 10 digits, 2 after decimal
Types.DecimalType decType = (Types.DecimalType) decimal;
int prec = decType.precision(); // 10
int scale = decType.scale();     // 2

​
Spatial Types

​
Geometry

Geometry type with optional coordinate reference system. 
// Default CRS (OGC:CRS84)
Types.GeometryType.crs84()

// Custom CRS
Types.GeometryType.of(String crs)
Example: 
Type geom1 = Types.GeometryType.crs84();
Type geom2 = Types.GeometryType.of("EPSG:4326");

Types.GeometryType geomType = (Types.GeometryType) geom2;
String crs = geomType.crs(); // "EPSG:4326"

​
Geography

Geography type with CRS and edge algorithm. 
// Default (OGC:CRS84, spherical)
Types.GeographyType.crs84()

// Custom CRS
Types.GeographyType.of(String crs)

// Custom CRS and algorithm
Types.GeographyType.of(String crs, EdgeAlgorithm algorithm)
Example: 
Type geog = Types.GeographyType.of(
    "EPSG:4326",
    EdgeAlgorithm.SPHERICAL
);

​
Complex Types

​
Struct

Structured type with named fields. 
Types.StructType.of(NestedField... fields)
Types.StructType.of(List<NestedField> fields)
Example: 
import org.apache.iceberg.types.Types.NestedField;

Type structType = Types.StructType.of(
    NestedField.required(1, "id", Types.LongType.get()),
    NestedField.optional(2, "name", Types.StringType.get()),
    NestedField.required(3, "age", Types.IntegerType.get())
);

// Access fields
Types.StructType struct = (Types.StructType) structType;
NestedField field = struct.field("name");
Type fieldType = struct.fieldType("name"); // StringType

​
List

Ordered collection of elements. 
// Optional elements
Types.ListType.ofOptional(int elementId, Type elementType)

// Required elements
Types.ListType.ofRequired(int elementId, Type elementType)
Example: 
Type listType = Types.ListType.ofOptional(
    1,
    Types.StringType.get()
);

Types.ListType list = (Types.ListType) listType;
Type elemType = list.elementType(); // StringType
boolean optional = list.isElementOptional(); // true
int elemId = list.elementId(); // 1

​
Map

Key-value pairs. 
// Optional values
Types.MapType.ofOptional(
    int keyId,
    int valueId,
    Type keyType,
    Type valueType
)

// Required values
Types.MapType.ofRequired(
    int keyId,
    int valueId,
    Type keyType,
    Type valueType
)
Example: 
Type mapType = Types.MapType.ofOptional(
    1, 2,
    Types.StringType.get(),
    Types.IntegerType.get()
);

Types.MapType map = (Types.MapType) mapType;
Type keyType = map.keyType();    // StringType
Type valueType = map.valueType(); // IntegerType
boolean valueOpt = map.isValueOptional(); // true

​
Nested Fields

Fields in struct types.

​
Creating Fields

// Optional field
NestedField.optional(int id, String name, Type type)
NestedField.optional(int id, String name, Type type, String doc)

// Required field
NestedField.required(int id, String name, Type type)
NestedField.required(int id, String name, Type type, String doc)
Example: 
NestedField field1 = NestedField.required(
    1,
    "id",
    Types.LongType.get(),
    "Unique identifier"
);

NestedField field2 = NestedField.optional(
    2,
    "email",
    Types.StringType.get()
);

​
Field Builder

NestedField field = NestedField.builder()
    .withId(1)
    .withName("user_id")
    .ofType(Types.LongType.get())
    .asRequired()
    .withDoc("User identifier")
    .build();

​
Field Properties

int id = field.fieldId();
String name = field.name();
Type type = field.type();
String doc = field.doc();
boolean optional = field.isOptional();
boolean required = field.isRequired();

​
Type Utilities

​
Parsing Type Strings

Types.fromTypeName(String typeString)
Types.fromPrimitiveString(String typeString)
Example: 
Type intType = Types.fromTypeName("int");
Type decType = Types.fromTypeName("decimal(10,2)");
Type fixedType = Types.fromTypeName("fixed[16]");

​
Type Checking

boolean isPrimitive = type.isPrimitiveType();
boolean isNested = type.isNestedType();
boolean isStruct = type.isStructType();
boolean isList = type.isListType();
boolean isMap = type.isMapType();

​
Type Conversion

PrimitiveType primType = type.asPrimitiveType();
StructType structType = type.asStructType();
ListType listType = type.asListType();
MapType mapType = type.asMapType();

​
Examples

​
Creating a Schema with Types

import org.apache.iceberg.Schema;
import org.apache.iceberg.types.Types;
import static org.apache.iceberg.types.Types.NestedField.*;

Schema schema = new Schema(
    required(1, "id", Types.LongType.get()),
    optional(2, "data", Types.StringType.get()),
    required(3, "timestamp", Types.TimestampType.withZone()),
    optional(4, "amount", Types.DecimalType.of(10, 2)),
    required(5, "active", Types.BooleanType.get())
);

​
Nested Struct Type

Type addressType = Types.StructType.of(
    required(1, "street", Types.StringType.get()),
    required(2, "city", Types.StringType.get()),
    optional(3, "zip", Types.StringType.get())
);

Schema schema = new Schema(
    required(1, "user_id", Types.LongType.get()),
    optional(2, "name", Types.StringType.get()),
    optional(3, "address", addressType)
);

​
Complex Nested Types

// List of structs
Type itemType = Types.StructType.of(
    required(1, "product_id", Types.LongType.get()),
    required(2, "quantity", Types.IntegerType.get()),
    optional(3, "price", Types.DecimalType.of(10, 2))
);

Type itemsListType = Types.ListType.ofOptional(1, itemType);

// Map of string to list
Type tagsType = Types.MapType.ofOptional(
    1, 2,
    Types.StringType.get(),
    Types.ListType.ofOptional(3, Types.StringType.get())
);

Schema orderSchema = new Schema(
    required(1, "order_id", Types.LongType.get()),
    optional(2, "items", itemsListType),
    optional(3, "tags", tagsType)
);

​
Working with Field Defaults

import org.apache.iceberg.expressions.Literal;
import org.apache.iceberg.expressions.Expressions;

NestedField field = NestedField.builder()
    .withId(1)
    .withName("status")
    .ofType(Types.StringType.get())
    .asOptional()
    .withInitialDefault(Expressions.lit("pending"))
    .withWriteDefault(Expressions.lit("active"))
    .build();

Object initialDefault = field.initialDefault(); // "pending"
Object writeDefault = field.writeDefault();     // "active"

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us