Heuristic:Lance format Lance Warning Deprecated Java APIs

Knowledge Sources	Lance Internal
Domains	Java_Bindings, Deprecation
Last Updated	2026-02-08 22:00 GMT

Overview

DEPRECATION WARNING: Several Java API classes and methods are marked @Deprecated with documented migration paths to newer builder-pattern APIs.

Description

The Lance Java SDK has undergone significant API modernization. Older method-based APIs are being replaced with builder patterns for improved ergonomics and extensibility. The key deprecations are:

1. FragmentOperation class (entire class deprecated):

Old: FragmentOperation.Append, FragmentOperation.Overwrite
New: Use Transaction instead

2. Dataset static factory methods:

Old: Dataset.create(...), Dataset.open(String), Dataset.commit(...)
New: Dataset.write().uri(...).execute(), Dataset.open().uri(...).build(), Transaction

3. Fragment static factory methods:

Old: Fragment.create(...)
New: Fragment.write().datasetUri(...).execute()

4. Namespace API:

Old: create_empty_table
New: declare_table (scheduled for removal in 3.0.0)

5. Cache configuration:

Old: ReadOptions.setIndexCacheSize(int) (entry count)
New: ReadOptions.setIndexCacheSizeBytes(long) (byte-based)

Usage

Reference this warning when:

Writing Java integration code -- use the new builder APIs, not deprecated factory methods
Reviewing Java SDK usage examples -- ensure they use current API patterns
Planning Java SDK updates -- be aware of the 3.0.0 removal timeline for namespace APIs

The Insight (Rule of Thumb)

Action: Always use builder-pattern APIs (Dataset.write(), Dataset.open(), Fragment.write()) instead of deprecated static factory methods.
Action: Use Transaction for commit operations instead of Dataset.commit() or FragmentOperation.
Action: Use byte-based cache sizing (setIndexCacheSizeBytes) instead of entry-count-based (setIndexCacheSize).
Trade-off: Builder APIs are slightly more verbose but provide better extensibility and default handling.

Reasoning

The builder pattern allows adding new parameters without breaking existing callers. The transition from FragmentOperation to Transaction unifies all dataset mutation operations under a single abstraction. Cache sizing by bytes rather than entry count provides more predictable memory control, since entries can vary widely in size.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment