~ubuntu-branches/debian/jessie/sqlalchemy/jessie : revision 35

20

21

var DOCUMENTATION_OPTIONS = {

22

URL_ROOT: '../',

23

VERSION: '0.8.2',

23

VERSION: '0.8.3',

24

COLLAPSE_MODINDEX: false,

25

FILE_SUFFIX: '.html'

26

};

67

</div>

68

69

70

Release: 0.8.2 | Release Date: July 3, 2013

70

Release: 0.8.3 | Release Date: October 26, 2013

71

72

73

</div>

148

<li><a class="reference internal" href="#mapping-a-class-against-arbitrary-selects">Mapping a Class against Arbitrary Selects</a></li>

149

<li><a class="reference internal" href="#multiple-mappers-for-one-class">Multiple Mappers for One Class</a></li>

150

<li><a class="reference internal" href="#constructors-and-object-initialization">Constructors and Object Initialization</a></li>

151

<li><a class="reference internal" href="#configuring-a-version-counter">Configuring a Version Counter</a><ul>

152

<li><a class="reference internal" href="#simple-version-counting">Simple Version Counting</a></li>

153

<li><a class="reference internal" href="#custom-version-counters-types">Custom Version Counters / Types</a></li>

154

</ul>

155

</li>

151

156

<li><a class="reference internal" href="#class-mapping-api">Class Mapping API</a></li>

152

157

</ul>

153

158

</li>

195

200

fullname = Column(String)

196

201

password = Column(String)</pre></div>

197

202

</div>

198

In “classical” form, the table metadata is created separately with the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

203

In “classical” form, the table metadata is created separately with the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

199

204

construct, then associated with the <tt class="docutils literal">User</tt> class via the <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a> function:

200

205

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy import Table, MetaData, Column, ForeignKey, Integer, String

201

206

from sqlalchemy.orm import mapper

218

223

mapper(User, user)</pre></div>

219

224

</div>

220

225

Information about mapped attributes, such as relationships to other classes, are provided

221

via the <tt class="docutils literal">properties</tt> dictionary. The example below illustrates a second <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

226

via the <tt class="docutils literal">properties</tt> dictionary. The example below illustrates a second <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

222

227

object, mapped to a class called <tt class="docutils literal">Address</tt>, then linked to <tt class="docutils literal">User</tt> via <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a>:

223

228

<div class="highlight-python"><div class="highlight"><pre>address = Table('address', metadata,

224

229

Column('id', Integer, primary_key=True),

234

239

</div>

235

240

When using classical mappings, classes must be provided directly without the benefit

236

241

of the “string lookup” system provided by Declarative. SQL expressions are typically

237

specified in terms of the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects, i.e. <tt class="docutils literal">address.c.id</tt> above

242

specified in terms of the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects, i.e. <tt class="docutils literal">address.c.id</tt> above

238

243

for the <tt class="docutils literal">Address</tt> relationship, and not <tt class="docutils literal">Address.id</tt>, as <tt class="docutils literal">Address</tt> may not

239

244

yet be linked to table metadata, nor can we specify a string here.

240

245

Some examples in the documentation still use the classical approach, but note that

241

246

the classical as well as Declarative approaches are fully interchangeable. Both

242

systems ultimately create the same configuration, consisting of a <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>,

247

systems ultimately create the same configuration, consisting of a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>,

243

248

user-defined class, linked together with a <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a>. When we talk about

244

249

“the behavior of <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a>”, this includes when using the Declarative system

245

250

as well - it’s still used, just behind the scenes.

247

252

248

253

<h2>Customizing Column Properties<a class="headerlink" href="#customizing-column-properties" title="Permalink to this headline">¶</a></h2>

249

254

The default behavior of <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a> is to assemble all the columns in

250

the mapped <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> into mapped object attributes, each of which are

255

the mapped <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> into mapped object attributes, each of which are

251

256

named according to the name of the column itself (specifically, the <tt class="docutils literal">key</tt>

252

attribute of <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>). This behavior can be

257

attribute of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>). This behavior can be

253

258

modified in several ways.

254

259

255

<h3>Naming Columns Distinctly from Attribute Names<a class="headerlink" href="#naming-columns-distinctly-from-attribute-names" title="Permalink to this headline">¶</a></h3>

260

<h3>Naming Columns Distinctly from Attribute Names<a class="headerlink" href="#naming-columns-distinctly-from-attribute-names" title="Permalink to this headline">¶</a></h3>

256

261

A mapping by default shares the same name for a

257

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> as that of the mapped attribute.

258

The name assigned to the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> can be different,

262

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> as that of the mapped attribute.

263

The name assigned to the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> can be different,

259

264

as we illustrate here in a Declarative mapping:

260

265

<div class="highlight-python"><div class="highlight"><pre>class User(Base):

261

266

__tablename__ = 'user'

264

269

</div>

265

270

Where above <tt class="docutils literal">User.id</tt> resolves to a column named <tt class="docutils literal">user_id</tt>

266

271

and <tt class="docutils literal">User.name</tt> resolves to a column named <tt class="docutils literal">user_name</tt>.

267

When mapping to an existing table, the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> object

272

When mapping to an existing table, the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> object

268

273

can be referenced directly:

269

274

<div class="highlight-python"><div class="highlight"><pre>class User(Base):

270

275

__table__ = user_table

296

301

</div>

297

302

298

303

<h3>Using column_property for column level options<a class="headerlink" href="#using-column-property-for-column-level-options" title="Permalink to this headline">¶</a></h3>

299

Options can be specified when mapping a <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> using the

304

Options can be specified when mapping a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> using the

300

305

<a class="reference internal" href="#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal">column_property()</tt></a> function. This function

301

306

explicitly creates the <a class="reference internal" href="internals.html#sqlalchemy.orm.properties.ColumnProperty" title="sqlalchemy.orm.properties.ColumnProperty"><tt class="xref py py-class docutils literal">ColumnProperty</tt></a> used by the

302

<a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a> to keep track of the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>; normally, the

307

<a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a> to keep track of the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>; normally, the

303

308

<a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a> creates this automatically. Using <a class="reference internal" href="#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal">column_property()</tt></a>,

304

we can pass additional arguments about how we’d like the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

309

we can pass additional arguments about how we’d like the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

305

310

to be mapped. Below, we pass an option <tt class="docutils literal">active_history</tt>,

306

311

which specifies that a change to this column’s value should

307

312

result in the former value being loaded first:

314

319

name = column_property(Column(String(50)), active_history=True)</pre></div>

315

320

</div>

316

321

<a class="reference internal" href="#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal">column_property()</tt></a> is also used to map a single attribute to

317

multiple columns. This use case arises when mapping to a <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.join" title="sqlalchemy.sql.expression.join"><tt class="xref py py-func docutils literal">join()</tt></a>

322

multiple columns. This use case arises when mapping to a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.join" title="sqlalchemy.sql.expression.join"><tt class="xref py py-func docutils literal">join()</tt></a>

318

323

which has attributes which are equated to each other:

319

324

<div class="highlight-python"><div class="highlight"><pre>class User(Base):

320

325

__table__ = user.join(address)

341

346

<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">column_property</tt><big>(</big>*cols, **kw<big>)</big><a class="headerlink" href="#sqlalchemy.orm.column_property" title="Permalink to this definition">¶</a></dt>

342

347

<dd>Provide a column-level property for use with a Mapper.

343

348

Column-based properties can normally be applied to the mapper’s

344

<tt class="docutils literal">properties</tt> dictionary using the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> element directly.

349

<tt class="docutils literal">properties</tt> dictionary using the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> element directly.

345

350

Use this function when the given column is not directly present within the

346

351

mapper’s selectable; examples include SQL expressions, functions, and

347

352

scalar SELECT queries.

362

367

<a class="reference internal" href="session.html#sqlalchemy.orm.attributes.get_history" title="sqlalchemy.orm.attributes.get_history"><tt class="xref py py-func docutils literal">attributes.get_history()</tt></a> or <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.is_modified" title="sqlalchemy.orm.session.Session.is_modified"><tt class="xref py py-meth docutils literal">Session.is_modified()</tt></a>

363

368

which also need to know

364

369

the “previous” value of the attribute.

365

366

New in version 0.6.6.

370

371

New in version 0.6.6.

372

</div>

367

373

</li>

368

374

<li>comparator_factory – a class which extends

369

375

<a class="reference internal" href="internals.html#sqlalchemy.orm.properties.ColumnProperty.Comparator" title="sqlalchemy.orm.properties.ColumnProperty.Comparator"><tt class="xref py py-class docutils literal">ColumnProperty.Comparator</tt></a> which provides custom SQL clause

387

393

Note however that the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> with default expiration

388

394

settings still expires

389

395

all attributes after a <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-meth docutils literal">Session.commit()</tt></a> call, however.

390

391

New in version 0.7.3.

396

397

New in version 0.7.3.

398

</div>

392

399

</li>

393

400

<li>info – Optional data dictionary which will be populated into the

394

401

<a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.MapperProperty.info" title="sqlalchemy.orm.interfaces.MapperProperty.info"><tt class="xref py py-attr docutils literal">MapperProperty.info</tt></a> attribute of this object.

395

396

New in version 0.8.

402

403

New in version 0.8.

404

</div>

397

405

</li>

398

406

<li>extension – an

399

407

<a class="reference internal" href="deprecated.html#sqlalchemy.orm.interfaces.AttributeExtension" title="sqlalchemy.orm.interfaces.AttributeExtension"><tt class="xref py py-class docutils literal">AttributeExtension</tt></a>

411

419

</div>

412

420

413

421

<h3>Mapping a Subset of Table Columns<a class="headerlink" href="#mapping-a-subset-of-table-columns" title="Permalink to this headline">¶</a></h3>

414

Sometimes, a <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> object was made available using the

415

reflection process described at <a class="reference internal" href="../core/schema.html#metadata-reflection">Reflecting Database Objects</a> to load

422

Sometimes, a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> object was made available using the

423

reflection process described at metadata_reflection to load

416

424

the table’s structure from the database.

417

425

For such a table that has lots of columns that don’t need to be referenced

418

426

in the application, the <tt class="docutils literal">include_properties</tt> or <tt class="docutils literal">exclude_properties</tt>

443

451

In some cases, multiple columns may have the same name, such as when

444

452

mapping to a join of two or more tables that share some column name.

445

453

<tt class="docutils literal">include_properties</tt> and <tt class="docutils literal">exclude_properties</tt> can also accommodate

446

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects to more accurately describe which columns

454

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects to more accurately describe which columns

447

455

should be included or excluded:

448

456

<div class="highlight-python"><div class="highlight"><pre>class UserAddress(Base):

449

457

__table__ = user_table.join(addresses_table)

455

463

456

464

Note

457

465

insert and update defaults configured on individual

458

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects, i.e. those described at <a class="reference internal" href="../core/schema.html#metadata-defaults">Column Insert/Update Defaults</a>

466

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects, i.e. those described at metadata_defaults

459

467

including those configured by the <tt class="docutils literal">default</tt>, <tt class="docutils literal">update</tt>,

460

468

<tt class="docutils literal">server_default</tt> and <tt class="docutils literal">server_onupdate</tt> arguments, will continue to

461

function normally even if those <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects are not mapped.

469

function normally even if those <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects are not mapped.

462

470

This is because in the case of <tt class="docutils literal">default</tt> and <tt class="docutils literal">update</tt>, the

463

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> object is still present on the underlying

464

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, thus allowing the default functions to take place when

471

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> object is still present on the underlying

472

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, thus allowing the default functions to take place when

465

473

the ORM emits an INSERT or UPDATE, and in the case of <tt class="docutils literal">server_default</tt>

466

474

and <tt class="docutils literal">server_onupdate</tt>, the relational database itself maintains these

467

475

functions.

492

500

photo = deferred(Column(Binary))</pre></div>

493

501

</div>

494

502

Classical mappings as always place the usage of <a class="reference internal" href="#sqlalchemy.orm.deferred" title="sqlalchemy.orm.deferred"><tt class="xref py py-func docutils literal">orm.deferred()</tt></a> in the

495

<tt class="docutils literal">properties</tt> dictionary against the table-bound <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>:

503

<tt class="docutils literal">properties</tt> dictionary against the table-bound <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>:

496

504

<div class="highlight-python"><div class="highlight"><pre>mapper(Book, book_table, properties={

497

505

'photo':deferred(book_table.c.photo)

498

506

})</pre></div>

694

702

must be distinguished from the Python expression, which can be achieved using

695

703

<a class="reference internal" href="extensions/hybrid.html#sqlalchemy.ext.hybrid.hybrid_property.expression" title="sqlalchemy.ext.hybrid.hybrid_property.expression"><tt class="xref py py-meth docutils literal">hybrid_property.expression()</tt></a>. Below we illustrate the case where a conditional

696

704

needs to be present inside the hybrid, using the <tt class="docutils literal">if</tt> statement in Python and the

697

<a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal">sql.expression.case()</tt></a> construct for SQL expressions:

705

<a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal">sql.expression.case()</tt></a> construct for SQL expressions:

698

706

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.ext.hybrid import hybrid_property

699

707

from sqlalchemy.sql import case

700

708

721

729

722

730

<h3>Using column_property<a class="headerlink" href="#using-column-property" title="Permalink to this headline">¶</a></h3>

723

731

The <a class="reference internal" href="#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal">orm.column_property()</tt></a> function can be used to map a SQL

724

expression in a manner similar to a regularly mapped <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>.

732

expression in a manner similar to a regularly mapped <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>.

725

733

With this technique, the attribute is loaded

726

734

along with all other column-mapped attributes at load time. This is in some

727

735

cases an advantage over the usage of hybrids, as the value can be loaded

744

752

lastname = Column(String(50))

745

753

fullname = column_property(firstname + " " + lastname)</pre></div>

746

754

</div>

747

Correlated subqueries may be used as well. Below we use the <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a>

755

Correlated subqueries may be used as well. Below we use the <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a>

748

756

construct to create a SELECT that links together the count of <tt class="docutils literal">Address</tt>

749

757

objects available for a particular <tt class="docutils literal">User</tt>:

750

758

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.orm import column_property

769

777

correlate_except(Address)

770

778

)</pre></div>

771

779

</div>

772

In the above example, we define a <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> construct like the following:

780

In the above example, we define a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> construct like the following:

773

781

<div class="highlight-python"><div class="highlight"><pre>select([func.count(Address.id)]).\

774

782

where(Address.user_id==id).\

775

783

correlate_except(Address)</pre></div>

776

784

</div>

777

785

The meaning of the above statement is, select the count of <tt class="docutils literal">Address.id</tt> rows

778

786

where the <tt class="docutils literal">Address.user_id</tt> column is equated to <tt class="docutils literal">id</tt>, which in the context

779

