This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne.git
The following commit(s) were added to refs/heads/master by this push:
new c20e55ede CAY-3007 Deprecate SelectById
c20e55ede is described below
commit c20e55ededfb7f776454202a18bb60c650d0f66e
Author: Andrus Adamchik <[email protected]>
AuthorDate: Sun Aug 30 16:57:40 2026 -0400
CAY-3007 Deprecate SelectById
docs...
---
.../_cayenne-guide/part2/objectContext.adoc | 2 +-
.../asciidoc/_cayenne-guide/part2/queries.adoc | 2 +-
.../_cayenne-guide/part2/queries/selectbyid.adoc | 59 +++++++++++++++++++---
3 files changed, 55 insertions(+), 8 deletions(-)
diff --git
a/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
b/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
index 4fec460a0..d12a3fc8b 100644
---
a/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
+++
b/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
@@ -184,7 +184,7 @@ It also provides the reverse operation - finding an object
given a known PK:
Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);
----
-For more flexibility, you could use the <<SelectById>> query instead.
+For more flexibility, you could <<selectbyid,select by ID>> with
`ObjectSelect` instead.
Feel free to explore the `Cayenne` class API for other useful methods.
diff --git
a/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
b/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
index f9978346a..6d5f7f53f 100644
--- a/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
+++ b/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
@@ -26,7 +26,7 @@ Users can define their own query types to abstract certain DB
interactions
that for whatever reason can not be adequately described by the built-in set.
Queries can be roughly categorized as "object" and "native".
-Object queries (most notably `ObjectSelect`, `SelectById`, and `EJBQLQuery`)
+Object queries (most notably `ObjectSelect` and `EJBQLQuery`)
are built with abstractions originating in the object model (the "object" side
in the "object-relational" divide).
E.g. `ObjectSelect` consists of a Java class of objects to fetch, a qualifier
expression, orderings, etc. - all of this
expressed in terms of the object model.
diff --git
a/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries/selectbyid.adoc
b/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries/selectbyid.adoc
index 95af72515..38db5f75c 100644
---
a/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries/selectbyid.adoc
+++
b/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries/selectbyid.adoc
@@ -12,17 +12,64 @@
// the specific language governing permissions and limitations under the
// License.
-==== SelectById
+[[selectbyid]]
+==== Selecting by ID
-This query allows to search objects by their ID.
-It's introduced in Cayenne 4.0 and uses new "fluent" API same as
`ObjectSelect` query.
-
-Here is example of how to use it:
+Every generated entity class has a `SELF` property that stands for the object
itself. Used as a qualifier
+it matches on the entity's primary key:
[source, java]
----
-Artist artistWithId1 = SelectById.query(Artist.class, 1)
+Artist artistWithId1 = ObjectSelect.query(Artist.class)
+ .where(Artist.SELF.eqId(1))
.prefetch(Artist.PAINTING_ARRAY.joint())
.localCache()
.selectOne(context);
----
+
+Being an ordinary qualifier, it combines with everything else `ObjectSelect`
offers - prefetching, caching,
+ordering, pagination and further conditions.
+
+To match any of a set of IDs:
+
+[source, java]
+----
+List<Artist> artists = ObjectSelect.query(Artist.class)
+ .where(Artist.SELF.idsIn(1, 2, 3))
+ .select(context);
+----
+
+An `ObjectId` can be used in place of a plain value:
+
+[source, java]
+----
+Artist artist = ObjectSelect.query(Artist.class)
+ .where(Artist.SELF.eqId(objectId))
+ .selectOne(context);
+----
+
+Entities with a compound primary key are matched by a map of DB attribute
names to values:
+
+[source, java]
+----
+Map<String, Object> id = Map.of("KEY1", "x", "KEY2", "y");
+
+CompoundPk object = ObjectSelect.query(CompoundPk.class)
+ .where(CompoundPk.SELF.eqIdMap(id))
+ .selectOne(context);
+----
+
+To match several of them, use `idMapsIn(..)`, or `objectIdsIn(..)` for a set
of `ObjectId`s.
+
+The same "id" methods are available on to-one relationship properties,
matching related objects by their ID
+without fetching them first:
+
+[source, java]
+----
+List<Painting> paintings = ObjectSelect.query(Painting.class)
+ .where(Painting.TO_ARTIST.eqId(1))
+ .select(context);
+----
+
+To fetch a single object by a known PK, `Cayenne.objectForPK(..)` is often
shorter still - see
+<<persistent-objects-objectcontext,the ObjectContext chapter>>.
