<commit_before>.. _ref-models-instances:

========================
Model instance reference
========================

.. currentmodule:: django.db.models
   
This document describes the details of the ``Model`` API. It builds on the
material presented in the :ref:`model <topics-db-models>` and `database query
<topics-db-queries>` guides, so you'll probably want to read and understand
those documents before reading this one.

Throughout this reference we'll use the :ref:`example weblog models
<queryset-model-example>` presented in the :ref:`database query guide
<topics-db-queries>`.

Creating objects
================

To create a new instance of a model, just instantiate it like any other Python class:

.. class:: Model(**kwargs)

The keyword arguments to are simply the names of the fields you've defined on
your model. Note that instantiating a model in no way touches your database; for
that, you need to ``save()``.

Saving objects
==============

To save an object back to the database, call ``save()``:

.. method:: Model.save([raw=False])

Of course, there's some subtleties; see the sections below.

Auto-incrementing primary keys
------------------------------

If a model has an ``AutoField`` -- an auto-incrementing primary key -- then
that auto-incremented value will be calculated and saved as an attribute on
your object the first time you call ``save()``::

    >>> b2 = Blog(name='<NAME>', tagline='Thoughts on cheese.')
    >>> b2.id     # Returns None, because b doesn't have an ID yet.
    >>> b2.save()
    >>> b2.id     # Returns the ID of your new object.

There's no way to tell what the value of an ID will be before you call
``save()``, because that value is calculated by your database, not by Django.

(For convenience, each model has an ``AutoField`` named ``id`` by default
unless you explicitly specify ``primary_key=True`` on a field. See the
documentation for ``AutoField`` for more details.

The ``pk`` property
~~~~~~~~~~~~~~~~~~~

**New in Django development version**

.. attribute:: Model.pk

Regardless of whether you define a primary key field yourself, or let Django
supply one for you, each model will have a property called ``pk``. It behaves
like a normal attribute on the model, but is actually an alias for whichever
attribute is the primary key field for the model. You can read and set this<commit_msg>Fixed #8662 -- Fixed the documentation of Model.save() to match the real signature so that people overriding it will use the right signature.<commit_after>.. _ref-models-instances:

========================
Model instance reference
========================

.. currentmodule:: django.db.models
   
This document describes the details of the ``Model`` API. It builds on the
material presented in the :ref:`model <topics-db-models>` and `database query
<topics-db-queries>` guides, so you'll probably want to read and understand
those documents before reading this one.

Throughout this reference we'll use the :ref:`example weblog models
<queryset-model-example>` presented in the :ref:`database query guide
<topics-db-queries>`.

Creating objects
================

To create a new instance of a model, just instantiate it like any other Python class:

.. class:: Model(**kwargs)

The keyword arguments to are simply the names of the fields you've defined on
your model. Note that instantiating a model in no way touches your database; for
that, you need to ``save()``.

Saving objects
==============

To save an object back to the database, call ``save()``:

.. method:: Model.save([force_insert=False, force_update=False])

Of course, there's some subtleties; see the sections below.

**New in Django development version:** The signature of the ``save()`` method
has changed from earlier versions (``force_insert`` and ``force_update`` have
been added). If you are overriding these methods, be sure to use the correct
signature.

Auto-incrementing primary keys
------------------------------

If a model has an ``AutoField`` -- an auto-incrementing primary key -- then
that auto-incremented value will be calculated and saved as an attribute on
your object the first time you call ``save()``::

    >>> b2 = Blog(name='<NAME>', tagline='Thoughts on cheese.')
    >>> b2.id     # Returns None, because b doesn't have an ID yet.
    >>> b2.save()
    >>> b2.id     # Returns the ID of your new object.

There's no way to tell what the value of an ID will be before you call
``save()``, because that value is calculated by your database, not by Django.

(For convenience, each model has an ``AutoField`` named ``id`` by default
unless you explicitly specify ``primary_key=True`` on a field. See the
documentation for ``AutoField`` for more details.

The ``pk`` property
~~~~~~~~~~~~~~~~~~~

**New in Django development version**

.. attribute:: Model.pk

Regardless of whether you define a primary key field yourself, or let Django
supply one for you, each model will have a property called ``pk``. It behaves
like a normal attribute on the model, but is actually an alias for whichever
attribute is the primary key field for the model. You can read and set this
{'fraction_non_alphanumeric': 0.13618601016021883, 'fraction_numerical': 0.0023446658851113715, 'mean_word_length': 4.181174089068826, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 37, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2463006', 'n_tokens_mistral': 1370, 'n_tokens_neox': 1296, 'n_words': 690}