of the <tt class="docutils literal">User</tt> class is the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> named <tt class="docutils literal">id</tt> (note that <tt class="docutils literal">id</tt> is

787

of the <tt class="docutils literal">User</tt> class is the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> named <tt class="docutils literal">id</tt> (note that <tt class="docutils literal">id</tt> is

780

788

also the name of a Python built in function, which is not what we want to use

781

789

here - if we were outside of the <tt class="docutils literal">User</tt> class definition, we’d use <tt class="docutils literal">User.id</tt>).

782

790

The <tt class="xref py py-meth docutils literal">select.correlate_except()</tt> directive indicates that each element in the

783

FROM clause of this <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> may be omitted from the FROM list (that is, correlated

791

FROM clause of this <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> may be omitted from the FROM list (that is, correlated

784

792

to the enclosing SELECT statement against <tt class="docutils literal">User</tt>) except for the one corresponding

785

793

to <tt class="docutils literal">Address</tt>. This isn’t strictly necessary, but prevents <tt class="docutils literal">Address</tt> from

786

794

being inadvertently omitted from the FROM list in the case of a long string

795

803

where(Address.user_id==User.id)

796

804

)</pre></div>

797

805

</div>

798

For many-to-many relationships, use <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal">and_()</tt></a> to join the fields of the

806

For many-to-many relationships, use <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal">and_()</tt></a> to join the fields of the

799

807

association table to both tables in a relation, illustrated

800

808

here with a classical mapping:

801

809

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy import and_

908

916

<li>include_removes – if True, “remove” events will be

909

917

sent as well - the validation function must accept an additional

910

918

argument “is_remove” which will be a boolean.

911

912

New in version 0.7.7.

919

920

New in version 0.7.7.

921

</div>

913

922

</li>

914

923

</ul>

915

924

</td>

1037

1046

<h3>Synonyms<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>

1038

1047

Synonyms are a mapper-level construct that applies expression behavior to a descriptor

1039

1048

based attribute.

1040

1041

Changed in version 0.7: The functionality of synonym is superceded as of 0.7 by hybrid attributes.

1049

1050

Changed in version 0.7: The functionality of synonym is superceded as of 0.7 by hybrid attributes.

1051

</div>

1042

1052

1043

1053

1044

1054

<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">synonym</tt><big>(</big>name, map_column=False, descriptor=None, comparator_factory=None, doc=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.synonym" title="Permalink to this definition">¶</a></dt>

1045

1055

<dd>Denote an attribute name as a synonym to a mapped property.

1046

1047

Changed in version 0.7: <a class="reference internal" href="#sqlalchemy.orm.synonym" title="sqlalchemy.orm.synonym"><tt class="xref py py-func docutils literal">synonym()</tt></a> is superseded by the <a class="reference internal" href="extensions/hybrid.html#module-sqlalchemy.ext.hybrid" title="sqlalchemy.ext.hybrid"><tt class="xref py py-mod docutils literal">hybrid</tt></a>

1056

1057

Changed in version 0.7: <a class="reference internal" href="#sqlalchemy.orm.synonym" title="sqlalchemy.orm.synonym"><tt class="xref py py-func docutils literal">synonym()</tt></a> is superseded by the <a class="reference internal" href="extensions/hybrid.html#module-sqlalchemy.ext.hybrid" title="sqlalchemy.ext.hybrid"><tt class="xref py py-mod docutils literal">hybrid</tt></a>

1048

1058

extension. See the documentation for hybrids

1049

1059

at <a class="reference internal" href="extensions/hybrid.html">Hybrid Attributes</a>.

1060

</div>

1050

1061

Used with the <tt class="docutils literal">properties</tt> dictionary sent to

1051

1062

<a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a>:

1052

1063

<div class="highlight-python"><div class="highlight"><pre>class MyClass(object):

1108

1119

Sets of columns can be associated with a single user-defined datatype. The ORM

1109

1120

provides a single attribute which represents the group of columns using the

1110

1121

class you provide.

1111

1112

Changed in version 0.7: Composites have been simplified such that

1122

1123

Changed in version 0.7: Composites have been simplified such that

1113

1124

they no longer “conceal” the underlying column based attributes. Additionally,

1114

1125

in-place mutation is no longer automatic; see the section below on

1115

1126

enabling mutability to support tracking of in-place changes.

1127

</div>

1116

1128

A simple example represents pairs of columns as a <tt class="docutils literal">Point</tt> object.

1117

1129

<tt class="docutils literal">Point</tt> represents such a pair as <tt class="docutils literal">.x</tt> and <tt class="docutils literal">.y</tt>:

1118

1130

<div class="highlight-python"><div class="highlight"><pre>class Point(object):

1141

1153

also should supply adequate <tt class="docutils literal">__eq__()</tt> and <tt class="docutils literal">__ne__()</tt> methods which test

1142

1154

the equality of two instances.

1143

1155

We will create a mapping to a table <tt class="docutils literal">vertice</tt>, which represents two points

1144

as <tt class="docutils literal">x1/y1</tt> and <tt class="docutils literal">x2/y2</tt>. These are created normally as <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1156

as <tt class="docutils literal">x1/y1</tt> and <tt class="docutils literal">x2/y2</tt>. These are created normally as <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1145

1157

objects. Then, the <a class="reference internal" href="#sqlalchemy.orm.composite" title="sqlalchemy.orm.composite"><tt class="xref py py-func docutils literal">composite()</tt></a> function is used to assign new

1146

1158

attributes that will represent sets of columns via the <tt class="docutils literal">Point</tt> class:

1147

1159

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy import Column, Integer

1206

1218

<li>active_history=False – When <tt class="docutils literal">True</tt>, indicates that the “previous” value for a

1207

1219

scalar attribute should be loaded when replaced, if not

1208

1220

already loaded. See the same flag on <a class="reference internal" href="#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal">column_property()</tt></a>.

1209

1210

Changed in version 0.7: This flag specifically becomes meaningful

1221

1222

Changed in version 0.7: This flag specifically becomes meaningful

1211

1223

- previously it was a placeholder.

1224

</div>

1212

1225

</li>

1213

1226

<li>group – A group name for this property when marked as deferred.</li>

1214

1227

<li>deferred – When True, the column property is “deferred”, meaning that it does not

1221

1234

class-bound descriptor.</li>

1222

1235

<li>info – Optional data dictionary which will be populated into the

1223

1236

<a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.MapperProperty.info" title="sqlalchemy.orm.interfaces.MapperProperty.info"><tt class="xref py py-attr docutils literal">MapperProperty.info</tt></a> attribute of this object.

1224

1225

New in version 0.8.

1237

1238

New in version 0.8.

1239

</div>

1226

1240

</li>

1227

1241

<li>extension – an <a class="reference internal" href="deprecated.html#sqlalchemy.orm.interfaces.AttributeExtension" title="sqlalchemy.orm.interfaces.AttributeExtension"><tt class="xref py py-class docutils literal">AttributeExtension</tt></a> instance,

1228

1242

or list of extensions, which will be prepended to the list of

1243

1257

via the usage of the <a class="reference internal" href="extensions/mutable.html#sqlalchemy.ext.mutable.MutableComposite" title="sqlalchemy.ext.mutable.MutableComposite"><tt class="xref py py-class docutils literal">MutableComposite</tt></a> mixin, which uses events

1244

1258

to associate each user-defined composite object with all parent associations.

1245

1259

Please see the example in <a class="reference internal" href="extensions/mutable.html#mutable-composites">Establishing Mutability on Composites</a>.

1246

1247

Changed in version 0.7: In-place changes to an existing composite value are no longer

1260

1261

Changed in version 0.7: In-place changes to an existing composite value are no longer

1248

1262

tracked automatically; the functionality is superseded by the

1249

1263

<a class="reference internal" href="extensions/mutable.html#sqlalchemy.ext.mutable.MutableComposite" title="sqlalchemy.ext.mutable.MutableComposite"><tt class="xref py py-class docutils literal">MutableComposite</tt></a> class.

1250

1264

</div>

1265

</div>

1251

1266

1252

1267

<h3>Redefining Comparison Operations for Composites<a class="headerlink" href="#redefining-comparison-operations-for-composites" title="Permalink to this headline">¶</a></h3>

1253

1268

The “equals” comparison operation by default produces an AND of all

1287

1302

1288

1303

<h2>Mapping a Class against Multiple Tables<a class="headerlink" href="#mapping-a-class-against-multiple-tables" title="Permalink to this headline">¶</a></h2>

1289

1304

Mappers can be constructed against arbitrary relational units (called

1290

selectables) in addition to plain tables. For example, the <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.join" title="sqlalchemy.sql.expression.join"><tt class="xref py py-func docutils literal">join()</tt></a>

1305

selectables) in addition to plain tables. For example, the <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.join" title="sqlalchemy.sql.expression.join"><tt class="xref py py-func docutils literal">join()</tt></a>

1291

1306

function creates a selectable unit comprised of

1292

1307

multiple tables, complete with its own composite primary key, which can be

1293

mapped in the same way as a <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>:

1308

mapped in the same way as a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>:

1294

1309

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy import Table, Column, Integer, \

1295

1310

String, MetaData, join, ForeignKey

1296

1311

from sqlalchemy.ext.declarative import declarative_base

1346

1361

</div>

1347

1362

1348

1363

<h2>Mapping a Class against Arbitrary Selects<a class="headerlink" href="#mapping-a-class-against-arbitrary-selects" title="Permalink to this headline">¶</a></h2>

1349

Similar to mapping against a join, a plain <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> object can be used with a

1364

Similar to mapping against a join, a plain <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> object can be used with a

1350

1365

mapper as well. The example fragment below illustrates mapping a class

1351

called <tt class="docutils literal">Customer</tt> to a <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> which includes a join to a

1366

called <tt class="docutils literal">Customer</tt> to a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> which includes a join to a

1352

1367

subquery:

1353

1368

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy import select, func

1354

1369

1396

1411

<h2>Multiple Mappers for One Class<a class="headerlink" href="#multiple-mappers-for-one-class" title="Permalink to this headline">¶</a></h2>

1397

1412

In modern SQLAlchemy, a particular class is only mapped by one <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a>

1398

1413

at a time. The rationale here is that the <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a> modifies the class itself, not only

1399

persisting it towards a particular <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, but also instrumenting

1414

persisting it towards a particular <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, but also instrumenting

1400

1415

attributes upon the class which are structured specifically according to the

1401

1416

table metadata.

1402

1417

One potential use case for another mapper to exist at the same time is if we

1403

wanted to load instances of our class not just from the immediate <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

1418

wanted to load instances of our class not just from the immediate <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

1404

1419

to which it is mapped, but from another selectable that is a derivation of that

1405

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>. While there technically is a way to create such a <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a>,

1420

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>. While there technically is a way to create such a <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a>,

1406

1421

using the <tt class="docutils literal">non_primary=True</tt> option, this approach is virtually never needed.

1407

1422

Instead, we use the functionality of the <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> object to achieve this,

1408

1423

using a method such as <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.select_from" title="sqlalchemy.orm.query.Query.select_from"><tt class="xref py py-meth docutils literal">Query.select_from()</tt></a>

1417

1432

pattern, which is described as a recipe at <a class="reference external" href="http://www.sqlalchemy.org/trac/wiki/UsageRecipes/EntityName">Entity Name</a>.

1418

1433

</div>

1419

1434

1420

<h2>Constructors and Object Initialization<a class="headerlink" href="#constructors-and-object-initialization" title="Permalink to this headline">¶</a></h2>

1435

<h2>Constructors and Object Initialization<a class="headerlink" href="#constructors-and-object-initialization" title="Permalink to this headline">¶</a></h2>

1421

1436

Mapping imposes no restrictions or requirements on the constructor

1422

1437

(<tt class="docutils literal">__init__</tt>) method for the class. You are free to require any arguments for

1423

1438

the function that you wish, assign attributes to the instance that are unknown

1479

1494

</dd></dl>

1480

1495

1481

1496

</div>

1497

1498

<h2>Configuring a Version Counter<a class="headerlink" href="#configuring-a-version-counter" title="Permalink to this headline">¶</a></h2>

1499

The <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> supports management of a version id column, which

1500

is a single table column that increments or otherwise updates its value

1501

each time an <tt class="docutils literal">UPDATE</tt> to the mapped table occurs. This value is checked each

1502

time the ORM emits an <tt class="docutils literal">UPDATE</tt> or <tt class="docutils literal">DELETE</tt> against the row to ensure that

1503

the value held in memory matches the database value.

1504

The purpose of this feature is to detect when two concurrent transactions

1505

are modifying the same row at roughly the same time, or alternatively to provide

1506

a guard against the usage of a “stale” row in a system that might be re-using

1507

data from a previous transaction without refreshing (e.g. if one sets <tt class="docutils literal">expire_on_commit=False</tt>

1508

with a <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>, it is possible to re-use the data from a previous

1509

transaction).

1510

1511

Concurrent transaction updates

1512

When detecting concurrent updates within transactions, it is typically the

1513

case that the database’s transaction isolation level is below the level of

1514

repeatable read; otherwise, the transaction will not be exposed

1515

to a new row value created by a concurrent update which conflicts with

1516

the locally updated value. In this case, the SQLAlchemy versioning

1517

feature will typically not be useful for in-transaction conflict detection,

1518

though it still can be used for cross-transaction staleness detection.

1519

The database that enforces repeatable reads will typically either have locked the

1520

target row against a concurrent update, or is employing some form

1521

of multi version concurrency control such that it will emit an error

1522

when the transaction is committed. SQLAlchemy’s version_id_col is an alternative

1523

which allows version tracking to occur for specific tables within a transaction

1524

that otherwise might not have this isolation level set.

1525

1526

See also

1527

<a class="reference external" href="http://www.postgresql.org/docs/9.1/static/transaction-iso.html#XACT-REPEATABLE-READ">Repeatable Read Isolation Level</a> - Postgresql’s implementation of repeatable read, including a description of the error condition.

1528

</div>

1529

</div>

1530

1531

<h3>Simple Version Counting<a class="headerlink" href="#simple-version-counting" title="Permalink to this headline">¶</a></h3>

1532

The most straightforward way to track versions is to add an integer column

1533

to the mapped table, then establish it as the <tt class="docutils literal">version_id_col</tt> within the

1534

mapper options:

1535

<div class="highlight-python"><div class="highlight"><pre>class User(Base):

1536

__tablename__ = 'user'

1537

1538

id = Column(Integer, primary_key=True)

1539

version_id = Column(Integer, nullable=False)

1540

name = Column(String(50), nullable=False)

1541

1542

__mapper_args__ = {

1543

"version_id_col": version_id

1544

}</pre></div>

1545

</div>

1546

Above, the <tt class="docutils literal">User</tt> mapping tracks integer versions using the column

1547

<tt class="docutils literal">version_id</tt>. When an object of type <tt class="docutils literal">User</tt> is first flushed, the

1548

<tt class="docutils literal">version_id</tt> column will be given a value of “1”. Then, an UPDATE

1549

of the table later on will always be emitted in a manner similar to the

1550

following:

1551

<div class="highlight-python"><pre>UPDATE user SET version_id=:version_id, name=:name

1552

WHERE user.id = :user_id AND user.version_id = :user_version_id

1553

{"name": "new name", "version_id": 2, "user_id": 1, "user_version_id": 1}</pre>

1554

</div>

1555

The above UPDATE statement is updating the row that not only matches

1556

<tt class="docutils literal">user.id = 1</tt>, it also is requiring that <tt class="docutils literal">user.version_id = 1</tt>, where “1”

1557

is the last version identifier we’ve been known to use on this object.

1558

If a transaction elsewhere has modifed the row independently, this version id

1559

will no longer match, and the UPDATE statement will report that no rows matched;

1560

this is the condition that SQLAlchemy tests, that exactly one row matched our

1561

UPDATE (or DELETE) statement. If zero rows match, that indicates our version

1562

of the data is stale, and a <tt class="xref py py-class docutils literal">StaleDataError</tt> is raised.

1563

</div>

1564

1565

<h3>Custom Version Counters / Types<a class="headerlink" href="#custom-version-counters-types" title="Permalink to this headline">¶</a></h3>

1566

Other kinds of values or counters can be used for versioning. Common types include

1567

dates and GUIDs. When using an alternate type or counter scheme, SQLAlchemy

1568

provides a hook for this scheme using the <tt class="docutils literal">version_id_generator</tt> argument,

1569

which accepts a version generation callable. This callable is passed the value of the current

1570

known version, and is expected to return the subsequent version.

1571

For example, if we wanted to track the versioning of our <tt class="docutils literal">User</tt> class

1572

using a randomly generated GUID, we could do this (note that some backends

1573

support a native GUID type, but we illustrate here using a simple string):

1574

<div class="highlight-python"><div class="highlight"><pre>import uuid

1575

1576

class User(Base):

1577

__tablename__ = 'user'

1578

1579

id = Column(Integer, primary_key=True)

1580

version_uuid = Column(String(32))

1581

name = Column(String(50), nullable=False)

1582

1583

__mapper_args__ = {

1584

'version_id_col':version_uuid,

1585

'version_id_generator':lambda version: uuid.uuid4().hex

1586

}</pre></div>

1587

</div>

1588

The persistence engine will call upon <tt class="docutils literal">uuid.uuid4()</tt> each time a

1589

<tt class="docutils literal">User</tt> object is subject to an INSERT or an UPDATE. In this case, our

1590

version generation function can disregard the incoming value of <tt class="docutils literal">version</tt>,

1591

as the <tt class="docutils literal">uuid4()</tt> function

1592

generates identifiers without any prerequisite value. If we were using

1593

a sequential versioning scheme such as numeric or a special character system,

1594

we could make use of the given <tt class="docutils literal">version</tt> in order to help determine the

1595

subsequent value.

1596

1597

See also

1598

<a class="reference internal" href="../core/types.html#custom-guid-type">Backend-agnostic GUID Type</a>

1599

</div>

1600

</div>

1601

</div>

1482

1602

1483

1603

<h2>Class Mapping API<a class="headerlink" href="#class-mapping-api" title="Permalink to this headline">¶</a></h2>

1484

1604

1531

1651

<li>class_ – The class to be mapped. When using Declarative,

1532

1652

this argument is automatically passed as the declared class

1533

1653

itself.</li>

1534

<li>local_table – The <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> or other selectable

1654

<li>local_table – The <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> or other selectable

1535

1655

to which the class is mapped. May be <tt class="docutils literal">None</tt> if

1536

1656

this mapper inherits from another mapper using single-table

1537

1657

inheritance. When using Declarative, this argument is

1538

1658

automatically passed by the extension, based on what

1539

1659

is configured via the <tt class="docutils literal">__table__</tt> argument or via the

1540

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> produced as a result of the <tt class="docutils literal">__tablename__</tt>

1541

and <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> arguments present.</li>

1660

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> produced as a result of the <tt class="docutils literal">__tablename__</tt>

1661

and <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> arguments present.</li>

1542

1662

<li>always_refresh – If True, all query operations for this mapped

1543

1663

class will overwrite all data within object instances that already

1544

1664

exist within the session, erasing any in-memory changes with

1560

1680

<a class="reference internal" href="events.html#sqlalchemy.orm.events.MapperEvents" title="sqlalchemy.orm.events.MapperEvents"><tt class="xref py py-class docutils literal">MapperEvents</tt></a> listener requires being called

1561

1681

in between individual row persistence operations.</li>

1562

1682

<li>column_prefix – A string which will be prepended

1563

to the mapped attribute name when <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1683

to the mapped attribute name when <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1564

1684

objects are automatically assigned as attributes to the

1565

1685

mapped class. Does not affect explicitly specified

1566

1686

column-based properties.

1570

1690

table inheritance with its parent mapper.

1571

1691

See the section <a class="reference internal" href="inheritance.html#concrete-inheritance">Concrete Table Inheritance</a> for an example.

1572

1692

</li>

1693

<li>eager_defaults – if True, the ORM will immediately fetch the

1694

value of server-generated default values after an INSERT or UPDATE,

1695

rather than leaving them as expired to be fetched on next access.

1696

This can be used for event schemes where the server-generated values

1697

are needed immediately before the flush completes.

1698

This scheme will emit an individual <tt class="docutils literal">SELECT</tt> statement per row

1699

inserted or updated, which note can add significant performance

1700

overhead.</li>

1573

1701

<li>exclude_properties – A list or set of string column names to

1574

1702

be excluded from mapping.

1575

1703

See <a class="reference internal" href="#include-exclude-cols">Mapping a Subset of Table Columns</a> for an example.

1588

1716

of the other mapper’s class. When using Declarative, this argument

1589

1717

is passed automatically as a result of the natural class

1590

1718

hierarchy of the declared classes.

1591

See also:

1592

<a class="reference internal" href="inheritance.html">Mapping Class Inheritance Hierarchies</a>

1719

1720

See also

1721

<a class="reference internal" href="inheritance.html">Mapping Class Inheritance Hierarchies</a>

1722

</div>

1593

1723

</li>

1594

1724

<li>inherit_condition – For joined table inheritance, a SQL

1595

1725

expression which will

1596

1726

define how the two tables are joined; defaults to a natural join

1597

1727

between the two tables.</li>

1598

1728

<li>inherit_foreign_keys – When <tt class="docutils literal">inherit_condition</tt> is used and the

1599

columns present are missing a <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.ForeignKey" title="sqlalchemy.schema.ForeignKey"><tt class="xref py py-class docutils literal">ForeignKey</tt></a> configuration,

1729

columns present are missing a <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.ForeignKey" title="sqlalchemy.schema.ForeignKey"><tt class="xref py py-class docutils literal">ForeignKey</tt></a> configuration,

1600

1730

this parameter can be used to specify which columns are “foreign”.

1601

1731

In most cases can be left as <tt class="docutils literal">None</tt>.</li>

1602

1732

<li>legacy_is_orphan – Boolean, defaults to <tt class="docutils literal">False</tt>.

1613

1743

object has been flushed yet or not.

1614

1744

See the change note and example at <a class="reference internal" href="../changelog/migration_08.html#legacy-is-orphan-addition">The consideration of a “pending” object as an “orphan” has been made more aggressive</a>

1615

1745

for more detail on this change.

1616

1617

New in version 0.8: - the consideration of a pending object as

1746

1747

New in version 0.8: - the consideration of a pending object as

1618

1748

an “orphan” has been modified to more closely match the

1619

1749

behavior as that of persistent objects, which is that the object

1620

1750

is expunged from the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> as soon as it is

1623

1753

from all of its orphan-enabled parents. The new flag <tt class="docutils literal">legacy_is_orphan</tt>

1624

1754

is added to <a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">orm.mapper()</tt></a> which re-establishes the

1625

1755

legacy behavior.

1756

</div>

1626

1757

</li>

1627

1758

<li>non_primary – Specify that this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> is in addition

1628

1759

to the “primary” mapper, that is, the one used for persistence.

1632

1763

The <tt class="docutils literal">non_primary</tt> feature is rarely needed with modern

1633

1764

usage.

1634

1765

</li>

1635

<li>order_by – A single <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> or list of <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1766

<li>order_by – A single <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> or list of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1636

1767

objects for which selection operations should use as the default

1637

1768

ordering for entities. By default mappers have no pre-defined

1638

1769

ordering.</li>

1648

1779

operation for an update. The <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> here will

1649

1780

emit an UPDATE statement for the dependent columns during a

1650

1781

primary key change.

1651

See also:

1652

<a class="reference internal" href="relationships.html#passive-updates">Mutable Primary Keys / Update Cascades</a> - description of a similar feature as

1782

1783

See also

1784

<a class="reference internal" href="relationships.html#passive-updates">Mutable Primary Keys / Update Cascades</a> - description of a similar feature as

1653

1785

used with <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a>

1786

</div>

1654

1787

</li>

1655

1788

<li>polymorphic_on – Specifies the column, attribute, or

1656

1789

SQL expression used to determine the target class for an

1657

1790

incoming row, when inheriting classes are present.

1658

This value is commonly a <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> object that’s

1659

present in the mapped <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>:

1791

This value is commonly a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> object that’s

1792

present in the mapped <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>:

1660

1793

<div class="highlight-python"><div class="highlight"><pre>class Employee(Base):

1661

1794

__tablename__ = 'employee'

1662

1795

1670

1803

</div>

1671

1804

It may also be specified

1672

1805

as a SQL expression, as in this example where we

1673

use the <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal">case()</tt></a> construct to provide a conditional

1806

use the <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal">case()</tt></a> construct to provide a conditional

1674

1807

approach:

1675

1808

<div class="highlight-python"><div class="highlight"><pre>class Employee(Base):

1676

1809

__tablename__ = 'employee'

1706

1839

"polymorphic_identity":"employee"

1707

1840

}</pre></div>

1708

1841

</div>

1709

1710

Changed in version 0.7.4: <tt class="docutils literal">polymorphic_on</tt> may be specified as a SQL expression,

1842

1843

Changed in version 0.7.4: <tt class="docutils literal">polymorphic_on</tt> may be specified as a SQL expression,

1711

1844

or refer to any attribute configured with

1712

1845

<a class="reference internal" href="#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal">column_property()</tt></a>, or to the string name of one.

1846

</div>

1713

1847

When setting <tt class="docutils literal">polymorphic_on</tt> to reference an

1714

1848

attribute or expression that’s not present in the

1715

locally mapped <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, yet the value

1849

locally mapped <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, yet the value

1716

1850

of the discriminator should be persisted to the database,

1717

1851

the value of the

1718

1852

discriminator is not automatically set on new

1732

1866

for the mapped class to the <tt class="docutils literal">discriminator</tt> attribute,

1733

1867

thus persisting the value to the <tt class="docutils literal">discriminator</tt> column

1734

1868

in the database.

1735

See also:

1736

<a class="reference internal" href="inheritance.html">Mapping Class Inheritance Hierarchies</a>

1869

1870

See also

1871

<a class="reference internal" href="inheritance.html">Mapping Class Inheritance Hierarchies</a>

1872

</div>

1737

1873

</li>

1738

1874

<li>polymorphic_identity – Specifies the value which

1739

1875

identifies this particular class as returned by the

1744

1880

be used for the newly reconstructed object.</li>

1745

1881

<li>properties – A dictionary mapping the string names of object

1746

1882

attributes to <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.MapperProperty" title="sqlalchemy.orm.interfaces.MapperProperty"><tt class="xref py py-class docutils literal">MapperProperty</tt></a> instances, which define the

1747

persistence behavior of that attribute. Note that <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1883

persistence behavior of that attribute. Note that <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1748

1884

objects present in

1749

the mapped <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> are automatically placed into

1885

the mapped <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> are automatically placed into

1750

1886

<tt class="docutils literal">ColumnProperty</tt> instances upon mapping, unless overridden.

1751

1887

When using Declarative, this argument is passed automatically,

1752

1888

based on all those <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.MapperProperty" title="sqlalchemy.orm.interfaces.MapperProperty"><tt class="xref py py-class docutils literal">MapperProperty</tt></a> instances declared

1753

1889

in the declared class body.</li>

1754

<li>primary_key – A list of <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects which define the

1890

<li>primary_key – A list of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects which define the

1755

1891

primary key to be used against this mapper’s selectable unit.

1756

1892

This is normally simply the primary key of the <tt class="docutils literal">local_table</tt>, but

1757

1893

can be overridden here.</li>

1758

<li>version_id_col – A <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1759

that will be used to keep a running version id of mapped entities

1760

in the database. This is used during save operations to ensure that

1761

no other thread or process has updated the instance during the

1762

lifetime of the entity, else a

1894

<li>version_id_col – A <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a>

1895

that will be used to keep a running version id of rows

1896

in the table. This is used to detect concurrent updates or

1897

the presence of stale data in a flush. The methodology is to

1898

detect if an UPDATE statement does not match the last known

1899

version id, a

1763

1900

<a class="reference internal" href="exceptions.html#sqlalchemy.orm.exc.StaleDataError" title="sqlalchemy.orm.exc.StaleDataError"><tt class="xref py py-class docutils literal">StaleDataError</tt></a> exception is

1764

thrown. By default the column must be of <a class="reference internal" href="../core/types.html#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal">Integer</tt></a> type,

1765

unless <tt class="docutils literal">version_id_generator</tt> specifies a new generation

1766

algorithm.</li>

1767

<li>version_id_generator – A callable which defines the algorithm

1768

used to generate new version ids. Defaults to an integer

1769

generator. Can be replaced with one that generates timestamps,

1770

uuids, etc. e.g.:

1771

<div class="highlight-python"><div class="highlight"><pre>import uuid

1772

1773

class MyClass(Base):

1774

__tablename__ = 'mytable'

1775

id = Column(Integer, primary_key=True)

1776

version_uuid = Column(String(32))

1777

1778

__mapper_args__ = {

1779

'version_id_col':version_uuid,

1780

'version_id_generator':lambda version:uuid.uuid4().hex

1781

}</pre></div>

1782

</div>

1783

The callable receives the current version identifier as its

1784

single argument.

1901

thrown.

1902

By default, the column must be of <a class="reference internal" href="../core/types.html#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal">Integer</tt></a> type,

1903

unless <tt class="docutils literal">version_id_generator</tt> specifies an alternative version

1904

generator.

1905

1906

See also

1907

<a class="reference internal" href="#mapper-version-counter">Configuring a Version Counter</a> - discussion of version counting

1908

and rationale.

1909

</div>

1910

</li>

1911

<li>version_id_generator – Define how new version ids should

1912

be generated. Defaults to <tt class="docutils literal">None</tt>, which indicates that

1913

a simple integer counting scheme be employed. To provide a custom

1914

versioning scheme, provide a callable function of the form:

1915

<div class="highlight-python"><div class="highlight"><pre>def generate_version(version):

1916

return next_version</pre></div>

1917

</div>

1918

1919

See also

1920

<a class="reference internal" href="#custom-version-counter">Custom Version Counters / Types</a>

1921

</div>

1785

1922

</li>

1786

1923

