ormar/docs/fields.md

Fields

There are 12 basic model field types and a special ForeignKey and Many2Many fields to establish relationships between models.

!!!tip For explanation of ForeignKey and Many2Many fields check relations.

Each of the Fields has assigned both sqlalchemy column class and python type that is used to create pydantic model.

Common Parameters

All Field types have a set of common parameters.

primary_key

primary_key: bool = False -> by default False.

Sets the primary key column on a table, foreign keys always refer to the pk of the Model.

Used in sql only.

autoincrement

autoincrement: bool = primary_key and type == int -> defaults to True if column is a primary key and of type Integer, otherwise False.

Can be only used with int/bigint fields.

If a field has autoincrement it becomes optional.

Used both in sql and pydantic (changes pk field to optional for autoincrement).

nullable

nullable: bool = not primary_key -> defaults to False for primary key column, and True for all other.

Specifies if field is optional or required, used both with sql and pydantic.

!!!note By default all ForeignKeys are also nullable, meaning the related Model is not required.

If you change the `ForeignKey` column to `nullable=False`, it becomes required.

!!!info If you want to know more about how you can preload related models during queries and how the relations work read the queries and relations sections.

default

default: Any = None -> defaults to None.

A default value used if no other value is passed.

In sql invoked on an insert, used during pydantic model definition.

If the field has a default value it becomes optional.

You can pass a static value or a Callable (function etc.)

Used both in sql and pydantic.

server default

server_default: Any = None -> defaults to None.

A default value used if no other value is passed.

In sql invoked on the server side so you can pass i.e. sql function (like now() or query/value wrapped in sqlalchemy text() clause).

If the field has a server_default value it becomes optional.

You can pass a static value or a Callable (function etc.)

Used in sql only.

Sample usage:

--8<-- "../docs_src/fields/docs004.py"

!!!warning server_default accepts str, sqlalchemy.sql.elements.ClauseElement or sqlalchemy.sql.elements.TextClause so if you want to set i.e. Integer value you need to wrap it in sqlalchemy.text() function like above

!!!tip You can pass also valid sql (dialect specific) wrapped in sqlalchemy.text()

For example `func.now()` above could be exchanged for `text('(CURRENT_TIMESTAMP)')` for sqlite backend

!!!info server_default is passed straight to sqlalchemy table definition so you can read more in server default sqlalchemy documentation

index

index: bool = False -> by default False,

Sets the index on a table's column.

Used in sql only.

unique

unique: bool = False

Sets the unique constraint on a table's column.

Used in sql only.

pydantic_only

pydantic_only: bool = False

Prevents creation of a sql column for given field.

Used for data related to given model but not to be stored in the database.

Used in pydantic only.

choices

choices: Sequence = []

A set of choices allowed to be used for given field.

Used for data validation on pydantic side.

Prevents insertion of value not present in the choices list.

Used in pydantic only.

Fields Types

String

String(max_length, allow_blank: bool = True, strip_whitespace: bool = False, min_length: int = None, max_length: int = None, curtail_length: int = None, regex: str = None,) has a required max_length parameter.

• Sqlalchemy column: sqlalchemy.String
• Type (used for pydantic): str

!!!tip For explanation of other parameters check pydantic documentation.

Text

Text(allow_blank: bool = True, strip_whitespace: bool = False) has no required parameters.

• Sqlalchemy column: sqlalchemy.Text
• Type (used for pydantic): str

!!!tip For explanation of other parameters check pydantic documentation.

Boolean

Boolean() has no required parameters.

• Sqlalchemy column: sqlalchemy.Boolean
• Type (used for pydantic): bool

Integer

Integer(minimum: int = None, maximum: int = None, multiple_of: int = None) has no required parameters.

• Sqlalchemy column: sqlalchemy.Integer
• Type (used for pydantic): int

!!!tip For explanation of other parameters check pydantic documentation.

BigInteger

BigInteger(minimum: int = None, maximum: int = None, multiple_of: int = None) has no required parameters.

• Sqlalchemy column: sqlalchemy.BigInteger
• Type (used for pydantic): int

!!!tip For explanation of other parameters check pydantic documentation.

Float

Float(minimum: float = None, maximum: float = None, multiple_of: int = None) has no required parameters.

• Sqlalchemy column: sqlalchemy.Float
• Type (used for pydantic): float

!!!tip For explanation of other parameters check pydantic documentation.

Decimal

Decimal(minimum: float = None, maximum: float = None, multiple_of: int = None, precision: int = None, scale: int = None, max_digits: int = None, decimal_places: int = None) has no required parameters

You can use either length and precision parameters or max_digits and decimal_places.

• Sqlalchemy column: sqlalchemy.DECIMAL
• Type (used for pydantic): decimal.Decimal

!!!tip For explanation of other parameters check pydantic documentation.

Date

Date() has no required parameters.

• Sqlalchemy column: sqlalchemy.Date
• Type (used for pydantic): datetime.date

Time

Time() has no required parameters.

• Sqlalchemy column: sqlalchemy.Time
• Type (used for pydantic): datetime.time

DateTime

DateTime() has no required parameters.

• Sqlalchemy column: sqlalchemy.DateTime
• Type (used for pydantic): datetime.datetime

JSON

JSON() has no required parameters.

• Sqlalchemy column: sqlalchemy.JSON
• Type (used for pydantic): pydantic.Json

UUID

UUID(uuid_format: str = 'hex') has no required parameters.

• Sqlalchemy column: ormar.UUID based on sqlalchemy.CHAR(36) or sqlalchemy.CHAR(32) field (for string or hex format respectively)
• Type (used for pydantic): uuid.UUID

uuid_format parameters allow 'hex'(default) or 'string' values.

Depending on the format either 32 or 36 char is used in the database.

Sample:

• 'hex' format value = "c616ab438cce49dbbf4380d109251dce" (CHAR(32))
• 'string' value = "c616ab43-8cce-49db-bf43-80d109251dce" (CHAR(36))

When loaded it's always python UUID so you can compare it and compare two formats values between each other.