Control batch sizes for vectorized operations:

| Property | Description | Default |

|----------|-------------|---------|

| `lance.read_batch_size` | Rows per batch during vectorized reads | `8192` |

| `lance.write_batch_size` | Rows to batch before writing to Arrow | `10000` |

| `lance.max_rows_per_file` | Maximum rows per Lance file | `1000000` |

| `lance.max_rows_per_group` | Maximum rows per row group | `100000` |

This guide covers performance tuning for Lance Trino operations in large-scale analytics scenarios.

Lance is **optimized by default for random access patterns** - fast point lookups, vector searches, and selective column reads.

These defaults work well for ML/AI workloads where you frequently access individual records or small batches.

For **large-scale batch ETL and scan-heavy OLAP operations** (writing millions of rows, full table scans, bulk exports),

you can tune Lance's environment variables and connector properties to better utilize available resources.

Lance Trino uses a multi-level caching strategy to minimize redundant I/O and improve query performance.

Lance Trino implements two levels of caching:

1. **Session Cache** - Contains index and metadata caches:

- **Index Cache**: Caches opened vector indices, fragment reuse indices, and index metadata

- **Metadata Cache**: Caches manifests, transactions, deletion files, row ID indices, and file metadata

2. **Dataset Cache** - Caches opened datasets by `(userIdentity, tablePath, version)` key. Since a dataset at a specific version is immutable, this ensures:

- Each dataset is opened only once per worker

- All workers read the same version for snapshot isolation

- Schema and fragment metadata are reused from the cached dataset

Configure caching behavior via connector properties in your catalog file:

lance.cache.session.max_entries=100 # Maximum cached sessions (default: 100)

lance.cache.session.ttl_minutes=60 # Session cache TTL in minutes (default: 60)

lance.cache.session.index_cache_size_bytes=6442450944 # Index cache size: 6GB

lance.cache.session.metadata_cache_size_bytes=1073741824 # Metadata cache size: 1GB

lance.cache.dataset.max_entries=100 # Maximum cached datasets (default: 100)

lance.cache.dataset.ttl_minutes=30 # Dataset cache TTL in minutes (default: 30)

| Property | Description | Default |

|----------|-------------|---------|

| `lance.cache.session.max_entries` | Maximum number of cached sessions | `100` |

| `lance.cache.session.ttl_minutes` | Session cache TTL in minutes | `60` |

| `lance.cache.session.index_cache_size_bytes` | Index cache size in bytes | Lance default (6GB) |

| `lance.cache.session.metadata_cache_size_bytes` | Metadata cache size in bytes | Lance default (1GB) |

| `lance.cache.dataset.max_entries` | Maximum number of cached datasets | `100` |

| `lance.cache.dataset.ttl_minutes` | Dataset cache TTL in minutes | `30` |

The index cache stores vector indices which can be large but provide significant speedup for vector search queries.

Increase this if you frequently query tables with vector indices.

The metadata cache stores manifests, file metadata, and other dataset metadata.

Each column's metadata can be around 40MB, so increase this if your tables have many columns.

Lance uses environment variables for low-level I/O tuning. Set these on your Trino coordinator and worker nodes.

Set via environment variable `LANCE_IO_THREADS` (default: 64).

Controls the number of I/O threads used for parallel reads from storage.

For large scans, increasing this to match your CPU core count enables more concurrent S3 requests.

export LANCE_IO_THREADS=128

Set via environment variable `LANCE_UPLOAD_CONCURRENCY` (default: 10).

Controls the number of concurrent multipart upload streams to S3.

Increasing this to match your CPU core count can improve throughput.

export LANCE_UPLOAD_CONCURRENCY=32

Set via environment variable `LANCE_INITIAL_UPLOAD_SIZE` (default: 5MB).

Controls the initial part size for S3 multipart uploads.

Larger part sizes reduce the number of API calls and can improve throughput for large writes.

However, larger part sizes use more memory and may increase latency for small writes.

Use the default for interactive workloads.

!!!note

Lance automatically increments the multipart upload size by 5MB every 100 uploads,

so large file writes progressively use increasingly large upload parts.

There is no configuration for a fixed upload size.

export LANCE_INITIAL_UPLOAD_SIZE=33554432 # 32MB

| Variable | Description | Default |

|----------|-------------|---------|

| `LANCE_IO_THREADS` | Number of I/O threads for parallel reads | `64` |

| `LANCE_UPLOAD_CONCURRENCY` | Number of concurrent S3 upload streams | `10` |

| `LANCE_INITIAL_UPLOAD_SIZE` | Initial S3 multipart upload part size (bytes) | `5242880` (5MB) |

Lance Trino optimizes split planning based on index availability. When a table has indexes on filtered columns, larger splits are used because index lookups are efficient.

lance.index.btree.rows_per_split=100000000

lance.index.bitmap.rows_per_split=10000000

| Property | Description | Default |

|----------|-------------|---------|

| `lance.index.btree.rows_per_split` | Row count threshold for btree-indexed splits | `100000000` (100M) |

