Implementation:Lance format Lance JNI Utils

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

Overview

JNI Utils provides shared utility functions for the JNI binding layer, including parameter extraction for write operations, compaction options building, vector search query parsing, index parameter construction, and Java object creation helpers.

Description

This module contains the reusable utility functions consumed across all JNI entry points:

Storage and write parameter extraction:

• extract_storage_options - Converts a Java Map<String, String> to a Rust HashMap for storage configuration.
• extract_write_params - Builds a Lance WriteParams struct from Java Optional parameters including max rows per file, max rows per group, max bytes per file, write mode, stable row IDs, data storage version, v2 manifest paths, storage options, storage options provider, initial bases, and target bases.

Compaction options:

• build_compaction_options - Builds a CompactionOptions struct from Java Optional parameters including target rows per fragment, max rows per group, max bytes per file, deletion materialization settings, thread count, batch size, and index remap deferral.

Vector search:

• get_query - Converts a Java Optional<Query> to a Rust Option<Query>, extracting column name, key vector (as Float32Array), k, nprobes range, ef, refine factor, distance type, and index usage flag.

Index parameters:

• get_vector_index_params - Extracts vector index parameters from Java, building VectorIndexParams with IVF (including optional pre-trained centroids), PQ/SQ sub-quantizers, HNSW graph parameters, distance type, and index file version.
• get_scalar_index_params - Extracts scalar index parameters (BTree configuration).

Java object creation helpers:

• to_rust_map / to_java_map - Bidirectional conversion between Java Map and Rust HashMap.
• to_java_optional - Wraps a value in a Java Optional.
• to_java_long_obj - Creates a Java Long from a Rust integer.
• to_java_boolean_obj - Creates a Java Boolean from a Rust bool.
• to_java_float_obj - Creates a Java Float from a Rust f32.

Usage

Use this module whenever JNI code needs to extract compound parameters from Java (write params, compaction options, queries, index params) or create Java wrapper objects. It is imported by blocking_dataset, blocking_scanner, fragment, optimize, and other modules.

Code Reference

Source Location

java/lance-jni/src/utils.rs

Signature

pub fn extract_storage_options(
    env: &mut JNIEnv,
    storage_options_obj: &JObject,
) -> Result<HashMap<String, String>>;

pub fn extract_write_params(
    env: &mut JNIEnv,
    max_rows_per_file: &JObject,
    max_rows_per_group: &JObject,
    max_bytes_per_file: &JObject,
    mode: &JObject,
    enable_stable_row_ids: &JObject,
    data_storage_version: &JObject,
    enable_v2_manifest_paths: Option<&JObject>,
    storage_options_obj: &JObject,
    storage_options_provider_obj: &JObject,
    initial_bases: &JObject,
    target_bases: &JObject,
) -> Result<WriteParams>;

pub fn build_compaction_options(
    env: &mut JNIEnv,
    target_rows_per_fragment: &JObject,
    max_rows_per_group: &JObject,
    max_bytes_per_file: &JObject,
    materialize_deletions: &JObject,
    materialize_deletions_threshold: &JObject,
    num_threads: &JObject,
    batch_size: &JObject,
    defer_index_remap: &JObject,
) -> Result<CompactionOptions>;

pub fn get_query(env: &mut JNIEnv, query_obj: JObject) -> Result<Option<Query>>;

pub fn get_vector_index_params(
    env: &mut JNIEnv, index_params_obj: JObject,
) -> Result<Box<dyn IndexParams>>;

pub fn to_rust_map(env: &mut JNIEnv, jmap: &JMap) -> Result<HashMap<String, String>>;
pub fn to_java_map<'a>(env: &mut JNIEnv<'a>, map: &HashMap<String, String>) -> Result<JObject<'a>>;
pub fn to_java_optional<'a>(env: &mut JNIEnv<'a>, obj: JObject<'a>) -> Result<JObject<'a>>;
pub fn to_java_long_obj<'a>(env: &mut JNIEnv<'a>, value: i64) -> Result<JObject<'a>>;
pub fn to_java_boolean_obj<'a>(env: &mut JNIEnv<'a>, value: bool) -> Result<JObject<'a>>;
pub fn to_java_float_obj<'a>(env: &mut JNIEnv<'a>, value: f32) -> Result<JObject<'a>>;

Import

use crate::utils::{
    extract_storage_options, extract_write_params, build_compaction_options,
    get_query, get_vector_index_params, get_scalar_index_params,
    to_rust_map, to_java_map, to_java_optional, to_java_long_obj,
    to_java_boolean_obj, to_java_float_obj,
};

I/O Contract

Direction	Type	Description
Input	&JObject (Java Optional/Map)	Java objects wrapping write, compaction, or query parameters
Input	&JMap	Java Map for storage options or metadata
Output	Result<WriteParams>	Fully constructed Rust write parameters
Output	Result<CompactionOptions>	Fully constructed Rust compaction options
Output	Result<Option<Query>>	Optional vector search query
Output	Result<Box<dyn IndexParams>>	Vector or scalar index parameters
Output	Result<HashMap<String, String>>	Rust map from Java Map
Output	Result<JObject>	Java Optional, Long, Boolean, or Float wrapper objects

Usage Examples

use crate::utils::{extract_write_params, build_compaction_options, to_rust_map};

// Extract write parameters from Java objects
fn prepare_write(env: &mut JNIEnv, /* java params */) -> Result<WriteParams> {
    extract_write_params(
        env,
        &max_rows_per_file,
        &max_rows_per_group,
        &max_bytes_per_file,
        &mode,
        &enable_stable_row_ids,
        &data_storage_version,
        Some(&enable_v2_manifest_paths),
        &storage_options_obj,
        &storage_options_provider_obj,
        &initial_bases,
        &target_bases,
    )
}

// Convert a Java Map to a Rust HashMap
fn read_options(env: &mut JNIEnv, map_obj: &JObject) -> Result<HashMap<String, String>> {
    let jmap = JMap::from_env(env, map_obj)?;
    to_rust_map(env, &jmap)
}

Related Pages

• Implementation:Lance_format_Lance_JNI_BlockingDataset - Primary consumer of write params and storage options
• Implementation:Lance_format_Lance_JNI_BlockingScanner - Uses get_query for vector search configuration
• Implementation:Lance_format_Lance_JNI_Fragment - Uses extract_write_params for fragment creation
• Implementation:Lance_format_Lance_JNI_Optimize - Uses build_compaction_options for compaction
• Implementation:Lance_format_Lance_JNI_FFI - JNIEnvExt methods called within these utilities