feat: Lazy DAO fields by obabichevjb · Pull Request #2713 · JetBrains/Exposed

obabichevjb · 2026-01-17T09:56:55Z

Description

Summary of the change: Added lazy loading support for DAO entity fields, allowing developers to mark large or rarely-accessed columns (e.g., BLOB, TEXT) as lazy-loaded to improve query performance and reduce memory usage.

What:
- Added a new LazyEntityField class that implements property delegation for lazy-loaded columns
- Added the .lazy() extension function to mark entity properties as lazy-loaded
- Implemented a dedicated cache (lazyFieldCache) in the Entity class to store lazy field values
How:
- LazyEntityField.kt: New class implementing getValue()/setValue() operators for lazy property delegation. Maintains a global registry of lazy columns per table. On first access, executes a targeted SELECT query for that specific column and caches the result.
- Entity.kt: Added lazyFieldCache HashMap to store lazy field values independently from readValues. Modified storeWrittenValues() to cache lazy fields during flush, preventing unnecessary database queries. Added refresh() support to clear lazy field cache.

Type of Change

Please mark the relevant options with an "X":

New feature
Documentation update

Affected databases:

All

Related Issues

Can DAO API support conditional retrieve some columns?

obabichevjb · 2026-01-17T10:03:00Z

+         * Maps each table to a set of its lazy columns.
+         * This allows EntityClass to efficiently filter out lazy columns for its specific table.
+         */
+        internal val lazyColumns = mutableMapOf<Table, MutableSet<Column<*>>>()


In terms of API I didn't want to extend DSL layer, because it doesn't look like DSL need lazy column, so I wanted the method like lazy() exists only in Entities, but in this case it's a bit complicated to track which fields are lazy and which are not, because columns in DAO are delegates.

So I stopped at the variant of creating global cache for lazy columns assuming that in general it's not a big set. Every column is registered in the moment of call lazy().

Initially I hoped that in the moment of call lazy() the column could be stored inside entity, but at that moment it's not initialized yet.

vnikolova

Docs look good, thanks for the addition! 👍
Suggested some small edits below.

vnikolova · 2026-01-20T09:47:30Z

+        <chapter id="lazy-fields" title="Lazy fields">
+            <p>
+                By default, all entity properties are loaded immediately when an entity is retrieved from the database.
+                However, for large columns like BLOBs or TEXT fields, or for rarely accessed data, this can negatively


Suggested change

However, for large columns like BLOBs or TEXT fields, or for rarely accessed data, this can negatively

However, for large columns like BLOB or TEXT fields, or for rarely accessed data, this behavior can negatively

vnikolova · 2026-01-20T09:49:50Z

+            <p>
+                Exposed provides the
+                <a href="%BASE_API_URL%/exposed-dao/org.jetbrains.exposed.dao/-entity/lazy.html"><code>.lazy()</code></a>
+                modifier to mark columns as lazy-loaded. Lazy fields are:


Suggested change

modifier to mark columns as lazy-loaded. Lazy fields are:

modifier, which allows you to mark columns as lazy-loaded. Lazy fields are:

vnikolova · 2026-01-20T09:50:10Z

+                modifier to mark columns as lazy-loaded. Lazy fields are:
+            </p>
+            <list>
+                <li>Excluded from the default entity query</li>


Suggested change

<li>Excluded from the default entity query</li>

<li>Excluded from the default entity query.</li>

vnikolova · 2026-01-20T09:50:18Z

+            </p>
+            <list>
+                <li>Excluded from the default entity query</li>
+                <li>Loaded on-demand when first accessed</li>


Suggested change

<li>Loaded on-demand when first accessed</li>

<li>Loaded on-demand when first accessed.</li>

vnikolova · 2026-01-20T09:50:45Z

+            <list>
+                <li>Excluded from the default entity query</li>
+                <li>Loaded on-demand when first accessed</li>
+                <li>Cached after the first access to avoid redundant queries</li>


Suggested change

<li>Cached after the first access to avoid redundant queries</li>

<li>Cached after the first access to avoid redundant queries.</li>

vnikolova · 2026-01-20T09:58:54Z

+     *
+     * On first access:
+     * 1. Checks for active transaction
+     * 2. Flushes entity if it has pending writes


Suggested change

* 2. Flushes entity if it has pending writes

* 2. Flushes the entity if it has pending writes.

vnikolova · 2026-01-20T09:59:09Z

+     * On first access:
+     * 1. Checks for active transaction
+     * 2. Flushes entity if it has pending writes
+     * 3. Loads this lazy column value from the database


Suggested change

* 3. Loads this lazy column value from the database

* 3. Loads the lazy column value from the database.

vnikolova · 2026-01-20T10:00:07Z

+     * 1. Checks for active transaction
+     * 2. Flushes entity if it has pending writes
+     * 3. Loads this lazy column value from the database
+     * 4. Caches the lazy value for subsequent accesses


Suggested change

* 4. Caches the lazy value for subsequent accesses

* 4. Caches the lazy column value for subsequent accesses.

vnikolova · 2026-01-20T10:00:44Z

+    /**
+     * Sets the value of this lazy field for the given entity.
+     *
+     * The value is stored in the entity's write values and will be persisted on flush.


Suggested change

* The value is stored in the entity's write values and will be persisted on flush.

* The value is stored in the entity's write values and is persisted on flush.

vnikolova · 2026-01-20T10:02:23Z

+import org.jetbrains.exposed.v1.core.Column
+
+/**
+ * An exception that provides information about a lazy [column] that was accessed


Suggested change

* An exception that provides information about a lazy [column] that was accessed

* An exception that provides information about a lazy [column] accessed

e5l

lgtm

feat: Lazy DAO fields

2cb9cba

obabichevjb commented Jan 17, 2026

View reviewed changes

obabichevjb requested review from bog-walk, e5l and vnikolova January 17, 2026 10:03

vnikolova reviewed Jan 20, 2026

View reviewed changes

e5l approved these changes Jan 20, 2026

View reviewed changes

	However, for large columns like BLOBs or TEXT fields, or for rarely accessed data, this can negatively
	However, for large columns like BLOB or TEXT fields, or for rarely accessed data, this behavior can negatively

	modifier to mark columns as lazy-loaded. Lazy fields are:
	modifier, which allows you to mark columns as lazy-loaded. Lazy fields are:

	<li>Excluded from the default entity query</li>
	<li>Excluded from the default entity query.</li>

	<li>Loaded on-demand when first accessed</li>
	<li>Loaded on-demand when first accessed.</li>

	<li>Cached after the first access to avoid redundant queries</li>
	<li>Cached after the first access to avoid redundant queries.</li>

	* 2. Flushes entity if it has pending writes
	* 2. Flushes the entity if it has pending writes.

	* 3. Loads this lazy column value from the database
	* 3. Loads the lazy column value from the database.

	* 4. Caches the lazy value for subsequent accesses
	* 4. Caches the lazy column value for subsequent accesses.

	* The value is stored in the entity's write values and will be persisted on flush.
	* The value is stored in the entity's write values and is persisted on flush.

	* An exception that provides information about a lazy [column] that was accessed
	* An exception that provides information about a lazy [column] accessed

Conversation

obabichevjb commented Jan 17, 2026

Description

Type of Change

Related Issues

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vnikolova left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

e5l left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants