atoti.Column.default_value

property Column.default_value: ConstantValue | 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.columns
...     },
...     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.columns
... }
{'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: ... Cannot make an array type non-nullable. ...

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