Skip to content

territory

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

!!!tip Description of ForeignKey and ManyToMany field check relationships.

Each field is assigned the sqlalchemy column class and the python type used to create the pydantic model.

field type

string

String(max_length: int, min_length: int = None, regex: str = None,) There is a required max_length parameter.

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

!!!tip For descriptions of other parameters, see the pydantic documentation.

text

Text() has no required parameters.

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

!!!tip For descriptions of other parameters, see the pydantic documentation.

Boolean value

Boolean() has no required parameters.

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

integer

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

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

!!!tip For descriptions of other parameters, see the pydantic documentation.

large integer

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

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

!!!tip For descriptions of other parameters, see the pydantic documentation.

small integer

SmallInteger(minimum: int = None, maximum: int = None, multiple_of: int = None) There are no required parameters.

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

!!!tip For descriptions of other parameters, see the pydantic documentation.

float

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

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

!!!tip For descriptions of other parameters, see the pydantic documentation.

decimalism

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) No required parameters

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

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

!!!tip For descriptions of other parameters, see the pydantic documentation.

date

Date() has no required parameters.

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

time

Time(timezone: bool = False) No required parameters.

You can pass timezone=True for time-zone aware database columns.

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

date and time

DateTime(timezone: bool = False) There are no required parameters.

You can pass timezone=True for time-zone aware database columns.

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

JSON

JSON() has no required parameters.

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

large binary file

LargeBinary(max_length) has a required max_length parameter.

  • Sqlalchemy column: sqlalchemy.LargeBinary
  • Type (for pydantic): bytes

LargeBinary length is used in some backends (i.e. mysql) to determine the size of a field, in others it is simply ignored, but in ormar it is always required. It should be the maximum size of the file/byte (in bytes).

LargeBinary also has an optional represent_as_base64_str: bool = False flag. When set to TrueOrmar, byte values are automatically converted to Base64 encoded strings, and you can also set values by passing Base64 encoded strings.

This allows you to set values through the API, even if the values are not compatible with utf-8 or fail during json conversion.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import base64
... # other imports skipped for brevity


base_ormar_config = ormar.OrmarConfig(
    metadata=metadata
    database=database
)


class LargeBinaryStr(ormar.Model):
    ormar_config = base_ormar_config.copy(tablename="my_str_blobs")

    id: int = ormar.Integer(primary_key=True)
    test_binary: str = ormar.LargeBinary(
        max_length=100000, represent_as_base64_str=True
    )

# set non utf-8 compliant value - note this can be passed by api (i.e. fastapi) in json
item = LargeBinaryStr(test_binary=base64.b64encode(b"\xc3\x28").decode())

assert item.test_binary == base64.b64encode(b"\xc3\x28").decode()

# technical note that underlying value is still bytes and will be saved as so
assert item.__dict__["test_binary"] == b"\xc3\x28"

universally unique identifier

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

  • Sqlalchemy column: ormar.UUID based on sqlalchemy.CHAR(36) or sqlalchemy.CHAR(32) fields (string or hexadecimal format, respectively)
  • Type (for pydantic): uuid.UUID

The uuid_format parameter allows Hex (default) or String values.

Depending on the format, 32 or 36 characters are used in the database.

Sample:

  • "hexadecimal" format value =c616ab438cce49dbbf4380d109251dce(characters (32))
  • "string" value =c616ab43-8cce-49db-bf43-80d109251dce(character (36))

It is always a python UUID when loaded, so you can compare it and compare values between the two format values.

enumeration

There are two ways to use enumeration in ormar ->, one is to use a dedicated enumeration field of sqlalchemy.Enum column type, and the other is to set selection on any field in ormar.

The Enum field uses the database dialect specific Enum column type (if available), but falls back to varchar if this field type is not available.

The selection option always follows the selected database field type.

Therefore, which one to use depends on the backend you are using and the column/data type you want to use in the enumeration field.

enumeration-field

Enum(enum_class=Type[Enum]) has a required enum_class parameter.

  • Sqlalchemy column: sqlalchemy.Enum
  • Type (for pydantic): Type[Enum]