<li>with_polymorphic – A tuple in the form <tt class="docutils literal">(<classes>,

1787

1924

<selectable>)</tt> indicating the default style of “polymorphic”

1792

1929

loaded immediately. The second tuple argument <selectable>

1793

1930

indicates a selectable that will be used to query for multiple

1794

1931

classes.

1795

See also:

1796

<a class="reference internal" href="inheritance.html#concrete-inheritance">Concrete Table Inheritance</a> - typically uses <tt class="docutils literal">with_polymorphic</tt>

1797

to specify a UNION statement to select from.

1798

<a class="reference internal" href="inheritance.html#with-polymorphic">Basic Control of Which Tables are Queried</a> - usage example of the related

1799

<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.with_polymorphic" title="sqlalchemy.orm.query.Query.with_polymorphic"><tt class="xref py py-meth docutils literal">Query.with_polymorphic()</tt></a> method

1932

1933

See also

1934

<a class="reference internal" href="inheritance.html#with-polymorphic">Basic Control of Which Tables are Queried</a>

1935

</div>

1800

1936

</li>

1801

1937

</ul>

1802

1938

</td>

1913

2049

1914

2050

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1915

2051

<li>table_map – mapping of polymorphic identities to

1916

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects.</li>

2052

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects.</li>

1917

2053

<li>typecolname – string name of a “discriminator” column, which will be

1918

2054

derived from the query, producing the polymorphic identity for

1919

2055

each row. If <tt class="docutils literal">None</tt>, no polymorphic discriminator is generated.</li>

1920

<li>aliasname – name of the <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.alias" title="sqlalchemy.sql.expression.alias"><tt class="xref py py-func docutils literal">alias()</tt></a>

2056

<li>aliasname – name of the <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.alias" title="sqlalchemy.sql.expression.alias"><tt class="xref py py-func docutils literal">alias()</tt></a>

1921

2057

construct generated.</li>

1922

2058

<li>cast_nulls – if True, non-existent columns, which are represented

1923

2059

as labeled NULLs, will be passed into CAST. This is a legacy behavior

1933

2069

1934

2070

1935

2071

class <tt class="descclassname">sqlalchemy.orm.mapper.</tt><tt class="descname">Mapper</tt><big>(</big>class_, local_table, properties=None, primary_key=None, non_primary=False, inherits=None, inherit_condition=None, inherit_foreign_keys=None, extension=None, order_by=False, always_refresh=False, version_id_col=None, version_id_generator=None, polymorphic_on=None, _polymorphic_map=None, polymorphic_identity=None, concrete=False, with_polymorphic=None, allow_partial_pks=True, batch=True, column_prefix=None, include_properties=None, exclude_properties=None, passive_updates=True, eager_defaults=False, legacy_is_orphan=False, _compiled_cache_size=100<big>)</big><a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper" title="Permalink to this definition">¶</a></dt>

1936

<dd>Define the correlation of class attributes to database table

2072

<dd>Bases: <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces._InspectionAttr" title="sqlalchemy.orm.interfaces._InspectionAttr"><tt class="xref py py-class docutils literal">sqlalchemy.orm.interfaces._InspectionAttr</tt></a>

2073

Define the correlation of class attributes to database table

1937

2074

columns.

1938

2075

The <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> object is instantiated using the

1939

2076

<a class="reference internal" href="#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a> function. For information

2001

2138

<a class="reference internal" href="internals.html#sqlalchemy.orm.attributes.QueryableAttribute.property" title="sqlalchemy.orm.attributes.QueryableAttribute.property"><tt class="xref py py-attr docutils literal">QueryableAttribute.property</tt></a> attribute refers to the

2002

2139

<a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.MapperProperty" title="sqlalchemy.orm.interfaces.MapperProperty"><tt class="xref py py-class docutils literal">MapperProperty</tt></a> property, which is what you get when referring

2003

2140

to the collection of mapped properties via <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.attrs" title="sqlalchemy.orm.mapper.Mapper.attrs"><tt class="xref py py-attr docutils literal">Mapper.attrs</tt></a>.

2004

2005

New in version 0.8.0.

2006

2141

2142

New in version 0.8.0.

2143

</div>

2144

2007

2145

See also

2008

2146

<a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.attrs" title="sqlalchemy.orm.mapper.Mapper.attrs"><tt class="xref py py-attr docutils literal">Mapper.attrs</tt></a>

2009

2147

</div>

2025

2163

of this attribute which limit the types of properties

2026

2164

returned, inclding <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.synonyms" title="sqlalchemy.orm.mapper.Mapper.synonyms"><tt class="xref py py-attr docutils literal">synonyms</tt></a>, <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.column_attrs" title="sqlalchemy.orm.mapper.Mapper.column_attrs"><tt class="xref py py-attr docutils literal">column_attrs</tt></a>,

2027

2165

<a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.relationships" title="sqlalchemy.orm.mapper.Mapper.relationships"><tt class="xref py py-attr docutils literal">relationships</tt></a>, and <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.composites" title="sqlalchemy.orm.mapper.Mapper.composites"><tt class="xref py py-attr docutils literal">composites</tt></a>.

2028

2166

2029

2167

See also

2030

2168

<a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.all_orm_descriptors" title="sqlalchemy.orm.mapper.Mapper.all_orm_descriptors"><tt class="xref py py-attr docutils literal">Mapper.all_orm_descriptors</tt></a>

2031

2169

</div>

2102

2240

2103

2241

2104

2242

<tt class="descname">columns</tt> = None<a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.columns" title="Permalink to this definition">¶</a></dt>

2105

<dd>A collection of <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> or other scalar expression

2243

<dd>A collection of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> or other scalar expression

2106

2244

objects maintained by this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a>.

2107

2245

The collection behaves the same as that of the <tt class="docutils literal">c</tt> attribute on

2108

any <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> object, except that only those columns included in

2246

any <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> object, except that only those columns included in

2109

2247

this mapping are present, and are keyed based on the attribute name

2110

2248

defined in the mapping, not necessarily the <tt class="docutils literal">key</tt> attribute of the

2111

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> itself. Additionally, scalar expressions mapped

2249

<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> itself. Additionally, scalar expressions mapped

2112

2250

by <a class="reference internal" href="#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal">column_property()</tt></a> are also present here.

2113

2251

This is a read only attribute determined during mapper construction.

2114

2252

Behavior is undefined if directly modified.

2125

2263

2126

2264

<tt class="descname">compile</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.compile" title="Permalink to this definition">¶</a></dt>

2127

2265

<dd>Initialize the inter-mapper relationships of all mappers that

2128

2129

Deprecated since version 0.7: <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.compile" title="sqlalchemy.orm.mapper.Mapper.compile"><tt class="xref py py-meth docutils literal">Mapper.compile()</tt></a> is replaced by <a class="reference internal" href="#sqlalchemy.orm.configure_mappers" title="sqlalchemy.orm.configure_mappers"><tt class="xref py py-func docutils literal">configure_mappers()</tt></a>

2266

2267

Deprecated since version 0.7: <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.compile" title="sqlalchemy.orm.mapper.Mapper.compile"><tt class="xref py py-meth docutils literal">Mapper.compile()</tt></a> is replaced by <a class="reference internal" href="#sqlalchemy.orm.configure_mappers" title="sqlalchemy.orm.configure_mappers"><tt class="xref py py-func docutils literal">configure_mappers()</tt></a>

2268

</div>

2130

2269

have been constructed thus far.

2131

2270

</dd></dl>

2132

2271

2133

2272

2134

2273

2135

2274

<tt class="descname">compiled</tt><a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.compiled" title="Permalink to this definition">¶</a></dt>

2136

<dd>

2137

