Implementation:Lance format Lance JNI Schema

Knowledge Sources	Lance
Domains	Java_Bindings, JNI
Last Updated	2026-02-08 19:33 GMT

Overview

JNI Schema is the Rust-side JNI binding that converts Lance schemas and Arrow data types into their Java Apache Arrow equivalents, enabling Java applications to inspect dataset schemas with full type fidelity.

Description

This module implements the IntoJava trait for lance_core::datatypes::Schema and provides helper functions for converting the complete Lance type system to Java Arrow types. The conversion is recursive and handles:

Schema conversion:

• Schema::into_java - Converts a Lance schema into a Java LanceSchema object, iterating over fields and converting each to a Java LanceField with its ID, parent ID, name, nullability, logical type, Arrow type, metadata, children, and primary key information.

Field conversion:

• convert_to_java_field - Converts a single Lance Field to a Java LanceField object, including all field properties.
• convert_children_fields - Recursively converts nested child fields (for struct, list, and map types).

Arrow type conversion: convert_arrow_type maps the full Arrow DataType enum to Java Arrow type objects:

• Primitive types: Null, Boolean, Int8/16/32/64, UInt8/16/32/64, Float16/32/64
• String types: Utf8, LargeUtf8
• Binary types: Binary, LargeBinary, FixedSizeBinary
• Temporal types: Date32, Date64, Time32, Time64, Timestamp (with timezone), Duration
• Decimal types: Decimal128, Decimal256
• Nested types: List, LargeList, FixedSizeList, Struct, Union, Map

Each type conversion creates the corresponding Java ArrowType subclass (e.g., ArrowType$Int, ArrowType$FloatingPoint, ArrowType$Timestamp) using JNI constructor calls or static field access.

Usage

Use this module when implementing or extending schema inspection in the Java SDK. It is called whenever Java code reads a dataset schema or needs to understand the types of columns in a Lance dataset.

Code Reference

Source Location

java/lance-jni/src/schema.rs

Signature

impl IntoJava for Schema {
    fn into_java<'local>(self, env: &mut JNIEnv<'local>) -> Result<JObject<'local>>;
}

pub fn convert_to_java_field<'local>(
    env: &mut JNIEnv<'local>,
    lance_field: &Field,
) -> Result<JObject<'local>>;

pub fn convert_arrow_type<'local>(
    env: &mut JNIEnv<'local>,
    arrow_type: &DataType,
) -> Result<JObject<'local>>;

Import

use crate::schema::{convert_to_java_field, convert_arrow_type};

I/O Contract

Direction	Type	Description
Input	Schema (Lance schema)	Lance schema with fields, metadata, and type information
Input	&Field (Lance field)	Individual field with name, type, children, and metadata
Input	&DataType (Arrow DataType)	Arrow data type enum to convert
Output	JObject (Java LanceSchema)	Java org.lance.schema.LanceSchema with field list and metadata map
Output	JObject (Java LanceField)	Java org.lance.schema.LanceField with full type information
Output	JObject (Java ArrowType)	Java org.apache.arrow.vector.types.pojo.ArrowType subclass

Usage Examples

// Java side: reading dataset schema
import org.lance.Dataset;
import org.lance.schema.LanceSchema;

Dataset dataset = Dataset.open("/path/to/dataset");
LanceSchema schema = dataset.getSchema();

for (LanceField field : schema.getFields()) {
    System.out.println(field.getName() + ": " + field.getArrowType());
}

// Rust JNI side: type conversion for a Float32 column
fn convert_floating_point_type<'local>(
    env: &mut JNIEnv<'local>,
    precision: &str,  // "HALF", "SINGLE", or "DOUBLE"
) -> Result<JObject<'local>> {
    // Creates org.apache.arrow.vector.types.pojo.ArrowType$FloatingPoint
    // with the specified precision enum value
}

Related Pages

• Lance_format_Lance_JNI_BlockingDataset - Dataset schema retrieval calls into this module
• Lance_format_Lance_JNI_Traits - IntoJava trait implemented here for Schema
• Lance_format_Lance_JNI_Utils - to_java_map used for schema metadata conversion
• Lance_format_Lance_JNI_Transaction - Transaction operations reference schema information