API Reference¶

Load and validate InfluxDB settings from TOML.

Parameters¶

path : str | Path | None, default=None Path to a TOML settings file. If None, uses settings.toml in the current working directory.

Returns¶

InfluxSettings Validated settings object.

Raises¶

FileNotFoundError If the settings file does not exist. ValueError If required keys are missing or contain invalid values.

Write a settings TOML file for DeteQT.

Parameters¶

url : str InfluxDB HTTP(S) base URL. org : str InfluxDB organization. bucket : str InfluxDB bucket. token : str InfluxDB token (typically write token for users). timeout_ms : int, default=30000 Client timeout for writes, in milliseconds. path : str | Path, default="settings.toml" Target TOML path to create. default_tags : Mapping[str, str] | None, default=None Optional default tags written under [defaults.tags]. overwrite : bool, default=False If False and target already exists, raise FileExistsError.

Returns¶

Path Path to the written settings file.

Raises¶

FileExistsError If target exists and overwrite is False. ValueError If required values or default_tags are invalid.

Write one QOI point.

Parameters¶

record : Mapping[str, object] One record dictionary using the same schema as write_batch. Use extra_tags and extra_fields keys in the record for optional user-defined tags/fields. settings_path : str | Path | None, default=None Optional path to settings TOML. Defaults to settings.toml.

Returns¶

dict[str, object] Write summary with records_total, records_written, and records_failed.

Write multiple QOI records.

Parameters¶

records : Iterable[Mapping[str, object]] Record dictionaries using standard keys and optional extra_tags / extra_fields. settings_path : str | Path | None, default=None Optional path to settings TOML. continue_on_error : bool, default=False If True, continue writing after per-record failures. chunk_size : int, default=500 Number of records per write request. return_errors : bool, default=False If True, include a per-record errors list in the summary.

Returns¶

dict[str, object] Summary counters: records_total, records_written, and records_failed. If return_errors is True, includes errors as list[dict[str, object]].

Print and return QoI-to-snapshot matching plan for recursive ingest.

Parameters¶

folder : str | Path Folder scanned recursively.

Returns¶

list[dict[str, str | None]] List with qoi_path and snapshot_path (or None if unmatched).

Recursively load raw records from files in a folder.

Parameters¶

folder : str | Path Folder to scan recursively. continue_on_error : bool, default=True If True, skip unreadable files and continue.

Returns¶

list[dict[str, object]] Raw loaded records.

Raises¶

FileNotFoundError If folder does not exist.

Normalize and validate raw records before writing.

Parameters¶

raw_data : Sequence[Mapping[str, object]] Raw records from ingest_data. keep_keys : Sequence[str] | None, default=None Keys to keep from each record. If None, standard keys are used. continue_on_error : bool, default=False If True, skip invalid records and continue.

Returns¶

list[dict[str, object]] Processed records ready for write_batch.

Raises¶

ValueError If a record is invalid and continue_on_error is False.

Ingest, process, and write records in one call.

Parameters¶

folder : str | Path Folder to scan recursively. keep_keys : Sequence[str] | None, default=None Keys to keep before writing. settings_path : str | Path | None, default=None Optional settings TOML path. continue_on_error : bool, default=True If True, continue after per-file, per-record, and write failures. chunk_size : int, default=500 Number of records per write request. Smaller values give faster progress feedback but produce more HTTP requests.

Returns¶

dict[str, object] Write summary plus raw_records_total and processed_records_total.

Load one JSON file and normalize it into standard record dictionaries.

Parameters¶

path : str | Path Path to a JSON file.

Returns¶

list[dict[str, object]] Normalized records.

Raises¶

ValueError If JSON payload cannot be normalized into records. json.JSONDecodeError If file content is not valid JSON.

Build a Flux query string.

Parameters¶

bucket : str InfluxDB bucket name. start : str, default="-1h" Flux start time expression. stop : str | None, default=None Optional Flux stop time expression. measurement : str | None, default=None Optional measurement filter. If None, all measurements are queried. fields : Sequence[str] | None, default=None Optional field names to include. tags : Mapping[str, str] | None, default=None Optional tag equality filters. columns : Sequence[str] | None, default=None Optional keep column list. limit : int | None, default=None Optional row limit. sort_desc : bool, default=False If True, sort by _time descending.

Returns¶

str Flux query string.

Raises¶

ValueError If bucket or start are empty, or limit is not greater than 0.

Run a raw Flux query and return all rows.

Run a raw Flux query and return rows plus query metadata.

Stream rows for a raw Flux query as an iterator.

Run a structured query and return all rows.

Parameters¶

settings_path : str | Path | None, default=None Optional path to settings TOML. bucket : str | None, default=None Optional bucket override. Defaults to value from settings. start : str, default="-1h" Flux start time expression. stop : str | None, default=None Optional Flux stop time expression. measurement : str | None, default=None Optional measurement filter. fields : Sequence[str] | None, default=None Optional field list filter. tags : Mapping[str, str] | None, default=None Optional tag equality filters. columns : Sequence[str] | None, default=None Optional keep-column list. limit : int | None, default=None Optional row limit. sort_desc : bool, default=False If True, sort by _time descending.

Returns¶

list[dict[str, object]] Query result rows.

Run a structured query and return rows plus query metadata.

Stream rows for a structured query as an iterator.