Fields¶

Usage¶

Fields are defined as properties of a Model class object:

from tortoise.models import Model
from tortoise import fields

class Tournament(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=255)

Reference¶

Here is the list of fields available with custom options of these fields:

Base Field¶

class tortoise.fields.base.Field(source_field=None, generated=False, primary_key=None, null=False, default=None, db_default=NOT_PROVIDED, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[source]¶

Base Field type.

Parameters:¶

source_field=None¶: Provide a source_field name if the DB column name needs to be something specific instead of generated off the field name.
generated=False¶: Is this field DB-generated?
primary_key=None¶: Is this field a Primary Key? Can only have a single such field on the Model, and if none is specified it will autogenerate a default primary key called id.
null=False¶: Is this field nullable?
default=None¶: A default value for the field if not specified on Model creation. This can also be a callable for dynamic defaults in which case we will call it. The default value will not be part of the schema.
unique=False¶: Is this field unique?
db_index=None¶: Should this field be indexed by itself?
description=None¶: Field description. Will also appear in Tortoise.describe_model() and as DB comments in the generated DDL.
validators=None¶: Validators for this field.

Class Attributes: These attributes needs to be defined when defining an actual field type.

field_type type[Any]¶: The Python type the field is. If adding a type as a mixin, _FieldMeta will automatically set this to that.

indexable bool = True¶: Is the field indexable? Set to False if this field can’t be indexed reliably.

has_db_field bool = True¶: Does this field have a direct corresponding DB column? Or is the field virtualized?

skip_to_python_if_native bool = False¶: If the DB driver natively supports this Python type, should we skip it? This is for optimization purposes only, where we don’t need to force type conversion between Python and the DB.

allows_generated bool = False¶: Is this field able to be DB-generated?

function_cast Optional[pypika_tortoise.Term] = None¶: A casting term that we need to apply in case the DB needs emulation help.

SQL_TYPE str¶: The SQL type as a string that the DB will use.

GENERATED_SQL str¶: The SQL that instructs the DB to auto-generate this field. Required if allows_generated is True.

Per-DB overrides:

One can specify per-DB overrides of any of the class attributes, or the to_db_value or to_python_value methods.

To do so, specify a inner class in the form of class _db__SQL_DIALECT: like so:

class _db_sqlite:
    SQL_TYPE = "VARCHAR(40)"
    skip_to_python_if_native = False

    def function_cast(self, term: Term) -> Term:
        return functions.Cast(term, SqlTypes.NUMERIC)

Tortoise will then use the overridden attributes/functions for that dialect. If you need a dynamic attribute, you can use a property.

property constraints : dict¶

Returns a dict with constraints defined in the Pydantic/JSONSchema format.

Return type:¶: dict

deconstruct()[source]¶

Return type:¶: tuple

describe(serializable)[source]¶

Describes the field.

Parameters:¶

serializable¶: False if you want raw python objects, True for JSON-serializable data. (Defaults to True)

Return type:¶

dict

Returns:¶

A dictionary containing the field description.

(This assumes serializable=True, which is the default):

{
    "name":         str     # Field name
    "field_type":   str     # Field type
    "db_column":    str     # Name of DB column
                            #  Optional: Only for pk/data fields
    "raw_field":    str     # Name of raw field of the Foreign Key
                            #  Optional: Only for Foreign Keys
    "db_field_types": dict  # DB Field types for default and DB overrides
    "python_type":  str     # Python type
    "generated":    bool    # Is the field generated by the DB?
    "nullable":     bool    # Is the column nullable?
    "unique":       bool    # Is the field unique?
    "indexed":      bool    # Is the field indexed?
    "default":      ...     # The default value (coerced to int/float/str/bool/null)
    "description":  str     # Description of the field (nullable)
    "docstring":    str     # Field docstring (nullable)
}

When serializable=False is specified some fields are not coerced to valid JSON types. The changes are:

{
    "field_type":   Field   # The Field class used
    "python_type":  Type    # The actual Python type
    "default":      ...     # The default value as native type OR a callable
}

get_db_field_type()[source]¶

Returns the DB field type for this field for the current dialect.

Return type:¶: str

get_db_field_types()[source]¶

Returns the DB types for this field.

Return type:¶: dict[str, str] | None
Returns:¶: A dictionary that is keyed by dialect. A blank dialect “” means it is the default DB field type.

get_for_dialect(dialect, key)[source]¶

Returns a field by dialect override.

Parameters:¶

dialect¶: The requested SQL Dialect.
key¶: The attribute/method name.

Return type:¶

Any

has_db_default()[source]¶

Return type:¶: bool

property required : bool¶

Returns True if the field is required to be provided.

It needs to be non-nullable and not have a default or be DB-generated to be required.

Return type:¶: bool

to_db_value(value, instance)[source]¶

Converts from the Python type to the DB type.

Parameters:¶

value¶

Current python value in model.

instance : type[tortoise.models.Model] | tortoise.models.Model¶

Model class or Model instance provided to look up.

Due to metacoding, to determine if this is an instance reliably, please do a:

if hasattr(instance, "_saved_in_db"):

Return type:¶

Any

to_python_value(value)[source]¶

Converts from the DB type to the Python type.

Parameters:¶

value¶: Value from DB

Return type:¶

Any

validate(value)[source]¶

Validate whether given value is valid

Parameters:¶

value¶: Value to be validation

Raises:¶

ValidationError – If validator check is not passed

Return type:¶

None

class tortoise.fields.base.OnDelete(value)[source]¶

An enumeration.

CASCADE = 'CASCADE'¶

NO_ACTION = 'NO ACTION'¶

RESTRICT = 'RESTRICT'¶

SET_DEFAULT = 'SET DEFAULT'¶

SET_NULL = 'SET NULL'¶

class tortoise.fields.base.StrEnum(value)[source]¶

An enumeration.

__format__(format_spec)¶: Returns format using actual value type unless __str__ has been overridden.

Data Fields¶

class tortoise.fields.data.BigIntField(primary_key: bool | None = None, *, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.BigIntField(primary_key: bool | None = None, *, null: True, **kwargs: Any)

Big integer field. (64-bit signed)

primary_key (bool):: True if field is Primary Key.

property constraints : dict¶

Returns a dict with constraints defined in the Pydantic/JSONSchema format.

Return type:¶: dict

class tortoise.fields.data.BinaryField(*, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.BinaryField(*, null: True, **kwargs: Any)

Binary field.

This is for storing bytes objects. Note that filter or queryset-update operations are not supported.

field_type¶: alias of bytes

class tortoise.fields.data.BooleanField(*, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.BooleanField(*, null: True, **kwargs: Any)

Boolean field.

field_type¶: alias of bool

tortoise.fields.data.CharEnumField(enum_type, description=None, max_length=0, **kwargs)[source]¶

Char Enum Field

A field representing a character enumeration.

Warning: If max_length is not specified or equals to zero, the size of represented char fields is automatically detected. So if later you update the enum, you need to update your table schema as well.

Note: Valid str value of enum_type is acceptable.

enum_type:: The enum class
description:: The description of the field. It is set automatically if not specified to a multiline list of “name: value” pairs.
max_length:: The length of the created CharField. If it is zero it is automatically detected from enum_type.

Return type:¶: Enum

class tortoise.fields.data.CharField(max_length: int, *, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.CharField(max_length: int, *, null: True, **kwargs: Any)

Character field.

You must provide the following:

max_length (int):: Maximum length of the field in characters.

property constraints : dict¶

Returns a dict with constraints defined in the Pydantic/JSONSchema format.

Return type:¶: dict

field_type¶: alias of str

class tortoise.fields.data.DateField(*, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.DateField(*, null: True, **kwargs: Any)

Date field.

field_type¶: alias of date

class tortoise.fields.data.DatetimeField(auto_now: bool = False, auto_now_add: bool = False, *, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.DatetimeField(auto_now: bool = False, auto_now_add: bool = False, *, null: True, **kwargs: Any)

Datetime field.

auto_now and auto_now_add is exclusive. You can opt to set neither or only ONE of them.

auto_now (bool):: Always set to datetime.utcnow() on save.
auto_now_add (bool):: Set to datetime.utcnow() on first save only.

property constraints : dict¶

Returns a dict with constraints defined in the Pydantic/JSONSchema format.

Return type:¶: dict

describe(serializable)[source]¶

Describes the field.

Parameters:¶

serializable¶: False if you want raw python objects, True for JSON-serializable data. (Defaults to True)

Return type:¶

dict

Returns:¶

A dictionary containing the field description.

(This assumes serializable=True, which is the default):

{
    "name":         str     # Field name
    "field_type":   str     # Field type
    "db_column":    str     # Name of DB column
                            #  Optional: Only for pk/data fields
    "raw_field":    str     # Name of raw field of the Foreign Key
                            #  Optional: Only for Foreign Keys
    "db_field_types": dict  # DB Field types for default and DB overrides
    "python_type":  str     # Python type
    "generated":    bool    # Is the field generated by the DB?
    "nullable":     bool    # Is the column nullable?
    "unique":       bool    # Is the field unique?
    "indexed":      bool    # Is the field indexed?
    "default":      ...     # The default value (coerced to int/float/str/bool/null)
    "description":  str     # Description of the field (nullable)
    "docstring":    str     # Field docstring (nullable)
}

When serializable=False is specified some fields are not coerced to valid JSON types. The changes are:

{
    "field_type":   Field   # The Field class used
    "python_type":  Type    # The actual Python type
    "default":      ...     # The default value as native type OR a callable
}

field_type¶: alias of datetime

class tortoise.fields.data.DecimalField(max_digits: int, decimal_places: int, *, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.DecimalField(max_digits: int, decimal_places: int, *, null: True, **kwargs: Any)

Accurate decimal field.

You must provide the following:

max_digits (int):: Max digits of significance of the decimal field.
decimal_places (int):: How many of those significant digits is after the decimal point.

field_type¶: alias of Decimal

class tortoise.fields.data.FloatField(*, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.FloatField(*, null: True, **kwargs: Any)

Float (double) field.

field_type¶: alias of float

tortoise.fields.data.IntEnumField(enum_type, description=None, **kwargs)[source]¶

Enum Field

A field representing an integer enumeration.

The description of the field is set automatically if not specified to a multiline list of “name: value” pairs.

Note: Valid int value of enum_type is acceptable.

enum_type:: The enum class
description:: The description of the field. It is set automatically if not specified to a multiline list of “name: value” pairs.

Return type:¶: IntEnum

class tortoise.fields.data.IntField(primary_key: bool | None = None, *, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.IntField(primary_key: bool | None = None, *, null: True, **kwargs: Any)

Integer field. (32-bit signed)

primary_key (bool):: True if field is Primary Key.

property constraints : dict¶

Returns a dict with constraints defined in the Pydantic/JSONSchema format.

Return type:¶: dict

field_type¶: alias of int

class tortoise.fields.data.JSONField(encoder=<function _orjson_dumps>, decoder=<built-in function loads>, **kwargs)[source]¶

JSON field.

This field can store dictionaries or lists of any JSON-compliant structure.

You can use generics to make static checking more friendly. Example: JSONField[dict[str, str]]

You can specify your own custom JSON encoder/decoder, leaving at the default should work well. If you have orjson installed, we default to using that, else the default json module will be used.

encoder:: The custom JSON encoder.
decoder:: The custom JSON decoder.

If you want to use Pydantic model as the field type for generating a better OpenAPI documentation, you can use field_type to specify the type of the field.

field_type:: The Pydantic model class.

class tortoise.fields.data.SmallIntField(primary_key: bool | None = None, *, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.SmallIntField(primary_key: bool | None = None, *, null: True, **kwargs: Any)

Small integer field. (16-bit signed)

primary_key (bool):: True if field is Primary Key.

property constraints : dict¶

Returns a dict with constraints defined in the Pydantic/JSONSchema format.

Return type:¶: dict

class tortoise.fields.data.TextField(primary_key=None, unique=False, db_index=False, **kwargs)[source]¶

Large Text field.

field_type¶: alias of str

class tortoise.fields.data.TimeDeltaField(*, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.TimeDeltaField(*, null: True, **kwargs: Any)

A field for storing time differences.

field_type¶: alias of timedelta

class tortoise.fields.data.TimeField(auto_now: bool = False, auto_now_add: bool = False, *, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.TimeField(auto_now: bool = False, auto_now_add: bool = False, *, null: True, **kwargs: Any)

Time field.

field_type¶: alias of time

class tortoise.fields.data.UUIDField(*, null: False = False, **kwargs: Any)[source]¶

class tortoise.fields.data.UUIDField(*, null: True, **kwargs: Any)

UUID Field

This field can store uuid value.

If used as a primary key, it will auto-generate a UUID4 by default.

field_type¶: alias of UUID

Relational Fields¶

tortoise.fields.relational.ForeignKeyField(to: type[Model] | str, related_name: str | None | False = None, on_delete: OnDelete = CASCADE, db_constraint: bool = True, *, null: True, **kwargs: Any) → ForeignKeyFieldInstance[MODEL] | None[source]¶

tortoise.fields.relational.ForeignKeyField(to: type[Model] | str, related_name: str | None | False = None, on_delete: OnDelete = CASCADE, db_constraint: bool = True, null: False = False, **kwargs: Any) → ForeignKeyFieldInstance[MODEL]

ForeignKey relation field.

This field represents a foreign key relation to another model.

See Foreign Key for usage information.

You must provide the following:

to:: The related model or name of the related model in a 'app.model' format.

The following is optional:

related_name:

The attribute name on the related model to reverse resolve the foreign key.

on_delete:

One of:

field.CASCADE:: Indicate that the model should be cascade deleted if related model gets deleted.
field.RESTRICT:: Indicate that the related model delete will be restricted as long as a foreign key points to it.
field.SET_NULL:: Resets the field to NULL in case the related model gets deleted. Can only be set if field has null=True set.
field.SET_DEFAULT:: Resets the field to default value in case the related model gets deleted. Can only be set is field has a default set.
field.NO_ACTION:: Take no action.

to_field:

The attribute name on the related model to establish foreign key relationship. If not set, pk is used

db_constraint:

Controls whether or not a constraint should be created in the database for this foreign key. The default is True, and that’s almost certainly what you want; setting this to False can be very bad for data integrity.

Return type:¶: Optional[ForeignKeyFieldInstance[Model]]

tortoise.fields.relational.ManyToManyField(to, through=None, forward_key=None, backward_key='', related_name='', on_delete=OnDelete.CASCADE, db_constraint=True, unique=True, **kwargs)[source]¶

ManyToMany relation field.

This field represents a many-to-many between this model and another model.

See Many to Many for usage information.

You must provide the following:

to:: The related model or name of the related model in a 'app.model' format.

The following is optional:

through:

The DB table that represents the through table. The default is normally safe.

forward_key:

The forward lookup key on the through table. The default is normally safe.

backward_key:

The backward lookup key on the through table. The default is normally safe.

related_name:

The attribute name on the related model to reverse resolve the many to many.

db_constraint:

Controls whether or not a constraint should be created in the database for this foreign key. The default is True, and that’s almost certainly what you want; setting this to False can be very bad for data integrity.

on_delete:

One of:

field.CASCADE:: Indicate that the model should be cascade deleted if related model gets deleted.
field.RESTRICT:: Indicate that the related model delete will be restricted as long as a foreign key points to it.
field.SET_NULL:: Resets the field to NULL in case the related model gets deleted. Can only be set if field has null=True set.
field.SET_DEFAULT:: Resets the field to default value in case the related model gets deleted. Can only be set is field has a default set.
field.NO_ACTION:: Take no action.

unique:

Controls whether or not a unique index should be created in the database to speed up select queries. The default is True. If you want to allow repeat records, set this to False.

Return type:¶: ManyToManyRelation[Any]

tortoise.fields.relational.OneToOneField(to: type[Model] | str, related_name: str | None | False = None, on_delete: OnDelete = CASCADE, db_constraint: bool = True, *, null: True, **kwargs: Any) → OneToOneFieldInstance[MODEL] | None[source]¶

tortoise.fields.relational.OneToOneField(to: type[Model] | str, related_name: str | None | False = None, on_delete: OnDelete = CASCADE, db_constraint: bool = True, null: False = False, **kwargs: Any) → OneToOneFieldInstance[MODEL]

OneToOne relation field.

This field represents a foreign key relation to another model.

See One to One for usage information.

You must provide the following:

to:: The related model or name of the related model in a 'app.model' format.

The following is optional:

related_name:

The attribute name on the related model to reverse resolve the foreign key.

on_delete:

One of:

field.CASCADE:: Indicate that the model should be cascade deleted if related model gets deleted.
field.RESTRICT:: Indicate that the related model delete will be restricted as long as a foreign key points to it.
field.SET_NULL:: Resets the field to NULL in case the related model gets deleted. Can only be set if field has null=True set.
field.SET_DEFAULT:: Resets the field to default value in case the related model gets deleted. Can only be set is field has a default set.
field.NO_ACTION:: Take no action.

to_field:

The attribute name on the related model to establish foreign key relationship. If not set, pk is used

db_constraint:

Controls whether or not a constraint should be created in the database for this foreign key. The default is True, and that’s almost certainly what you want; setting this to False can be very bad for data integrity.

Return type:¶: Optional[OneToOneFieldInstance[Model]]

DB Default Expressions¶

class tortoise.fields.db_defaults.Now[source]¶

Convenience subclass of SqlDefault that emits CURRENT_TIMESTAMP.

Example:

class MyModel(Model):
    created_at = fields.DatetimeField(db_default=Now())

class tortoise.fields.db_defaults.RandomHex[source]¶

Convenience subclass of SqlDefault that emits a dialect-specific expression for generating a random 32-character hex string.

Example:

class MyModel(Model):
    tracking_id = fields.CharField(max_length=36, db_default=RandomHex())

class tortoise.fields.db_defaults.SqlDefault(sql)[source]¶

Represents a raw SQL expression for use as a database-level default value.

Use this with the db_default parameter on fields to emit raw SQL in both generate_schemas() and migrations.

Warning

The SQL string is emitted verbatim into DDL statements. Never construct it from untrusted user input.

Example:

class MyModel(Model):
    created_at = fields.DatetimeField(db_default=SqlDefault("CURRENT_TIMESTAMP"))

DB Specific Fields¶

MySQL¶

class tortoise.contrib.mysql.fields.GeometryField(source_field=None, generated=False, primary_key=None, null=False, default=None, db_default=NOT_PROVIDED, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[source]¶

class tortoise.contrib.mysql.fields.UUIDField(binary_compression=True, **kwargs)[source]¶

UUID Field

This field can store uuid value, but with the option to add binary compression.

If used as a primary key, it will auto-generate a UUID4 by default.

binary_compression (bool):: If True, the UUID will be stored in binary format. This will save 6 bytes per UUID in the database. Note: that this is a MySQL-only feature. See https://dev.mysql.com/blog-archive/mysql-8-0-uuid-support/ for more details.

to_db_value(value, instance)[source]¶

Converts from the Python type to the DB type.

Parameters:¶

value¶

Current python value in model.

instance : type[tortoise.models.Model] | tortoise.models.Model¶

Model class or Model instance provided to look up.

Due to metacoding, to determine if this is an instance reliably, please do a:

if hasattr(instance, "_saved_in_db"):

Return type:¶

str | bytes | None

to_python_value(value)[source]¶

Converts from the DB type to the Python type.

Parameters:¶

value¶: Value from DB

Return type:¶

uuid.UUID | None

Postgres¶

class tortoise.contrib.postgres.fields.TSVectorField(source_fields=None, config=None, weights=None, stored=True, **kwargs)[source]¶

describe(serializable)[source]¶

Describes the field.

Parameters:¶

serializable¶: False if you want raw python objects, True for JSON-serializable data. (Defaults to True)

Return type:¶

dict

Returns:¶

A dictionary containing the field description.

(This assumes serializable=True, which is the default):

{
    "name":         str     # Field name
    "field_type":   str     # Field type
    "db_column":    str     # Name of DB column
                            #  Optional: Only for pk/data fields
    "raw_field":    str     # Name of raw field of the Foreign Key
                            #  Optional: Only for Foreign Keys
    "db_field_types": dict  # DB Field types for default and DB overrides
    "python_type":  str     # Python type
    "generated":    bool    # Is the field generated by the DB?
    "nullable":     bool    # Is the column nullable?
    "unique":       bool    # Is the field unique?
    "indexed":      bool    # Is the field indexed?
    "default":      ...     # The default value (coerced to int/float/str/bool/null)
    "description":  str     # Description of the field (nullable)
    "docstring":    str     # Field docstring (nullable)
}

When serializable=False is specified some fields are not coerced to valid JSON types. The changes are:

{
    "field_type":   Field   # The Field class used
    "python_type":  Type    # The actual Python type
    "default":      ...     # The default value as native type OR a callable
}

Extending A Field¶

It is possible to subclass fields allowing use of arbitrary types as long as they can be represented in a database compatible format. An example of this would be a simple wrapper around the CharField to store and query Enum types.

from enum import Enum
from typing import Type

from tortoise import ConfigurationError
from tortoise.fields import CharField


class EnumField(CharField):
    """
    An example extension to CharField that serializes Enums
    to and from a str representation in the DB.
    """

    def __init__(self, enum_type: Type[Enum], **kwargs):
        super().__init__(128, **kwargs)
        if not issubclass(enum_type, Enum):
            raise ConfigurationError("{} is not a subclass of Enum!".format(enum_type))
        self._enum_type = enum_type

    def to_db_value(self, value: Enum, instance) -> str:
        return value.value

    def to_python_value(self, value: str) -> Enum:
        try:
            return self._enum_type(value)
        except Exception:
            raise ValueError(
                "Database value {} does not exist on Enum {}.".format(value, self._enum_type)
            )

When subclassing, make sure that the to_db_value returns the same type as the superclass (in the case of CharField, that is a str) and that, naturally, to_python_value accepts the same type in the value parameter (also str).