### Find Entities by Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/entities.md

Finds entities that match criteria defined in an example object. Supports optional sorting and fetching specific properties using a Fetcher.

```java
public <E> List<E> findByExample(
    Example<E> example,
    TypedProp.Scalar<?, ?> ... sortedProps
)
public <E> List<E> findByExample(
    Example<E> example,
    Fetcher<E> fetcher,
    TypedProp.Scalar<?, ?> ... sortedProps
)
```

```java
Book exampleBook = Objects.createBook(draft -> {
    draft.setAuthorId(1L); // Filter by author
    // name and other properties unspecified, ignored in query
});

Example<Book> example = Example.of(exampleBook);

List<Book> books = sqlClient.getEntities()
    .findByExample(example, BookProps.PRICE.asc());

// With fetcher
Fetcher<Book> fetcher = Fetcher.create(Book.class).allScalarFields();
List<Book> booksWithDetails = sqlClient.getEntities()
    .findByExample(example, fetcher, BookProps.PRICE.asc());
```

--------------------------------

### Complete Entity Definition Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/annotations.md

An example demonstrating a comprehensive entity definition with various annotations for primary keys, unique keys, descriptions, columns, associations, formulas, and versioning.

```java
@Entity
@Description("Book catalog entry")
public interface Book {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    long id();
    
    @Key  // Unique key for INSERT_IF_ABSENT
    String isbn();
    
    @Description("Book title")
    String name();
    
    BigDecimal price();
    
    @Column(nullable = false)
    String description();
    
    @Formula(sql = "LENGTH(NAME)")
    int nameLength();
    
    @ManyToOne
    Author author();
    
    @ManyToMany
    List<Tag> tags();
    
    @Column(insertable = false, updatable = false)
    LocalDateTime createdTime();
    
    @Version
    int version();  // For optimistic locking
}
```

--------------------------------

### Example<E>

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/types.md

Query-by-example specification for finding entities, used in conjunction with the `findByExample` method.

```APIDOC
## Example<E>

### Description
Query-by-example specification for finding entities.

**Used by:** `findByExample(Example<E>)`
```

--------------------------------

### Page getTotalPageCount() Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Demonstrates how to retrieve the total number of pages available.

```java
Page<Book> page = /* ... */;
long pageCount = page.getTotalPageCount(); // 5
```

--------------------------------

### Configure Database Naming Strategy with SnakeCase

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/configuration.md

Example of setting a SnakeCaseNamingStrategy for database naming.

```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setDatabaseNamingStrategy(new SnakeCaseNamingStrategy())
    .build();
```

--------------------------------

### Complete Save Operation Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

This example demonstrates building an entity with nested associations and configuring a complex save operation using UPSERT mode with different association save strategies.

```java
// Build entity with nested associations
Book book = Objects.createBook(draft -> {
    draft.setId(1L);
    draft.setName("Clean Code");
    draft.setPrice(50.00);
    draft.setAuthor(Objects.createAuthor(author -> {
        author.setId(1L);
        author.setName("Robert C. Martin");
    }));
    draft.setTags(Arrays.asList(
        Objects.createTag(tag -> {
            tag.setId(1L);
            tag.setName("Best Practices");
        }),
        Objects.createTag(tag -> {
            tag.setName("New Tag");
            // No id - new tag
        })
    ));
});

// Configure save behavior
SimpleSaveResult<Book> result = sqlClient.saveCommand(book)
    .setMode(SaveMode.UPSERT)  // Insert or update book
    .setAssociatedMode(BookProps.AUTHOR, AssociatedSaveMode.REPLACE)
    .setAssociatedMode(BookProps.TAGS, AssociatedSaveMode.MERGE)
    .execute();

// Inspect result
Book modified = result.getModifiedEntity();
System.out.println("Book saved with id: " + modified.id());
System.out.println("Total rows affected: " + result.getTotalAffectedRowCount());

for (Map.Entry<AffectedTable, Integer> entry : 
     result.getAffectedRowCountByTable().entrySet()) {
    System.out.println("Table " + entry.getKey() + ": " + 
                      entry.getValue() + " rows");
}
```

--------------------------------

### findByExample

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/entities.md

Searches for entities that match a given example object. This method supports filtering by example criteria and allows for optional sorting and fetching of specific properties using a Fetcher. It can return a list of entities or a list of DTOs projected from the matching entities.

```APIDOC
## findByExample()

### Description
Find entities matching an example object (query by example). Supports returning a list of entities or a list of DTOs projected from matching entities.

### Method
`findByExample(Example<E> example, TypedProp.Scalar<?, ?> ... sortedProps)`
`findByExample(Example<E> example, Fetcher<E> fetcher, TypedProp.Scalar<?, ?> ... sortedProps)`
`findExample(Class<V> viewType, Example<E> example, TypedProp.Scalar<?, ?> ... sortedProps)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **example** (Example<E>) - Required - Example object with criteria
- **fetcher** (Fetcher<E>) - Optional - Fetcher for properties to load
- **viewType** (Class<V>) - Required - DTO view type (for findExample)
- **sortedProps** (TypedProp.Scalar...) - Optional - Properties to sort by

### Response
#### Success Response (200)
- **List<E>** or **List<V>** - Matching entities or DTOs of matching entities

### Request Example
```java
Book exampleBook = Objects.createBook(draft -> {
    draft.setAuthorId(1L); // Filter by author
    // name and other properties unspecified, ignored in query
});

Example<Book> example = Example.of(exampleBook);

List<Book> books = sqlClient.getEntities()
    .findByExample(example, BookProps.PRICE.asc());

// With fetcher
Fetcher<Book> fetcher = Fetcher.create(Book.class).allScalarFields();
List<Book> booksWithDetails = sqlClient.getEntities()
    .findByExample(example, fetcher, BookProps.PRICE.asc());

// DTO projection
List<BookDTO> dtos = sqlClient.getEntities()
    .findExample(BookDTO.class, example, BookProps.NAME.asc());
```
```

--------------------------------

### Page getTotalRowCount() Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Illustrates how to get the total number of rows across all pages.

```java
Page<Book> page = /* ... */;
long total = page.getTotalRowCount(); // 150
```

--------------------------------

### Find Entities by Example with DTO Projection

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/entities.md

Finds entities matching an example and projects the results into a specified DTO (View) type. Allows for returning data in a different structure than the entity.

```java
public <E, V extends View<E>> List<V> findExample(
    Class<V> viewType, 
    Example<E> example, 
    TypedProp.Scalar<?, ?> ... sortedProps
)
```

```java
Book exampleBook = Objects.createBook(draft -> {
    draft.setAuthorId(1L);
});
Example<Book> example = Example.of(exampleBook);

// Returns BookDTO objects, not Book
List<BookDTO> dtos = sqlClient.getEntities()
    .findExample(BookDTO.class, example, BookProps.NAME.asc());
```

--------------------------------

### Page Constructor Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Demonstrates creating a Page instance with a list of rows, total row count, and total page count.

```java
List<Book> books = /* query results */;
Page<Book> page = new Page<>(books, 150, 5);
// 150 total books, 5 pages total
```

--------------------------------

### Example: Upsert with Specific Properties

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Shows how to update only the name and price of a book during an upsert operation using `setUpsertMask` with specific properties.

```java
Book book = Objects.createBook(draft -> {
    draft.setId(1L);
    draft.setName("Updated");
    draft.setPrice(29.99);
});

sqlClient.saveCommand(book)
    .setUpsertMask(BookProps.NAME, BookProps.PRICE)
    .execute();
// Only these properties are updated; others are left alone
```

--------------------------------

### Complete Fetcher Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/fetcher.md

Demonstrates creating a fetcher for the Book entity, including nested associations for Author and Publisher. Shows how to use the fetcher with a SQL client query.

```java
Fetcher<Book> bookFetcher = Fetcher.create(Book.class)
    .add("id")
    .add("name")
    .add("isbn")
    .add("price")
    .add("author", Fetcher.create(Author.class)
        .add("id")
        .add("name")
        .add("email")
    )
    .add("publisher", Fetcher.create(Publisher.class)
        .allScalarFields()
    );

// Use in query
List<Book> books = sqlClient
    .createQuery(BookTable.class)
    .select(book)
    .fetch(bookFetcher);

// Each book now has:
// - id, name, isbn, price (scalars)
// - author with id, name, email
// - publisher with all scalar fields
```

--------------------------------

### toString

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/fetcher.md

Gets a string representation of the fetcher.

```APIDOC
## toString

### Description
Get a string representation of the fetcher.

### Method
`toString(boolean multiLine)`

### Parameters
#### Path Parameters
- **multiLine** (boolean) - Yes - true for readable multi-line format, false for single line

### Returns
`String` — Formatted string representation
```

--------------------------------

### Using Page for Full Pagination

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Example of querying data with full pagination details using `fetchPage`. Suitable for traditional pagination UIs.

```java
// Query with page information
Page<Book> page = sqlClient.createQuery(BookTable.class)
    .select(book)
    .limit(10)  // page size
    .offset(20) // skip 20 rows for page 3
    .fetchPage(1);

System.out.println("Page 1 of " + page.getTotalPageCount());
System.out.println("Total books: " + page.getTotalRowCount());
for (Book book : page.getRows()) {
    System.out.println(book.getName());
}
```

--------------------------------

### Page getRows() Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Shows how to retrieve and iterate over the list of row objects for the current page.

```java
Page<Book> page = /* ... */;
for (Book book : page.getRows()) {
    System.out.println(book.getName());
}
```

--------------------------------

### JSqlClient Builder Configuration Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Demonstrates the usage of the JSqlClient.Builder to configure various aspects of the client, including connection management, dialect, caching, and filters.

```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setDialect(new MySqlDialect())
    .setDefaultBatchSize(100)
    .setCaches(cache -> {
        cache.add(Book.class);
        cache.add(Author.class);
    })
    .addFilters(new SoftDeleteFilter())
    .setTriggerType(TriggerType.TRANSACTION_ONLY)
    .setDefaultBinLogJsonCodec(jsonCodec)
    .build();
```

--------------------------------

### Build JSqlClient with Full Configuration

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating the configuration of JSqlClient with various settings including connection management, dialect, validation, batching, logging, caching, filters, transactions, ID generation, and event triggers.

```java
DataSource primaryDataSource = /* ... */;
DataSource replicaDataSource = /* ... */;

JSqlClient sqlClient = JSqlClient.newBuilder()
    // JDBC
    .setConnectionManager(ConnectionManager.quill(primaryDataSource))
    .setSlaveConnectionManager(ConnectionManager.quill(replicaDataSource))
    
    // Database
    .setDialect(new MySqlDialect())
    .setDatabaseValidationMode(DatabaseValidationMode.ERROR)
    
    // Batching
    .setDefaultBatchSize(200)
    .setDefaultListBatchSize(20)
    
    // Logging
    .setExecutor((sql, variables, success, millis, reason) -> {
        if (!success) {
            logger.error("SQL error: " + sql);
        } else if (millis > 1000) {
            logger.warn("Slow query: " + sql);
        }
    })
    
    // Caching
    .setCaches(cache -> {
        cache.add(Book.class);
        cache.add(Author.class);
    })
    
    // Filters
    .addFilters(new SoftDeleteFilter())
    
    // Transactions
    .setMutationTransactionRequired(true)
    
    // ID Generation
    .setIdGenerator(new SnowflakeIdGenerator())
    
    // Events
    .setTriggerType(TriggerType.TRANSACTION_ONLY)
    
    .build();
```

--------------------------------

### Slice Constructor Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Shows how to create a Slice instance with rows and boolean flags indicating if it's the head or tail.

```java
List<Book> books = /* query results */;
Slice<Book> slice = new Slice<>(books, false, false);
// There are pages before and after this one
```

--------------------------------

### Slice getRows() Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Demonstrates retrieving and iterating over the row objects within a Slice.

```java
Slice<Book> slice = /* ... */;
for (Book book : slice.getRows()) {
    System.out.println(book.getName());
}
```

--------------------------------

### Example Interface Definition

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/types.md

A specification used for query-by-example searches, enabling entity retrieval based on specified criteria.

```java
public interface Example<E>
```

--------------------------------

### Using Slice for Efficient Pagination

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Example of querying data with minimal pagination info using `fetchSlice`. Optimized for infinite scroll or 'load more' scenarios.

```java
// Query without total count
Slice<Book> slice = sqlClient.createQuery(BookTable.class)
    .select(book)
    .limit(10)
    .offset(20)
    .fetchSlice(1);

System.out.println("Current page has " + slice.getRows().size() + " books");
if (!slice.isTail()) {
    System.out.println("Load next page available");
}
```

--------------------------------

### Reading and Creating a ClassNode with ASM

Source: https://github.com/babyfish-ct/jimmer/blob/main/project/jimmer-core/src/main/java/org/babyfish/jimmer/impl/org/objectweb/asm/tree/package.html

Demonstrates how to read bytecode into a ClassNode object for manipulation. This is the starting point for using the tree API.

```java
ClassReader classReader = new ClassReader(source);
ClassNode classNode = new ClassNode();
classReader.accept(classNode, 0);
```

--------------------------------

### Example: Insert Only Save Mode

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Illustrates how to use `setMode(SaveMode.INSERT_ONLY)` to ensure a book is inserted and fails if it already exists.

```java
Book book = Objects.createBook(draft -> {
    draft.setId(1L);
    draft.setName("New Book");
});

SimpleSaveResult<Book> result = sqlClient.saveCommand(book)
    .setMode(SaveMode.INSERT_ONLY)
    .execute();
```

--------------------------------

### Configure Multi-Layer Caching

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/configuration.md

Sets up a multi-layer caching strategy by providing a configuration block. This example adds Book and Author entities to the cache configuration.

```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setCaches(cache -> {
        cache.add(Book.class);
        cache.add(Author.class);
    })
    .build();
```

--------------------------------

### Get BinLog Interface

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Retrieve the BinLog interface for handling binary log events.

```java
public BinLog getBinLog()

// Returns: `BinLog` — Binary log interface
```

--------------------------------

### JSqlClient.newBuilder()

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Creates a new builder to construct a JSqlClient instance. This is the starting point for configuring and initializing the JSqlClient.

```APIDOC
## JSqlClient.newBuilder()

### Description
Creates a new builder to construct a JSqlClient instance.

### Method
```java
public static Builder newBuilder()
```

### Returns
`Builder` — JSqlClient.Builder instance for configuration

### Example
```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setDialect(new MySqlDialect())
    .build();
```
```

--------------------------------

### Example: Insert If Absent with Key Properties

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Demonstrates inserting a book only if a specific combination of ISBN and language does not exist, using `setMode(SaveMode.INSERT_IF_ABSENT)` and `setKeyProps`.

```java
// Find by (ISBN, language) combination
Book book = Objects.createBook(draft -> {
    draft.setIsbn("123-456");
    draft.setLanguage("EN");
    draft.setName("New Title");
});

sqlClient.saveCommand(book)
    .setMode(SaveMode.INSERT_IF_ABSENT)
    .setKeyProps(BookProps.ISBN, BookProps.LANGUAGE)
    .execute();
// Only inserts if (ISBN, language) doesn't exist
```

--------------------------------

### N+1 Prevention using Fetchers

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Avoid the N+1 query problem by using `Fetcher` to eagerly load related data in a single query. The 'bad' example shows inefficient loading, while the 'good' example demonstrates the optimized approach.

```java
// Bad: causes N+1
List<Book> books = sqlClient
    .createQuery(BookTable.class)
    .select(book)
    .execute();
for (Book b : books) {
    String authorName = b.author().name(); // N queries!
}

// Good: batch load in single query
Fetcher<Book> fetcher = Fetcher.create(Book.class)
    .add("id")
    .add("name")
    .add("author", Fetcher.create(Author.class)
        .add("id")
        .add("name")
    );

List<Book> books = sqlClient
    .createQuery(BookTable.class)
    .select(fetcher)
    .execute();
