Return an instance based on the given primary key identifier, or ``None`` if not found. E.g.:: my_user = session.query(User).get(5) some_object = session.query(VersionedFoo).get((5, 10)) some_object = session.query(VersionedFoo).get({"id": 5, "
(self, ident: _PKIdentityArgument)
| 1044 | alternative="The method is now available as :meth:`_orm.Session.get`", |
| 1045 | ) |
| 1046 | def get(self, ident: _PKIdentityArgument) -> Optional[_T]: |
| 1047 | """Return an instance based on the given primary key identifier, |
| 1048 | or ``None`` if not found. |
| 1049 | |
| 1050 | E.g.:: |
| 1051 | |
| 1052 | my_user = session.query(User).get(5) |
| 1053 | |
| 1054 | some_object = session.query(VersionedFoo).get((5, 10)) |
| 1055 | |
| 1056 | some_object = session.query(VersionedFoo).get({"id": 5, "version_id": 10}) |
| 1057 | |
| 1058 | :meth:`_query.Query.get` is special in that it provides direct |
| 1059 | access to the identity map of the owning :class:`.Session`. |
| 1060 | If the given primary key identifier is present |
| 1061 | in the local identity map, the object is returned |
| 1062 | directly from this collection and no SQL is emitted, |
| 1063 | unless the object has been marked fully expired. |
| 1064 | If not present, |
| 1065 | a SELECT is performed in order to locate the object. |
| 1066 | |
| 1067 | :meth:`_query.Query.get` also will perform a check if |
| 1068 | the object is present in the identity map and |
| 1069 | marked as expired - a SELECT |
| 1070 | is emitted to refresh the object as well as to |
| 1071 | ensure that the row is still present. |
| 1072 | If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. |
| 1073 | |
| 1074 | :meth:`_query.Query.get` is only used to return a single |
| 1075 | mapped instance, not multiple instances or |
| 1076 | individual column constructs, and strictly |
| 1077 | on a single primary key value. The originating |
| 1078 | :class:`_query.Query` must be constructed in this way, |
| 1079 | i.e. against a single mapped entity, |
| 1080 | with no additional filtering criterion. Loading |
| 1081 | options via :meth:`_query.Query.options` may be applied |
| 1082 | however, and will be used if the object is not |
| 1083 | yet locally present. |
| 1084 | |
| 1085 | :param ident: A scalar, tuple, or dictionary representing the |
| 1086 | primary key. For a composite (e.g. multiple column) primary key, |
| 1087 | a tuple or dictionary should be passed. |
| 1088 | |
| 1089 | For a single-column primary key, the scalar calling form is typically |
| 1090 | the most expedient. If the primary key of a row is the value "5", |
| 1091 | the call looks like:: |
| 1092 | |
| 1093 | my_object = query.get(5) |
| 1094 | |
| 1095 | The tuple form contains primary key values typically in |
| 1096 | the order in which they correspond to the mapped |
| 1097 | :class:`_schema.Table` |
| 1098 | object's primary key columns, or if the |
| 1099 | :paramref:`_orm.Mapper.primary_key` configuration parameter were |
| 1100 | used, in |
| 1101 | the order used for that parameter. For example, if the primary key |
| 1102 | of a row is represented by the integer |
| 1103 | digits "5, 10" the call would look like:: |