Collection.ingest

def Collection.ingest(
    data: IngestionData,
    allow_existing: bool = True,
    *,
    show_progress: bool | Callable[[float], None] = False,
) -> list[UUID]

Ingest data into a collection.

Parameters

data IngestionData

The data to ingest.

Supported IngestionData data types are:

An iterable of mappings, with one mapping per datapoint.
A mapping from field names to ordered sequences, numpy.ndarray objects, or pandas.Series objects.
A pandas.DataFrame, with column names mapped to dataset fields.
An xarray.Dataset, with variables and coordinates mapped to dataset fields.

A mapping is always interpreted as column-oriented data. Wrap a single record in an iterable, such as [record]. Every datapoint must include time. Tilebox generates id and ingestion_time. Missing optional values leave their corresponding fields unset.

allow_existing bool

Datapoint fields are used to generate a deterministic unique UUID for each datapoint in a collection. Duplicate data points result in the same ID being generated. If allow_existing is True, ingest will skip those data points, since they already exist. If allow_existing is False, ingest will raise an error if any of the generated datapoint IDs already exist. Defaults to True.

show_progress bool | Callable[[float], None]

If True, display a progress bar while ingesting many datapoints. You can also pass a callback to receive progress values between 0 and 1. Defaults to False.

Returns

List of datapoint IDs that were ingested, including the IDs of existing data points in case of duplicates and allow_existing=True.

Request example

collection.ingest([
    {
        "time": "2023-05-01T12:00:00Z",
        "value": 1,
        "sensor": "A",
    },
    {
        "time": "2023-05-02T12:00:00Z",
        "value": 2,
        "sensor": "B",
    },
])

Errors

ArgumentError found existing datapoints with same id

If allow_existing is False and any of the datapoints attempting to ingest already exist.