knkd

Андрей Светлов
Если совсем просто — то он добавит объект в сессию.
Если при этом по primary key в базе уже есть объект — вернется поднятый из базы.

Это по факту всего лишь более короткий способ сделать вот так?

user = session.query(User).filter_by(name=starter).first()
if user == None:
    user = User(session, starter)
    user.add()

По факту нужно быстро спросить, есть ли User и коль нет — добавить. merge с этим справляется.
Делать сложные операции с пользователем, затрагивающие коллекции — не нужно. Эти операции будут выброшены.

В начале работы делаете .merge и затем творите что хотите.