Create a datetime column specification for use in a schema.
Usage
The datetime_field() function defines the constraints and behavior for a datetime column when generating synthetic data with generate_dataset(). You can control the datetime range with min_date= and max_date=, enforce uniqueness with unique=True, and introduce null values with nullable=True and null_probability=.
Datetime values are generated uniformly (at second-level resolution) within the specified range. If no range is provided, the default range is 2000-01-01T00:00:00 to 2030-12-31T23:59:59. Both min_date= and max_date= accept datetime objects, date objects (which are converted to datetimes at midnight), or ISO 8601 datetime strings.
min_date: str | datetime | None = NoneMinimum datetime (inclusive). Can be an ISO format string (e.g., "2024-01-01T00:00:00"), a datetime.datetime object, or a datetime.date object. Default is None (defaults to 2000-01-01 00:00:00).
max_date: str | datetime | None = NoneMaximum datetime (inclusive). Can be an ISO format string, a datetime.datetime object, or a datetime.date object. Default is None (defaults to 2030-12-31 23:59:59).
nullable: bool = FalseWhether the column can contain null values. Default is False.
null_probability: float = 0.0Probability of generating a null value for each row when nullable=True. Must be between 0.0 and 1.0. Default is 0.0.
unique: bool = FalseWhether all values must be unique. Default is False. With second-level resolution over a wide range, collisions are unlikely for moderate dataset sizes.
generator: Callable[[], Any] | None = Noneunique= and nullable= still apply. The callable should take no arguments and return a single datetime.datetime value. It isn’t controlled by the seed= of generate_dataset(), so it needs its own seeded random number generator for reproducible data.
DatetimeField ValueErrormin_date is later than max_date, or if a datetime string cannot be parsed.
The min_date= and max_date= parameters accept datetime objects for precise range definitions:
import pointblank as pb
from datetime import datetime
schema = pb.Schema(
created_at=pb.datetime_field(
min_date=datetime(2024, 1, 1),
max_date=datetime(2024, 12, 31),
),
updated_at=pb.datetime_field(
min_date=datetime(2024, 6, 1),
max_date=datetime(2024, 12, 31),
),
)
pb.preview(pb.generate_dataset(schema, n=100, seed=23))PolarsRows100Columns2 |
||
created_at Datetime |
updated_at Datetime |
|
|---|---|---|
| 1 | 2024-02-17 16:33:53 | 2024-10-18 16:58:07 |
| 2 | 2024-11-14 21:21:34 | 2024-12-27 22:05:31 |
| 3 | 2024-12-29 14:40:05 | 2024-10-18 17:45:31 |
| 4 | 2024-12-05 21:08:23 | 2024-12-27 07:09:44 |
| 5 | 2024-02-14 09:38:39 | 2024-11-07 05:03:11 |
| 96 | 2024-12-10 00:21:07 | 2024-09-24 01:12:48 |
| 97 | 2024-11-05 10:23:02 | 2024-07-31 01:21:45 |
| 98 | 2024-04-07 14:52:22 | 2024-07-21 11:49:28 |
| 99 | 2024-02-07 05:34:29 | 2024-06-21 02:52:24 |
| 100 | 2024-04-10 21:16:58 | 2024-11-26 08:05:46 |
For a quick setup, ISO format strings work just as well:
schema = pb.Schema(
event_time=pb.datetime_field(
min_date="2024-03-01T08:00:00",
max_date="2024-03-01T18:00:00",
),
)
pb.preview(pb.generate_dataset(schema, n=30, seed=23))PolarsRows30Columns1 |
|
event_time Datetime |
|
|---|---|
| 1 | 2024-03-01 17:43:40 |
| 2 | 2024-03-01 11:59:13 |
| 3 | 2024-03-01 09:55:19 |
| 4 | 2024-03-01 09:19:42 |
| 5 | 2024-03-01 14:05:41 |
| 26 | 2024-03-01 11:29:59 |
| 27 | 2024-03-01 11:46:57 |
| 28 | 2024-03-01 16:47:38 |
| 29 | 2024-03-01 14:56:30 |
| 30 | 2024-03-01 09:21:50 |
Optional timestamps can be simulated with nullable=True, and datetime fields work nicely alongside other field types:
schema = pb.Schema(
order_id=pb.int_field(min_val=1000, max_val=9999, unique=True),
placed_at=pb.datetime_field(
min_date=datetime(2024, 1, 1),
max_date=datetime(2024, 12, 31),
),
shipped_at=pb.datetime_field(
min_date=datetime(2024, 1, 2),
max_date=datetime(2025, 1, 15),
nullable=True, null_probability=0.3,
),
)
pb.preview(pb.generate_dataset(schema, n=30, seed=7))PolarsRows30Columns3 |
|||
order_id Int64 |
placed_at Datetime |
shipped_at Datetime |
|
|---|---|---|---|
| 1 | 6166 | 2024-01-16 18:32:08 | 2024-07-21 20:24:26 |
| 2 | 9373 | 2024-11-24 12:56:24 | 2024-02-21 20:29:32 |
| 3 | 7458 | 2024-04-01 12:23:24 | 2024-04-12 09:02:35 |
| 4 | 6794 | 2024-12-02 14:53:31 | 2024-12-21 13:26:10 |
| 5 | 1134 | 2024-11-19 08:33:56 | 2025-01-11 21:54:07 |
| 26 | 7005 | 2024-10-06 18:14:09 | 2024-06-21 02:55:08 |
| 27 | 1190 | 2024-11-24 19:46:42 | 2024-11-18 17:42:24 |
| 28 | 3488 | 2024-10-17 14:06:03 | 2024-12-12 05:32:56 |
| 29 | 7086 | 2024-11-09 12:39:59 | None |
| 30 | 4109 | 2024-11-02 02:08:30 | 2024-08-08 13:14:56 |
About 30% of the shipped_at values are missing (13 of 30 here). Since each column is generated independently, some shipped_at values come before placed_at in the same row, so these columns aren’t suited for checks of date ordering without some extra processing.