tdfs4ds.benchmark¶
tdfs4ds.benchmark — dataset serving-latency benchmark + HTML report.
run_benchmark(dataset) measures client-perceived latency / throughput of a
tdfs4ds dataset view (single-key, batch, large-batch, concurrency, time-travel,
DBQL server-side), using raw teradatasql; build_benchmark_html /
write_benchmark_report render a self-contained HTML report.
module-attribute
¶
run_benchmark(dataset, entity_cols=None, *, sample_size=10000, skip=(), batch_sizes=(1, 5, 10, 50, 100, 500), large_sizes=(10000, 100000, 1000000), strategy_sizes=(500, 5000, 50000), concurrency=(1, 2, 4), time_travel_dates=(), max_in_list_keys=None, max_parse_ms=DEFAULT_MAX_PARSE_MS, batch_pushdown=True, conn_kwargs=None, progress=None)
Run the benchmark against dataset and return the report dict.
Parameters¶
dataset : str
Fully-qualified DB.dataset_view to benchmark.
entity_cols : list[str] | None
Grain/entity key columns. When None, auto-derived from the tdfs4ds
dataset catalog (needs an active teradataml context).
skip : set[str]
Any of {'parse','explain','warm','cold','batch','large_batch',
'batch_strategies','concurrent','time_travel','server_timing'} to skip.
max_parse_ms : float | None
The parse phase runs FIRST, before anything executes the view: it
times EXPLAIN SELECT * FROM <dataset> (parse + optimise, no
execution). When its median exceeds max_parse_ms the run stops
there — every request on such a view pays that cost before reading a
row, so the latency phases would mostly measure parsing and could take
very long. The report then explains why and what to try (the grouped
strategy). Default 5000 ms; None or 0 never stops.
strategy_sizes : tuple[int]
Batch sizes at which the batch_strategies phase compares the
in_list predicate vs the volatile_join retrieval side-by-side.
max_in_list_keys : int | None
Maximum number of keys put into an in_list predicate. When None
it is inferred from the entity-column count as
max(50, 500 // n_entity_cols) — wide composite keys produce large
per-key disjuncts whose parse time dominates the measurement, so the
cap keeps in_list batches cheap. It clamps batch_sizes and the
in_list arm of batch_strategies ONLY; the volatile_join arm
and large_batch keep their full sizes.
batch_pushdown : bool
True (default): the batch phases run what retrieve_batch runs -
the dataset's query regenerated with the keys inside every storage-table
read, so each FS_T_* table is read by primary index and only in the
partitions the keys fall in. False: the previous
SELECT * FROM <view> WHERE <keys> form, to measure the difference.
conn_kwargs : dict | None
Raw teradatasql kwargs; defaults to the TDFS4DS_TD_* environment.
progress : callable(str) | None
Receives one human-readable line per test phase (for a UI bar).
Returns the {"metadata":…, "results":…} report dict.
Probe the dataset's resolved columns → feature count + per-column types.
Resolution order: HELP COLUMN first (authoritative for VIEWS), DBC.ColumnsV fallback. 'features' are the non-entity columns; entity columns are the grain keys. Returns a metadata dict or {error:…}.
The HTML report of a benchmark (run_benchmark's result): a self-contained page with
inline SVG charts and CSS, no external JavaScript. Every section tolerates a phase that
is missing or failed. Use write_benchmark_report to save it to a file.
Render report to HTML and write it to disk; return the file path.
When out_path is None, writes under {tdfs4ds.BENCHMARK_REPORT_DIR}/ with
a timestamped, dataset-derived filename (directory created on demand).