Deprecated since version 0.7: <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.compiled" title="sqlalchemy.orm.mapper.Mapper.compiled"><tt class="xref py py-attr docutils literal">Mapper.compiled</tt></a> is replaced by <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.configured" title="sqlalchemy.orm.mapper.Mapper.configured"><tt class="xref py py-attr docutils literal">Mapper.configured</tt></a>

2275

2276

Deprecated since version 0.7: <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.compiled" title="sqlalchemy.orm.mapper.Mapper.compiled"><tt class="xref py py-attr docutils literal">Mapper.compiled</tt></a> is replaced by <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.configured" title="sqlalchemy.orm.mapper.Mapper.configured"><tt class="xref py py-attr docutils literal">Mapper.configured</tt></a>

2277

</div>

2138

2278

</dd></dl>

2139

2279

2140

2280

2181

2321

2182

2322

2183

2323

<tt class="descname">get_property_by_column</tt><big>(</big>column<big>)</big><a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.get_property_by_column" title="Permalink to this definition">¶</a></dt>

2184

<dd>Given a <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> object, return the

2324

<dd>Given a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> object, return the

2185

2325

<a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.MapperProperty" title="sqlalchemy.orm.interfaces.MapperProperty"><tt class="xref py py-class docutils literal">MapperProperty</tt></a> which maps this column.

2186

2326

</dd></dl>

2187

2327

2248

2388

2249

2389

2250

2390

<tt class="descname">local_table</tt> = None<a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.local_table" title="Permalink to this definition">¶</a></dt>

2251

<dd>The <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Selectable" title="sqlalchemy.sql.expression.Selectable"><tt class="xref py py-class docutils literal">Selectable</tt></a> which this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> manages.

2252

Typically is an instance of <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> or <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><tt class="xref py py-class docutils literal">Alias</tt></a>.

2391

<dd>The <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Selectable" title="sqlalchemy.sql.expression.Selectable"><tt class="xref py py-class docutils literal">Selectable</tt></a> which this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> manages.

2392

Typically is an instance of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> or <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><tt class="xref py py-class docutils literal">Alias</tt></a>.

2253

2393

May also be <tt class="docutils literal">None</tt>.

2254

2394

The “local” table is the

2255

2395

selectable that the <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> is directly responsible for

2265

2405

2266

2406

2267

2407

<tt class="descname">mapped_table</tt> = None<a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.mapped_table" title="Permalink to this definition">¶</a></dt>

2268

<dd>The <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Selectable" title="sqlalchemy.sql.expression.Selectable"><tt class="xref py py-class docutils literal">Selectable</tt></a> to which this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> is mapped.

2269

Typically an instance of <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a>, or

2270

<a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><tt class="xref py py-class docutils literal">Alias</tt></a>.

2408

<dd>The <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Selectable" title="sqlalchemy.sql.expression.Selectable"><tt class="xref py py-class docutils literal">Selectable</tt></a> to which this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> is mapped.

2409

Typically an instance of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a>, or

2410

<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><tt class="xref py py-class docutils literal">Alias</tt></a>.

2271

2411

The “mapped” table is the selectable that

2272

2412

the mapper selects from during queries. For non-inheriting

2273

2413

mappers, the mapped table is the same as the “local” table.

2274

2414

For joined-table inheritance mappers, mapped_table references the

2275

full <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a> representing full rows for this particular

2415

full <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a> representing full rows for this particular

2276

2416

subclass. For single-table inheritance mappers, mapped_table

2277

2417

references the base table.

2278

2418

See also <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.local_table" title="sqlalchemy.orm.mapper.Mapper.local_table"><tt class="xref py py-attr docutils literal">local_table</tt></a>.

2335

2475

2336

2476

2337

2477

<tt class="descname">polymorphic_on</tt> = None<a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.polymorphic_on" title="Permalink to this definition">¶</a></dt>

2338

<dd>The <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> or SQL expression specified as the

2478

<dd>The <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> or SQL expression specified as the

2339

2479

<tt class="docutils literal">polymorphic_on</tt> argument

2340

2480

for this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a>, within an inheritance scenario.

2341

This attribute is normally a <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> instance but

2481

This attribute is normally a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> instance but

2342

2482

may also be an expression, such as one derived from

2343

<a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal">cast()</tt></a>.

2483

<a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal">cast()</tt></a>.

2344

2484

This is a read only attribute determined during mapper construction.

2345

2485

Behavior is undefined if directly modified.

2346

2486

</dd></dl>

2348

2488

2349

2489

2350

2490

<tt class="descname">primary_key</tt> = None<a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.primary_key" title="Permalink to this definition">¶</a></dt>

2351

<dd>An iterable containing the collection of <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects

2491

<dd>An iterable containing the collection of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects

2352

2492

which comprise the ‘primary key’ of the mapped table, from the

2353

2493

perspective of this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a>.

2354

2494

This list is against the selectable in <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.mapped_table" title="sqlalchemy.orm.mapper.Mapper.mapped_table"><tt class="xref py py-attr docutils literal">mapped_table</tt></a>. In

2355

2495

the case of inheriting mappers, some columns may be managed by a

2356

superclass mapper. For example, in the case of a <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a>, the

2496

superclass mapper. For example, in the case of a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a>, the

2357

2497

primary key is determined by all of the primary key columns across all

2358

tables referenced by the <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a>.

2498

tables referenced by the <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a>.

2359

2499

The list is also not necessarily the same as the primary key column

2360

2500

collection associated with the underlying tables; the <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a>

2361

2501

features a <tt class="docutils literal">primary_key</tt> argument that can override what the

2391

2531

2392

2532

2393

2533

<tt class="descname">selectable</tt><a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.selectable" title="Permalink to this definition">¶</a></dt>

2394

<dd>The <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> construct this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> selects from

2534

<dd>The <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> construct this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> selects from

2395

2535

by default.

2396

2536

Normally, this is equivalent to <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper.mapped_table" title="sqlalchemy.orm.mapper.Mapper.mapped_table"><tt class="xref py py-attr docutils literal">mapped_table</tt></a>, unless

2397

2537

the <tt class="docutils literal">with_polymorphic</tt> feature is in use, in which case the

2398

full “polymoprhic” selectable is returned.

2538

full “polymorphic” selectable is returned.

2399

2539

</dd></dl>

2400

2540

2401

2541

2429

2569

2430

2570

2431

2571

<tt class="descname">tables</tt> = None<a class="headerlink" href="#sqlalchemy.orm.mapper.Mapper.tables" title="Permalink to this definition">¶</a></dt>

2432

<dd>An iterable containing the collection of <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects

2572

<dd>An iterable containing the collection of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects

2433

2573

which this <a class="reference internal" href="#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> is aware of.

2434

If the mapper is mapped to a <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a>, or an <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><tt class="xref py py-class docutils literal">Alias</tt></a>

2435

representing a <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.Select" title="sqlalchemy.sql.expression.Select"><tt class="xref py py-class docutils literal">Select</tt></a>, the individual <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

2574

If the mapper is mapped to a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><tt class="xref py py-class docutils literal">Join</tt></a>, or an <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><tt class="xref py py-class docutils literal">Alias</tt></a>

2575

representing a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select" title="sqlalchemy.sql.expression.Select"><tt class="xref py py-class docutils literal">Select</tt></a>, the individual <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

2436

2576

objects that comprise the full construct will be represented here.

2437

2577

This is a read only attribute determined during mapper construction.

2438

2578

Behavior is undefined if directly modified.

2471

2611

2472

2612

2473

2613

2474

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.

2614

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.

2475

2615

</div>

2476

2616

</div>

2477

2617