atoti.Column.default_value

property Column.default_value: bool | date | datetime | float | int | Sequence[int] | Sequence[float] | str | time | None

Value used to replace None inserted values.

If not None, the default value must match the column’s data_type. For instance, a LocalDate column cannot use the string "N/A" as its default value.

Each data type has its own default default_value value:

>>> from pprint import pprint
>>> table = session.create_table(
...     "Main data types",
...     types={
...         "boolean": tt.BOOLEAN,
...         "double": tt.DOUBLE,
...         "double[]": tt.DOUBLE_ARRAY,
...         "float": tt.FLOAT,
...         "float[]": tt.FLOAT_ARRAY,
...         "int": tt.INT,
...         "int[]": tt.INT_ARRAY,
...         "LocalDate": tt.LOCAL_DATE,
...         "LocalDateTime": tt.LOCAL_DATE_TIME,
...         "LocalTime": tt.LOCAL_TIME,
...         "long": tt.LONG,
...         "long[]": tt.LONG_ARRAY,
...         "String": tt.STRING,
...         "ZonedDateTime": tt.ZONED_DATE_TIME,
...     },
... )
>>> pprint(
...     {
...         column_name: table[column_name].default_value
...         for column_name in table
...     },
...     sort_dicts=False,
... )
{'boolean': False,
 'double': None,
 'double[]': None,
 'float': None,
 'float[]': None,
 'int': None,
 'int[]': None,
 'LocalDate': datetime.date(1970, 1, 1),
 'LocalDateTime': datetime.datetime(1970, 1, 1, 0, 0),
 'LocalTime': datetime.time(0, 0),
 'long': None,
 'long[]': None,
 'String': 'N/A',
 'ZonedDateTime': datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)}

Key columns cannot have None as their default value so it is forced to something else. For numeric scalar columns, this is zero:

>>> table = session.create_table(
...     "Numeric",
...     keys=["int", "float"],
...     types={
...         "int": tt.INT,
...         "float": tt.FLOAT,
...         "long": tt.LONG,
...         "double": tt.DOUBLE,
...     },
... )
>>> {column_name: table[column_name].default_value for column_name in table}
{'int': 0, 'float': 0.0, 'long': None, 'double': None}
>>> table += (None, None, None, None)
>>> table.head()
           long  double
int float
0   0.0    <NA>    <NA>

The default value of array columns is None and cannot be changed:

>>> session.create_table(  
...     "Array",
...     types={"long array": tt.LONG_ARRAY},
...     default_values={"long array": [0, 0]},
... )
Traceback (most recent call last):
    ...
py4j.protocol.Py4JJavaError: ... there is no global default value defined for this type. ...

Changing the default value from None to something else affects both the previously inserted None values and the upcoming ones:

>>> table["long"].default_value = 42
>>> table["long"].default_value
42
>>> table.head()
           long  double
int float
0   0.0      42    <NA>
>>> table += (1, None, None, None)
>>> table.head()
           long  double
int float
0   0.0      42    <NA>
1   0.0      42    <NA>

Once a column has a default value different than None, it cannot be changed anymore:

>>> table["long"].default_value = 1337
Traceback (most recent call last):
    ...
NotImplementedError: The default value is already not ``None`` and cannot be changed: recreate the table using the `default_values` parameter instead.
>>> table["long"].default_value
42
>>> del session.tables["Numeric"]
>>> table = session.create_table(
...     "Numeric",
...     keys=["int", "float"],
...     types={
...         "int": tt.INT,
...         "float": tt.FLOAT,
...         "long": tt.LONG,
...         "double": tt.DOUBLE,
...     },
...     default_values={"long": 1337},
... )
>>> table["long"].default_value
1337

The default value can also not be changed to None:

>>> table = session.create_table("Stringly", types={"String": tt.STRING})
>>> table["String"].default_value = None
Traceback (most recent call last):
    ...
NotImplementedError: The default value cannot be changed to `None`: recreate the table using the `default_values` parameter instead.
>>> table["String"].default_value
'N/A'
>>> del session.tables["Stringly"]
>>> table = session.create_table(
...     "Stringly",
...     types={"String": tt.STRING},
...     default_values={"String": None},
... )
>>> print(table["String"].default_value)
None