Runtime Inspection API — SQLAlchemy 2.0 Documentation

Release: 2.0.48 | Release Date: March 2, 2026

# SQLAlchemy 2.0 Documentation

# Runtime Inspection API

The inspection module provides the `inspect()` function, which delivers runtime information about a wide variety of SQLAlchemy objects, both within the Core as well as the ORM.

The `inspect()` function is the entry point to SQLAlchemy’s public API for viewing the configuration and construction of in-memory objects. Depending on the type of object passed to `inspect()`, the return value will either be a related object which provides a known interface, or in many cases it will return the object itself.

The rationale for `inspect()` is twofold. One is that it replaces the need to be aware of a large variety of “information getting” functions in SQLAlchemy, such as `Inspector.from_engine()` (deprecated in 1.4), `instance_state()`, `class_mapper()`, and others. The other is that the return value of `inspect()` is guaranteed to obey a documented API, thus allowing third party tools which build on top of SQLAlchemy configurations to be constructed in a forwards-compatible way.

Object Name | Description
--- | ---
inspect(subject[, raiseerr]) | Produce an inspection object for the given target.

function sqlalchemy.inspect(subject: Any, raiseerr: bool = True) → Any

  Produce an inspection object for the given target.

  The returned value in some cases may be the same object as the one given, such as if a `Mapper` object is passed. In other cases, it will be an instance of the registered inspection type for the given object, such as if an `Engine` is passed, an `Inspector` object is returned.

  Parameters:

    - subject – the subject to be inspected.

    - raiseerr – When `True`, if the given subject does not correspond to a known SQLAlchemy inspected type, `sqlalchemy.exc.NoInspectionAvailable` is raised. If `False`, `None` is returned.

## Available Inspection Targets

Below is a listing of many of the most common inspection targets.

- `Connectable` (i.e. `Engine`, `Connection`) - returns an `Inspector` object.

- `ClauseElement` - all SQL expression components, including `Table`, `Column`, serve as their own inspection objects, meaning any of these objects passed to `inspect()` return themselves.

- `object` - an object given will be checked by the ORM for a mapping - if so, an `InstanceState` is returned representing the mapped state of the object. The `InstanceState` also provides access to per attribute state via the `AttributeState` interface as well as the per-flush “history” of any attribute via the `History` object.

  See also

  Inspection of Mapped Instances

- `type` (i.e. a class) - a class given will be checked by the ORM for a mapping - if so, a `Mapper` for that class is returned.

  See also

  Inspection of Mapper objects

- mapped attribute - passing a mapped attribute to `inspect()`, such as `inspect(MyClass.some_attribute)`, returns a `QueryableAttribute` object, which is the descriptor associated with a mapped class. This descriptor refers to a `MapperProperty`, which is usually an instance of `ColumnProperty` or `RelationshipProperty`, via its `QueryableAttribute.property` attribute.

- `AliasedClass` - returns an `AliasedInsp` object.