class lamindb.Session#

Bases: object

Database session.

FAQ: Loading relationships: Session

It offers .select, .add and .delete attached to an open session, which is needed for lazy loading of relationships.

The session object should be closed when it’s not longer needed and typically used within a with statement:

with Session() as ss:
    file =, name="My test").one()


add(record, **fields)#

Insert or update data records.

Inserts a new record if the corresponding row doesn’t exist. Updates the corresponding row with the record if it exists.

To update a row, query it with .select and modify it before passing it to add.


record – One or multiple records as instances of SQLModel.

Return type:

Union[SQLModel, List[SQLModel]]


The record as returned from the database with a created_at timestamp.


Add a record (errors if already exists):

>>> ln.add(ln.Transform(name="My pipeline"))
Transform(id="0Cb86EZj", name="My pipeline", ...)

Update an existing record:

>>> transform =, id="0Cb86EZj").one()
>>> = "New name"
>>> ln.add(transform)
Transform(id="0Cb86EZj", name="New name", ...)

Add a record with passed fields if not yet exists:

>>> # add a record if the metadata combination is not already exist in the DB
>>> # if exists, returns the existing record from the DB
>>> ln.add(ln.Transform, name="My transform", v="1")
Transform(id="0Cb86EZj", name="My pipeline", ...)
>>> # is equivalent to the following:
>>> transform =, name="My transform", v="1").one_or_none()
>>> if transform is None:
>>>     ln.add(transform)

Close the session.

select(*entity, **fields)#

Query data.

Guide: Query & lookup data.

  • entity – Table, tables, or tables including column specification.

  • fields – Fields and values passed as keyword arguments.

Return type:



A SelectStmt object.