Cascade Select

This article will guide you on how to use the cascade query feature of Kronos.

Partially enable and disable cascade queries

Disable cascading queries

Kronos enables the cascading query function by default and needs to be explicitly disabled in the select function:

KPojo.select().cascade(enabled = false).toList()

Partially enable cascading queries

When there are multiple cascade declarations in KPojo, but only some of them need cascade query, you can pass the attributes that need cascade query into the cascade function, and the remaining attributes and sub-attributes will not trigger cascade query.

// If only property1 and property2 in KPojo need to be cascade queried:
KPojo.select().cascade { [KPojo::property1, KPojo::property2] }.toList()

You can limit the cascade query of its sub-attributes as follows:

KPojo.select()
    .cascade {
        [
            KPojo::property1,
            KPojo::property2,
            Property1::subProperty1,
            Property1::subProperty2
        ]
    }
    .toList()

@Ignore Declare a field skipped by cascade select

When defining the KPojo class, use @Ignore([IgnoreAction.CASCADE_SELECT]) on a relationship property to skip that property during cascade select.

@Table("company")
data class Company(
    @PrimaryKey
    var id: Int? = null,
    var employees: List<Employee> = listOf()
) : KPojo

@Table("employee")
data class Employee(
    var id: Int? = null,
    var companyId: Int? = null,
    @Ignore([IgnoreAction.CASCADE_SELECT])
    @Cascade(["companyId"], ["id"])
    var company: Company? = null
) : KPojo

Employee().select().toList()

The Employee rows are returned.
The company property is not loaded by cascade select for this query.

For all IgnoreAction values, see 📚annotation configuration - @Ignore Ignore Fields.

Cascading queries

After the cascade relationship is defined, use:

1. 📚toList: query the specified type list
2. 📚first: query a single record
3. 📚firstOrNull: query a single record (optional)

When you use the above three methods to query data, we will automatically perform logical queries for you based on the cascade relationship. For details, see: 📚cascade relationship definition.

Cascade query does not limit the level and direction of cascade relationship by default. If your cascade relationship is very deep, please pay attention to 📚turn off cascade query when querying, or only 📚partially turn on cascade query to ensure that you will not query data you don't need.

Q: How to handle circular references in cascading relationships in Kronos? Will there be an infinite query loop?

A: Kronos handles circular references. The properties of each KPojo class will only be queried once at different levels. When a duplicate reference is encountered, the query will stop automatically to avoid infinite loop queries.

A-->B;
B-->C;
C-->A;
A-->B; // This query will not be triggered again

Here is an example:

erDiagram
A {
    int bId
    B b
    List[C] listOfC
}
B {
    int cId
    C c
    List[A] listOfA
}
C {
    int aId
    A a
    List[B] listOfB
}
A ||--o{ B : "cascade"
B ||--o{ C : "cascade"
C ||--o{ A : "cascade"

If we query a certain A entity at this time, the complete structure of the query will be: (tree diagram representation)

A1
├── bId: <bId of A1>
├── b
│ ├── cId: <cId of B1>
│ ├── c
│ │ ├── aId: <aId of C1>
│ │ └── listOfB
│ │ ├── B2
│ │ ├── B3
│ │ └── ...
│ └── listOfA
│ ├── A2
│ ├── A3
│ └── ...
└── listOfC
├── C1
├── C2
└── ...