Implementation:Lance format Lance Java UpdateConfig

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

Overview

The UpdateConfig class is a transaction operation that updates dataset configuration values, schema metadata, table metadata, and field metadata using the UpdateMap pattern.

Description

UpdateConfig implements the Operation interface and is used with Dataset.newTransactionBuilder() to atomically update metadata associated with a Lance dataset. It supports four categories of metadata updates, each using the UpdateMap pattern:

• configUpdates: Dataset configuration key-value pairs (supports both upsert and delete via null values)
• tableMetadataUpdates: Table-level metadata (e.g., dataset description, version labels)
• schemaMetadataUpdates: Schema-level metadata
• fieldMetadataUpdates: Per-field metadata keyed by field ID

Each UpdateMap supports:

• Incremental mode (replace=false): Merges updates with existing values; null values indicate deletion
• Replace mode (replace=true): Completely replaces all existing values with the provided map

The class is constructed via a nested Builder class and provides both the current UpdateMap-based API and deprecated backward-compatible methods for the legacy API.

Usage

Use UpdateConfig when you need to modify dataset configuration, table metadata, schema metadata, or field metadata as part of a transaction. This is the recommended approach over the deprecated Dataset.updateConfig() and Dataset.deleteConfigKeys() methods.

Code Reference

Source Location

Property	Value
File	java/src/main/java/org/lance/operation/UpdateConfig.java
Package	org.lance.operation
Lines	394

Signature

public class UpdateConfig implements Operation

Import

import org.lance.operation.UpdateConfig;
import org.lance.operation.UpdateMap;

I/O Contract

Builder Methods (Input)

Method	Parameter Type	Description
configUpdates(UpdateMap)	UpdateMap	Dataset config key-value updates
tableMetadataUpdates(UpdateMap)	UpdateMap	Table-level metadata updates
schemaMetadataUpdates(UpdateMap)	UpdateMap	Schema-level metadata updates
fieldMetadataUpdates(Map<Integer, UpdateMap>)	Map<Integer, UpdateMap>	Per-field metadata by field ID

Accessor Methods (Output)

Method	Return Type	Description
configUpdates()	UpdateMap	Returns the config updates
tableMetadataUpdates()	UpdateMap	Returns the table metadata updates
schemaMetadataUpdates()	UpdateMap	Returns the schema metadata updates
fieldMetadataUpdates()	Map<Integer, UpdateMap>	Returns the field metadata updates
name()	String	Returns "UpdateConfig"

Usage Examples

Updating Dataset Configuration

import org.lance.Dataset;
import org.lance.operation.UpdateConfig;
import org.lance.operation.UpdateMap;
import java.util.Map;

UpdateMap configUpdates = UpdateMap.builder()
    .updates(Map.of(
        "key1", "value1",
        "key2", "value2"
    ))
    .replace(false)  // incremental update
    .build();

UpdateConfig operation = UpdateConfig.builder()
    .configUpdates(configUpdates)
    .build();

Dataset newDataset = dataset.newTransactionBuilder()
    .operation(operation)
    .build()
    .commit();

Deleting Configuration Keys

import org.lance.operation.UpdateConfig;
import org.lance.operation.UpdateMap;
import java.util.HashMap;
import java.util.Map;

// Use null values to indicate deletion
Map<String, String> updates = new HashMap<>();
updates.put("deprecated_key1", null);
updates.put("deprecated_key2", null);

UpdateMap configUpdates = UpdateMap.builder()
    .updates(updates)
    .replace(false)
    .build();

UpdateConfig operation = UpdateConfig.builder()
    .configUpdates(configUpdates)
    .build();

Dataset newDataset = dataset.newTransactionBuilder()
    .operation(operation)
    .build()
    .commit();

Updating Multiple Metadata Categories

import org.lance.operation.UpdateConfig;
import org.lance.operation.UpdateMap;
import java.util.Map;

// Table metadata
UpdateMap tableMetadata = UpdateMap.builder()
    .updates(Map.of(
        "dataset_description", "ML training dataset v2",
        "version", "2.0"
    ))
    .replace(false)
    .build();

// Schema metadata
UpdateMap schemaMetadata = UpdateMap.builder()
    .updates(Map.of("schema_version", "3"))
    .replace(false)
    .build();

// Field metadata (field ID 0)
UpdateMap field0Metadata = UpdateMap.builder()
    .updates(Map.of("field_description", "Primary key"))
    .replace(false)
    .build();

UpdateConfig operation = UpdateConfig.builder()
    .tableMetadataUpdates(tableMetadata)
    .schemaMetadataUpdates(schemaMetadata)
    .fieldMetadataUpdates(Map.of(0, field0Metadata))
    .build();

Dataset newDataset = dataset.newTransactionBuilder()
    .operation(operation)
    .build()
    .commit();

Replacing All Configuration

import org.lance.operation.UpdateConfig;
import org.lance.operation.UpdateMap;
import java.util.Map;

// Replace mode: all existing config values are removed
// and replaced with the provided map
UpdateMap configUpdates = UpdateMap.builder()
    .updates(Map.of(
        "setting1", "new_value1",
        "setting2", "new_value2"
    ))
    .replace(true)  // replaces ALL existing config
    .build();

UpdateConfig operation = UpdateConfig.builder()
    .configUpdates(configUpdates)
    .build();

Dataset newDataset = dataset.newTransactionBuilder()
    .operation(operation)
    .build()
    .commit();

Related Pages

• Lance_format_Lance_Java_Dataset - Dataset class that uses UpdateConfig through transactions
• Lance_format_Lance_Java_WriteDatasetBuilder - Alternative for creating datasets with initial configuration