Implementation:Lance format Lance Java LanceField

Knowledge Sources	Lance
Domains	Java_SDK, Dataset_Management
Last Updated	2026-02-08 19:33 GMT

Overview

Description

The LanceField class represents a field within the Lance schema, extending the standard Arrow Field concept with Lance-specific metadata. Each field carries a unique id, a parentId for hierarchical schema navigation, a logicalType string for Lance-internal type representation, optional DictionaryEncoding, custom metadata, child fields, and unenforced primary key annotations.

The class provides a critical asArrowField() method that converts a LanceField to a standard Arrow Field. This conversion handles special cases for FixedSizeList types where the inner element type must be reconstructed from the logicalType string, including support for lance.bfloat16 extension types. The private arrowTypeFromLogicalType() method maps Lance logical type strings to Arrow types, covering null, boolean, integer (8/16/32/64, signed/unsigned), floating point (half/single/double), string types, binary types, date, time, and duration types.

Usage

LanceField objects are typically obtained from a LanceSchema rather than constructed directly. Use asArrowField() to convert to standard Arrow fields for interoperability with the Arrow ecosystem. The primary key annotations (isUnenforcedPrimaryKey and unenforcedPrimaryKeyPosition) support composite primary key declarations.

Code Reference

Source Location

java/src/main/java/org/lance/schema/LanceField.java

Signature

public class LanceField {
    public int getId();
    public int getParentId();
    public String getName();
    public boolean isNullable();
    public String getLogicalType();
    public ArrowType getType();
    public Optional<DictionaryEncoding> getDictionaryEncoding();
    public Map<String, String> getMetadata();
    public List<LanceField> getChildren();
    public boolean isUnenforcedPrimaryKey();
    public OptionalInt getUnenforcedPrimaryKeyPosition();
    public Field asArrowField();
}

Import

import org.lance.schema.LanceField;

I/O Contract

Field Properties

Property	Type	Description
id	int	Unique field identifier within the schema
parentId	int	Parent field ID for nested schemas (0 for top-level fields)
name	String	Field name
nullable	boolean	Whether the field allows null values
logicalType	String	Lance-internal logical type string (e.g., "float", "fixed_size_list:float:128")
type	ArrowType	The Arrow data type
dictionaryEncoding	DictionaryEncoding	Optional dictionary encoding
metadata	Map<String, String>	Custom field-level metadata
children	List<LanceField>	Child fields for nested types
isUnenforcedPrimaryKey	boolean	Whether this field is part of an unenforced primary key
unenforcedPrimaryKeyPosition	int	1-based position in a composite primary key (0 means use schema field ID ordering)

Supported Logical Type Mappings

Logical Type	Arrow Type
null	ArrowType.Null
bool	ArrowType.Bool
int8, uint8, int16, ..., uint64	ArrowType.Int (various widths/signedness)
halffloat, float, double	ArrowType.FloatingPoint
string, large_string	ArrowType.Utf8, ArrowType.LargeUtf8
binary, large_binary, blob, json	ArrowType.Binary, ArrowType.LargeBinary
date32:day, date64:ms	ArrowType.Date
time32:s, time32:ms, time64:us, time64:ns	ArrowType.Time
duration:s, duration:ms, duration:us, duration:ns	ArrowType.Duration
lance.bfloat16	ArrowType.FixedSizeBinary(2) with extension metadata

Usage Examples

// Obtain fields from a LanceSchema
LanceSchema schema = dataset.lanceSchema();
List<LanceField> fields = schema.fields();

for (LanceField field : fields) {
    // Access Lance-specific metadata
    int fieldId = field.getId();
    String logicalType = field.getLogicalType();
    boolean isPrimaryKey = field.isUnenforcedPrimaryKey();

    // Convert to standard Arrow Field for interop
    Field arrowField = field.asArrowField();
}

Related Pages

• Lance_format_Lance_Java_LanceSchema -- Schema containing a list of LanceField objects
• Lance_format_Lance_Java_ColumnAlteration -- Alters column properties (rename, nullable, cast)
• Lance_format_Lance_Java_JsonFields -- Utility for creating JSON-typed Arrow fields