for (Book b : books) {
    String authorName = b.author().name(); // Already loaded
```

--------------------------------

### Complete Save Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Demonstrates building an entity with nested associations and configuring save behavior using various modes (UPSERT, REPLACE, MERGE). It also shows how to inspect the save result, including the modified entity and affected row counts per table.

```APIDOC
## Complete Example

### Description
Demonstrates building an entity with nested associations and configuring save behavior using various modes (UPSERT, REPLACE, MERGE). It also shows how to inspect the save result, including the modified entity and affected row counts per table.

### Method
```java
// Build entity with nested associations
Book book = Objects.createBook(draft -> {
    draft.setId(1L);
    draft.setName("Clean Code");
    draft.setPrice(50.00);
    draft.setAuthor(Objects.createAuthor(author -> {
        author.setId(1L);
        author.setName("Robert C. Martin");
    }));
    draft.setTags(Arrays.asList(
        Objects.createTag(tag -> {
            tag.setId(1L);
            tag.setName("Best Practices");
        }),
        Objects.createTag(tag -> {
            tag.setName("New Tag");
            // No id - new tag
        })
    ));
});

// Configure save behavior
SimpleSaveResult<Book> result = sqlClient.saveCommand(book)
    .setMode(SaveMode.UPSERT)  // Insert or update book
    .setAssociatedMode(BookProps.AUTHOR, AssociatedSaveMode.REPLACE)
    .setAssociatedMode(BookProps.TAGS, AssociatedSaveMode.MERGE)
    .execute();

// Inspect result
Book modified = result.getModifiedEntity();
System.out.println("Book saved with id: " + modified.id());
System.out.println("Total rows affected: " + result.getTotalAffectedRowCount());

for (Map.Entry<AffectedTable, Integer> entry : 
     result.getAffectedRowCountByTable().entrySet()) {
    System.out.println("Table " + entry.getKey() + ": " + 
                      entry.getValue() + " rows");
}
```
```

--------------------------------

### Example: Merge Associated Objects

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Demonstrates merging new authors with existing ones for a book using `setAssociatedModeAll(AssociatedSaveMode.MERGE)`.

```java
Book book = Objects.createBook(draft -> {
    draft.setId(1L);
    draft.setAuthors(Arrays.asList(author1, author2));
});

sqlClient.saveCommand(book)
    .setAssociatedModeAll(AssociatedSaveMode.MERGE)
    .execute();
// Merges new authors with existing ones
```

--------------------------------

### Set Custom Cache Factory

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/configuration.md

Replaces the default cache factory with a custom implementation. This example demonstrates setting a Redis-based cache factory.

```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setCacheFactory(new RedisBasedCacheFactory(redisClient))
    .build();
```

--------------------------------

### Example: Specific Association Save Modes

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Shows how to apply different association save modes to different properties of a book, such as merging authors and replacing the publisher.

```java
sqlClient.saveCommand(book)
    .setAssociatedMode(BookProps.AUTHORS, AssociatedSaveMode.MERGE)
    .setAssociatedMode(BookProps.PUBLISHER, AssociatedSaveMode.REPLACE)
    .execute();
```

--------------------------------

### Slice isHead() Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Illustrates checking if the current Slice is the first one in the result set.

```java
Slice<Book> slice = /* ... */;
if (!slice.isHead()) {
    System.out.println("Show 'previous' button");
}
```

--------------------------------

### Define Book Entity with Annotations

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/annotations.md

Example of defining a Book entity interface with primary key, name, and author association.

```java
@Entity
public interface Book {
    @Id
    long id();
    
    String name();
    
    @ManyToOne
    Author author();
}
```

--------------------------------

### Slice isTail() Example

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/page-slice.md

Shows how to determine if the current Slice is the last one in the result set.

```java
Slice<Book> slice = /* ... */;
if (!slice.isTail()) {
    System.out.println("Show 'next' button");
}
```

--------------------------------

### Configure Database Validation with ERROR Mode

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/configuration.md

Example of setting the database validation mode to ERROR, which throws an exception on mismatch.

```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setDatabaseValidationMode(DatabaseValidationMode.ERROR)
    .build();
```

--------------------------------

### limit and offset

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Applies LIMIT and OFFSET clauses for pagination, controlling the number of rows returned and the starting point.

```APIDOC
## limit and offset (pagination)

### Description
Add LIMIT and OFFSET clauses.

### Method
```java
public MutableRootQuery<T> limit(int limit)
public MutableRootQuery<T> offset(long offset)
```

### Parameters
#### Path Parameters
- **limit** (int) - Required - Maximum rows
- **offset** (long) - Required - Skip rows

### Request Example
```java
int pageSize = 20;
int pageNumber = 2;
long offset = (pageNumber - 1) * pageSize;

List<Book> page = sqlClient
    .createQuery(BookTable.class)
    .orderBy(book.name().asc())
    .limit(pageSize)
    .offset(offset)
    .select(book)
    .execute();
```
```

--------------------------------

### Get Fetcher String Representation

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/fetcher.md

Retrieves a string representation of the fetcher configuration. Use the multiLine parameter for a more readable output.

```java
public String toString(boolean multiLine)
```

--------------------------------

### Create SELECT Query on Entity Table

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Use `createQuery` to initiate a SELECT query on a specified entity table. This is the starting point for building complex queries.

```java
JSqlClient sqlClient = /* ... */;

// Create query
List<Book> books = sqlClient
    .createQuery(BookTable.class)
    .where(book.price().gt(10))
    .select(book)
    .execute();
```

--------------------------------

### Add Global Filters to JSqlClient

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/configuration.md

Use this to add global filters that will be applied to all queries. An example demonstrates adding a SoftDeleteFilter.

```java
class SoftDeleteFilter implements Filter<SoftDeletable> {
    @Override
    public void filter(FilterArgs<SoftDeletable> args) {
        args.where(args.getTable().logicalDeleted().eq(false));
    }
}

JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .addFilters(new SoftDeleteFilter())
    .build();
```

--------------------------------

### Creating Method Instructions via MethodVisitor

Source: https://github.com/babyfish-ct/jimmer/blob/main/project/jimmer-core/src/main/java/org/babyfish/jimmer/impl/org/objectweb/asm/tree/package.html

Demonstrates creating MethodNode instructions by using the MethodNode itself as a MethodVisitor. This allows using standard MethodVisitor methods to add instructions.

```java
MethodNode methodNode = new MethodNode(...);
methodNode.visitVarInsn(ALOAD, 0);
...
```

--------------------------------

### Creating Method Instructions with XxxInsnNode

Source: https://github.com/babyfish-ct/jimmer/blob/main/project/jimmer-core/src/main/java/org/babyfish/jimmer/impl/org/objectweb/asm/tree/package.html

Shows how to create MethodNode instructions by directly adding XxxInsnNode instances to the instructions list. This is one way to build method code from scratch.

```java
MethodNode methodNode = new MethodNode(...);
methodNode.instructions.add(new VarInsnNode(ALOAD, 0));
...
```

--------------------------------

### Get Associations Interface

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Retrieves the Associations interface for managing database associations.

```java
public Associations getAssociations(TypedProp.Association<?, ?> prop)
public Associations getAssociations(ImmutableProp immutableProp)
public Associations getAssociations(AssociationType associationType)
```

--------------------------------

### Get Filters Interface

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Access the Filters interface for global filter management.

```java
public Filters getFilters()

// Returns: `Filters` — Filter interface
```

--------------------------------

### Get Caches Interface

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Retrieve the Caches interface for managing query caches.

```java
public Caches getCaches()

// Returns: `Caches` — Cache management interface
```

--------------------------------

### Inserting Instructions at a Specific Pointer

Source: https://github.com/babyfish-ct/jimmer/blob/main/project/jimmer-core/src/main/java/org/babyfish/jimmer/impl/org/objectweb/asm/tree/package.html

Explains how to use insert() and insertBefore() methods on an InsnList to insert instructions at a saved pointer. This is useful when instructions cannot be generated sequentially.

```java
MethodNode methodNode = new MethodNode(...);
methodNode.visitVarInsn(ALOAD, 0);
AbstractInsnNode ptr = methodNode.instructions.getLast();
methodNode.visitVarInsn(ALOAD, 1);
// inserts an instruction between ALOAD 0 and ALOAD 1
methodNode.instructions.insert(ptr, new VarInsnNode(ALOAD, 0));
...
```

--------------------------------

### Get Entities Interface

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Access the Entities interface for performing entity-specific operations.

```java
public Entities getEntities()

// Returns: `Entities` — Entity operations interface
```

--------------------------------

### Get JSON Codec

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Obtain the JSON codec instance used for serialization and deserialization.

```java
public JsonCodec<?> getJsonCodec()

// Returns: `JsonCodec` — JSON codec instance
```

--------------------------------

### Get Triggers Interface

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Obtain the Triggers interface for managing database change events.

```java
public Triggers getTriggers()
public Triggers getTriggers(boolean transaction)

// Returns: `Triggers` — Trigger interface
```

--------------------------------

### Get Immutable Type Metadata

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/fetcher.md

Retrieves the Jimmer immutable type metadata for the entity associated with this fetcher.

```java
public ImmutableType getImmutableType()

```

--------------------------------

### Query Books with Fetcher

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/README.md

Demonstrates how to create a Fetcher to specify the shape of the query results, including nested author information, and then execute the query with a filter.

```java
Fetcher<Book> bookFetcher = Fetcher.create(Book.class)
    .add("id")
    .add("name")
    .add("price")
    .add("author", Fetcher.create(Author.class)
        .add("id")
        .add("name")
    );

List<Book> books = sqlClient
    .createQuery(BookTable.class)
    .where(book.price().gt(10))
    .select(bookFetcher)
    .execute();
```

--------------------------------

### Get Entity Java Class

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/fetcher.md

Retrieves the Java Class object for the entity type targeted by this fetcher.

```java
public Class<E> getJavaClass()

```

```java
Fetcher<Book> bookFetcher = Fetcher.create(Book.class);
Class<Book> bookClass = bookFetcher.getJavaClass();

```

--------------------------------

### Inserting Instructions by Iterating Over an Array

Source: https://github.com/babyfish-ct/jimmer/blob/main/project/jimmer-core/src/main/java/org/babyfish/jimmer/impl/org/objectweb/asm/tree/package.html

Shows how to insert instructions by converting the instruction list to an array and then using the insert() method of the instruction list. This approach requires careful handling of indices.

```java
AbstractInsnNode[] insns = methodNode.instructions.toArray();
for(int i = 0; i<insns.length; i++) {
    AbstractInsnNode insn = insns[i];
    if (...) {
        methodNode.instructions.insert(insn, new VarInsnNode(ALOAD, 0));
    }
}
```

--------------------------------

### Set Global ID Generator

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/configuration.md

Configures a global ID generator to be used for all entities. This example uses a SnowflakeIdGenerator.

```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setIdGenerator(new SnowflakeIdGenerator())
    .build();
```

--------------------------------

### Basic SimpleEntitySaveCommand Usage

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Demonstrates the basic usage of saving a single entity using SimpleEntitySaveCommand. It shows how to create an entity, execute the save operation, and retrieve the modified entity and affected row count.

```java
Book book = Objects.createBook(draft -> {
    draft.setId(1L);
    draft.setName("Effective Java");
    draft.setPrice(39.99);
});

SimpleSaveResult<E> result = sqlClient.saveCommand(book)
    .execute();

Book modified = result.getModifiedEntity();
int affectedRows = result.getTotalAffectedRowCount();
```

--------------------------------

### Configuration Reference

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/README.md

Reference for JSqlClient builder options in Jimmer, covering JDBC connection management, database dialect selection, batch operation settings, and more.

```APIDOC
## Configuration

### Description
JSqlClient builder options for configuring Jimmer.

### Options
- JDBC connection management
- Database dialect selection
- Batch operation settings
- SQL logging and execution
- Type and scalar handling
- JSON serialization
- ID generation strategies
- Caching and filtering
- Transaction management
- Database validation
- Query optimization
```

--------------------------------

### Apply LIMIT and OFFSET for Pagination

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Implement pagination by setting `limit` for the maximum number of rows and `offset` to skip a specified number of rows.

```java
int pageSize = 20;
int pageNumber = 2;
long offset = (pageNumber - 1) * pageSize;

List<Book> page = sqlClient
    .createQuery(BookTable.class)
    .orderBy(book.name().asc())
    .limit(pageSize)
    .offset(offset)
    .select(book)
    .execute();
```

--------------------------------

### get

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/immutable-objects.md

Retrieves the value of a property from an immutable object. This method can return the value as a generic Object or a specific typed value.

```APIDOC
## get (property value retrieval)

### Description
Retrieves the value of a property from an immutable object.

### Method
`public static Object get(Object immutable, PropId prop)`
`public static Object get(Object immutable, String prop)`
`public static Object get(Object immutable, ImmutableProp prop)`
`public static <T, X> X get(T immutable, TypedProp<T, X> prop)`

### Parameters
#### Path Parameters
- **immutable** (Object) - Yes - Jimmer immutable object instance
- **prop** (PropId, String, ImmutableProp, or TypedProp) - Yes - Property identifier

### Returns
`Object` or typed `<X>` — the property value

### Throws
- `IllegalArgumentException` — if immutable is not a Jimmer-created object or property name is invalid
- `UnloadedException` — if the property is not loaded

### Example
```java
Author author = /* loaded with name */;
String name = ImmutableObjects.get(author, "name");
// or with typed property:
String typedName = ImmutableObjects.get(author, AuthorProps.NAME);
```
```

--------------------------------

### Inserting Instructions Collected by Another MethodVisitor

Source: https://github.com/babyfish-ct/jimmer/blob/main/project/jimmer-core/src/main/java/org/babyfish/jimmer/impl/org/objectweb/asm/tree/package.html

Explains how to insert instructions by using a separate MethodNode as a MethodVisitor to collect instructions, and then inserting its instruction list into the target instruction list.

```java
AbstractInsnNode[] insns = methodNode.instructions.toArray();
for(int i = 0; i<insns.length; i++) {
    AbstractInsnNode insn = insns[i];
    if (...) {
        MethodNode toInsert = new MethodNode();
        toInsert.visitVarInsn(ALOAD, 0);
        toInsert.visitVarInsn(ALOAD, 1);
        m.instructions.insert(insn, toInsert.instructions);
    }
}
```

--------------------------------

### Execute Query with Pagination

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Use `fetchPage()` to retrieve paginated results. Specify the page size using `limit()` and the desired page number using the `pageIndex` parameter. The `fetchSlice()` method provides similar functionality.

```java
public Page<T> fetchPage(int pageIndex)
public Slice<T> fetchSlice(int pageIndex)

int pageSize = 20;
int pageNumber = 0;

Page<Book> page = sqlClient
    .createQuery(BookTable.class)
    .orderBy(book.name().asc())
    .limit(pageSize)
    .fetchPage(pageNumber);

System.out.println("Page " + (pageNumber + 1) + " of " + page.getTotalPageCount());
for (Book book : page.getRows()) {
    System.out.println(book.name());
}
```

--------------------------------

### Retrieve Property Value

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/immutable-objects.md

Use `get` to retrieve the value of a property from an immutable object. This method throws `UnloadedException` if the property is not loaded.

```java
public static Object get(Object immutable, PropId prop)
public static Object get(Object immutable, String prop)
public static Object get(Object immutable, ImmutableProp prop)
public static <T, X> X get(T immutable, TypedProp<T, X> prop)
```

```java
Author author = /* loaded with name */;
String name = ImmutableObjects.get(author, "name");
// or with typed property:
String typedName = ImmutableObjects.get(author, AuthorProps.NAME);
```

--------------------------------

### Get Field Map

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/fetcher.md

Returns an unmodifiable map of all fields configured within this fetcher, mapping field names to Field objects.

```java
public Map<String, Field> getFieldMap()

```

--------------------------------

### Complex Query with Fetchers, Filtering, Sorting, and Pagination

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Demonstrates building a complex query involving nested data fetching, multiple filtering criteria (range, equality, LIKE, any), ordering, and pagination. This is useful for retrieving detailed, filtered, and sorted lists of data.

```java
Fetcher<Book> bookFetcher = Fetcher.create(Book.class)
    .add("id")
    .add("name")
    .add("isbn")
    .add("price")
    .add("author", Fetcher.create(Author.class)
        .add("id")
        .add("name")
        .add("email")
    )
    .add("publisher", Fetcher.create(Publisher.class)
        .add("id")
        .add("name")
    )
    .add("tags", Fetcher.create(Tag.class)
        .add("id")
        .add("name")
    );

Page<Book> page = sqlClient
    .createQuery(BookTable.class)
    .where(book.price().between(10, 100))
    .where(book.published().eq(true))
    .where(
        Predicates.or(
            book.author().name().like("%Martin%"),
            book.tags().any(tag -> tag.name().eq("Popular"))
        )
    )
    .orderBy(book.price().desc(), book.name().asc())
    .limit(20)
    .fetchPage(0);

System.out.println("Total: " + page.getTotalRowCount());
System.out.println("Pages: " + page.getTotalPageCount());

for (Book book : page.getRows()) {
    System.out.println(book.name() + " by " + book.author().name());
}
```

--------------------------------

### Using MethodNode as a Buffer with ASM

Source: https://github.com/babyfish-ct/jimmer/blob/main/project/jimmer-core/src/main/java/org/babyfish/jimmer/impl/org/objectweb/asm/tree/package.html

Illustrates using a MethodNode as a buffer to transform or analyze method code before flushing it to a MethodVisitor. The transformation logic is placed within the visitEnd() method.

```java
ClassReader classReader = new ClassReader(source);
ClassWriter classWriter = new ClassWriter(0);
ClassVisitor classVisitor = new ClassVisitor(ASM7, classWriter) {
    public MethodVisitor visitMethod(int access, String name, String desc, String signature, String[] exceptions) {
      final MethodVisitor methodVisitor = 
          super.visitMethod(access, name, desc, signature, exceptions);
      MethodNode methodNode = new MethodNode(access, name, desc, signature, exceptions) {
        public void visitEnd() {
          // transform or analyze method code using tree API
          accept(methodVisitor);
        }
      };
      return methodNode;
    }
};
classReader.accept(classVisitor, 0);
```

--------------------------------

### fetchOne()

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Executes a query and expects exactly one result. Throws exceptions if zero or more than one result is found.

```APIDOC
## fetchOne()

### Description
Executes a query expecting exactly one result.

### Method
`fetchOne()`

### Returns
`T` — The single result

### Throws
- `EmptyResultException` — No results found
- `TooManyResultsException` — Multiple results found

### Example
```java
Book book = sqlClient
    .createQuery(BookTable.class)
    .where(book.id().eq(1L))
    .select(book)
    .fetchOne();
```
```

--------------------------------

### Create JSqlClient Builder

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Use this static method to obtain a builder for configuring and constructing a JSqlClient instance.

```java
public static Builder newBuilder()
```

```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setDialect(new MySqlDialect())
    .build();
```

--------------------------------

### Create Basic SELECT Query

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Construct a SELECT query on a specified table. This is useful for retrieving data based on certain criteria.

```java
public <T extends TableProxy<?>> MutableRootQuery<T> createQuery(T table)
public <T extends BaseTable> MutableRootQuery<T> createQuery(T baseTable)
```

```java
List<Book> books = sqlClient
    .createQuery(BookTable.class)
    .where(book.price().gt(10))
    .select(book)
    .execute();
```

--------------------------------

### JSqlClient Builder Configuration

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Provides configuration options for building a JSqlClient instance using the builder pattern. This includes setting up connection managers, dialects, caching, filters, and more.

```APIDOC
## Builder Configuration

The JSqlClient.Builder interface provides extensive configuration options:

| Configuration | Method |
|---------------|--------|
| Connection | `setConnectionManager` |
| Slave reads | `setSlaveConnectionManager` |
| SQL dialect | `setDialect` |
| Batch size | `setDefaultBatchSize` |
| Caching | `setCaches` |
| Filters | `addFilters` |
| ID generation | `setIdGenerator` |
| Transactions | `setMutationTransactionRequired` |
| Triggers | `setTriggerType` |
| Validation | `setDatabaseValidationMode` |

### Example Builder Usage
```java
JSqlClient sqlClient = JSqlClient.newBuilder()
    .setConnectionManager(connectionManager)
    .setDialect(new MySqlDialect())
    .setDefaultBatchSize(100)
    .setCaches(cache -> {
        cache.add(Book.class);
        cache.add(Author.class);
    })
    .addFilters(new SoftDeleteFilter())
    .setTriggerType(TriggerType.TRANSACTION_ONLY)
    .setDefaultBinLogJsonCodec(jsonCodec)
    .build();
```
```

--------------------------------

### Entities Interface Definition

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/types.md

Provides methods for finding and modifying entities, including finding by ID, finding all entities, and finding by example. It implements SaveOperations.

```java
public interface Entities extends SaveOperations
```

--------------------------------

### Paginate Book Results

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/README.md

Shows how to fetch paginated results for books, including filtering by published status, ordering by name, and limiting the page size. It also prints pagination details.

```java
Page<Book> page = sqlClient
    .createQuery(BookTable.class)
    .where(book.published().eq(true))
    .orderBy(book.name().asc())
    .limit(20)
    .fetchPage(0);

System.out.println("Total: " + page.getTotalRowCount());
System.out.println("Page 1 of " + page.getTotalPageCount());
```

--------------------------------

### Output DTO with Nested Objects

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/annotations.md

Example of an output DTO definition that includes nested objects for associated entities, providing a structured view of data.

```java
@Description("Book display")
public interface BookDisplay {
    long id();
    
    String name();
    
    BigDecimal price();
    
    @Description("Author details")
    AuthorSummary author();
    
    List<TagDTO> tags();
}
```

--------------------------------

### saveCommand / saveEntitiesCommand

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Creates save command objects for advanced configuration before execution. Allows for fine-grained control over save operations.

```APIDOC
## saveCommand / saveEntitiesCommand

### Description
Create save command objects for advanced configuration before execution.

### Method
`saveCommand(E entity)`
`saveEntitiesCommand(Iterable<E> entities)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Description |
|---|---|---|---|
| entity | E | Yes | The entity for which to create a save command |
| entities | Iterable<E> | Yes | Collection of entities for which to create save commands |

### Returns
`SimpleEntitySaveCommand<E>` or `BatchEntitySaveCommand<E>`

### Request Example
```java
SimpleEntitySaveCommand<Book> cmd = sqlClient.saveCommand(book)
    .setMode(SaveMode.INSERT_ONLY);
SimpleSaveResult<Book> result = cmd.execute();
```
```

--------------------------------

### Fluent API Design - Immutability

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/fetcher.md

Illustrates the immutable nature of the Fetcher API, where each method returns a new instance. This enables safe composition and reuse of fetcher configurations.

```java
// Base fetcher with common fields
Fetcher<Book> baseFetcher = Fetcher.create(Book.class)
    .add("id")
    .add("name");

// Extended versions for different use cases
Fetcher<Book> detailedFetcher = baseFetcher
    .add("price")
    .add("author", authorFetcher);

Fetcher<Book> summaryFetcher = baseFetcher
    .add("isbn");

// Both can be used independently
```

--------------------------------

### Entities API

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/README.md

Entity finder methods in Jimmer for retrieving entities by ID, querying by example, and finding all entities with sorting and filtering, optimized for cache efficiency.

```APIDOC
## Entities

### Description
Entity finder methods for retrieving entities. Supports single and batch retrieval by ID, query by example, and finding all entities with sorting and filtering, bypassing global filters for cache efficiency.

### Endpoint
N/A (SDK/Library API)

### Methods
- Single and batch entity retrieval by id
- Query by example
- Find all, sorted, filtered
- Bypasses global filters for cache efficiency
```

--------------------------------

### Advanced Field Configuration

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/fetcher.md

Shows how to use the loaderBlock parameter for advanced configuration when adding associations. This allows setting recursion depth and field-level filters.

```java
Fetcher<Book> fetcher = Fetcher.create(Book.class)
    .add("authors", authorFetcher, config -> {
        config.depth(5);           // for recursion
        config.filter(/* ... */);  // field-level filters
    });
```

--------------------------------

### Get Delete Operation Results

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Retrieves statistics from a delete operation, including the total number of deleted rows and row counts per affected table.

```java
DeleteResult result = sqlClient.deleteCommand(Book.class, 1L).execute();

int deleted = result.getDeletedRowCount();
System.out.println("Deleted " + deleted + " row(s)");
```

--------------------------------

### Get Batch Save Result Details

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Retrieves details from a batch entity save operation, including all modified entities and the total number of affected rows.

```java
BatchSaveResult<Book> result = sqlClient.save(books);

List<Book> modified = result.getModifiedEntities();
for (Book book : modified) {
    System.out.println("Saved book: " + book.id());
}

System.out.println("Total: " + result.getTotalAffectedRowCount());
```

--------------------------------

### Jimmer Annotation Processor (KSP)

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/annotations.md

The KSP version of the Jimmer Annotation Processor for Kotlin projects. Use this instead of APT for Kotlin.

```kotlin
project/jimmer-ksp/src/main/kotlin/org/babyfish/jimmer/ksp/JimmerProcessor.kt
```

--------------------------------

### Create Save Commands

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/jsql-client.md

Generate command objects for advanced save operations, allowing for pre-execution configuration.

```java
public <E> SimpleEntitySaveCommand<E> saveCommand(E entity)
public <E> BatchEntitySaveCommand<E> saveEntitiesCommand(Iterable<E> entities)
```

```java
SimpleEntitySaveCommand<Book> cmd = sqlClient.saveCommand(book)
    .setMode(SaveMode.INSERT_ONLY);
SimpleSaveResult<Book> result = cmd.execute();
```

--------------------------------

### execute()

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Executes a query and returns a list of all matching results. If no results are found, an empty list is returned.

```APIDOC
## execute()

### Description
Executes a query and returns a list of results.

### Method
`execute()`

### Returns
`List<T>` — Query results (empty if none match)

### Example
```java
List<Book> books = sqlClient
    .createQuery(BookTable.class)
    .where(book.price().gt(20))
    .select(book)
    .execute();
```
```

--------------------------------

### Get Save Result Details

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/save-operations.md

Retrieves details from a single entity save operation, including the original and modified entity states, and row counts per table.

```java
SimpleSaveResult<Book> result = sqlClient.save(book);

// Check affected rows
int totalRows = result.getTotalAffectedRowCount();
for (Map.Entry<AffectedTable, Integer> entry : 
     result.getAffectedRowCountByTable().entrySet()) {
    System.out.println(entry.getKey() + ": " + entry.getValue() + " rows");
}

// Get modified entity (id may have been generated)
Book modified = result.getModifiedEntity();
Long generatedId = modified.id();
```

--------------------------------

### fetchPage() and fetchSlice()

Source: https://github.com/babyfish-ct/jimmer/blob/main/_autodocs/api-reference/queries.md

Executes a query with pagination support, returning either a Page or Slice object based on the specified page index.

```APIDOC
## fetchPage() and fetchSlice()

### Description
Executes a query with pagination.

### Method
`fetchPage(int pageIndex)`
`fetchSlice(int pageIndex)`

### Parameters
#### Path Parameters
- **pageIndex** (int) - Required - Page number (0-based)

### Returns
`Page<T>` or `Slice<T>` — Paginated result

### Note
Use with `limit()` to set page size.

### Example
```java
int pageSize = 20;
int pageNumber = 0;

Page<Book> page = sqlClient
    .createQuery(BookTable.class)
    .orderBy(book.name().asc())
    .limit(pageSize)
    .fetchPage(pageNumber);

System.out.println("Page " + (pageNumber + 1) + " of " + page.getTotalPageCount());
for (Book book : page.getRows()) {
    System.out.println(book.name());
}
```
```