| `lance.index.bitmap.rows_per_split` | Row count threshold for bitmap-indexed splits | `10000000` (10M) |

<version>3.0.0-beta.4</version>

<!-- Currently unused but kept for potential future use -->

<ignoredUnusedDeclaredDependency>io.trino:trino-cache</ignoredUnusedDeclaredDependency>

<!-- Used for @SuppressModernizer annotation -->

<ignoredUnusedDeclaredDependency>org.gaul:modernizer-maven-annotations</ignoredUnusedDeclaredDependency>

<ignoredUsedUndeclaredDependencies>

<!-- Provided transitively by the parent pom -->

<ignoredUsedUndeclaredDependency>org.gaul:modernizer-maven-annotations</ignoredUsedUndeclaredDependency>

</ignoredUsedUndeclaredDependencies>

OptionalLong limit,

String userIdentity,

Long datasetVersion)

this(allocator, path, columns, List.of(), scannerFactory, storageOptions, substraitFilter, limit, userIdentity, datasetVersion);

OptionalLong limit,

String userIdentity,

Long datasetVersion)

lanceScanner = scannerFactory.open(path, allocator, projectionColumns, storageOptions, substraitFilter, limit, userIdentity, datasetVersion);

public LanceBasePageSource(LanceTableHandle tableHandle, List<LanceColumnHandle> columns, ScannerFactory scannerFactory, Map<String, String> storageOptions, String userIdentity)

this(tableHandle, columns, List.of(), scannerFactory, storageOptions, userIdentity);

public LanceBasePageSource(LanceTableHandle tableHandle, List<LanceColumnHandle> columns, List<String> filterProjectionColumns, ScannerFactory scannerFactory, Map<String, String> storageOptions, String userIdentity)

tableHandle.getLimit(),

userIdentity,

tableHandle.getDatasetVersion());

@Config("lance.index.btree.rows_per_split")

@Config("lance.index.bitmap.rows_per_split")

// ===== Cache Configuration =====

private int cacheSessionMaxEntries = 100;

private int cacheSessionTtlMinutes = 60;

private Long cacheSessionIndexCacheSizeBytes; // null = use Lance default

private Long cacheSessionMetadataCacheSizeBytes; // null = use Lance default

private int cacheDatasetMaxEntries = 100;

private int cacheDatasetTtlMinutes = 30;

public int getCacheSessionMaxEntries()

{

return cacheSessionMaxEntries;

}

@Config("lance.cache.session.max_entries")

@ConfigDescription("Maximum number of cached sessions (default 100)")

public LanceConfig setCacheSessionMaxEntries(int cacheSessionMaxEntries)

{

this.cacheSessionMaxEntries = cacheSessionMaxEntries;

return this;

}

public int getCacheSessionTtlMinutes()

{

return cacheSessionTtlMinutes;

}

@Config("lance.cache.session.ttl_minutes")

@ConfigDescription("Session cache TTL in minutes (default 60)")

public LanceConfig setCacheSessionTtlMinutes(int cacheSessionTtlMinutes)

{

this.cacheSessionTtlMinutes = cacheSessionTtlMinutes;

return this;

}

public Long getCacheSessionIndexCacheSizeBytes()

{

return cacheSessionIndexCacheSizeBytes;

}

@Config("lance.cache.session.index_cache_size_bytes")

@ConfigDescription("Lance session index cache size in bytes (default: Lance default)")

public LanceConfig setCacheSessionIndexCacheSizeBytes(Long cacheSessionIndexCacheSizeBytes)

{

this.cacheSessionIndexCacheSizeBytes = cacheSessionIndexCacheSizeBytes;

return this;

}

public Long getCacheSessionMetadataCacheSizeBytes()

{

return cacheSessionMetadataCacheSizeBytes;

}

@Config("lance.cache.session.metadata_cache_size_bytes")

@ConfigDescription("Lance session metadata cache size in bytes (default: Lance default)")

public LanceConfig setCacheSessionMetadataCacheSizeBytes(Long cacheSessionMetadataCacheSizeBytes)

{

this.cacheSessionMetadataCacheSizeBytes = cacheSessionMetadataCacheSizeBytes;

return this;

}

public int getCacheDatasetMaxEntries()

{

return cacheDatasetMaxEntries;

}

@Config("lance.cache.dataset.max_entries")

@ConfigDescription("Maximum number of cached datasets (default 100)")

public LanceConfig setCacheDatasetMaxEntries(int cacheDatasetMaxEntries)

{

this.cacheDatasetMaxEntries = cacheDatasetMaxEntries;

return this;

}

public int getCacheDatasetTtlMinutes()

{

return cacheDatasetTtlMinutes;

}

@Config("lance.cache.dataset.ttl_minutes")

@ConfigDescription("Dataset cache TTL in minutes (default 30)")

public LanceConfig setCacheDatasetTtlMinutes(int cacheDatasetTtlMinutes)

{

this.cacheDatasetTtlMinutes = cacheDatasetTtlMinutes;

return this;

}