Synthetic timeseries

synthetic-timeseries creates a read-only, SQL-queryable dynamic table (TableDynamic). Values are computed lazily in batches, not collected from a sensor or stored as an append-only physical series. It is a dynamic file factory, not a pond run executable or automatic collector.

Example configuration

start: "2024-01-01T00:00:00Z"  # Required: example inclusive start time.
end: "2024-01-01T03:00:00Z"    # Required: example inclusive end time.
interval: 1h                   # Required: example sample spacing.
time_column: timestamp         # Default: event-time column name.
points:                        # Required: output measurement definitions.
  - name: temperature          # Required: example measurement name.
    components:                # Required: components are summed.
      - type: line             # Required: select the linear component.
        slope: 0.001           # Example units/second; default is 0.0.
        offset: 20.0           # Example starting value; default is 0.0.

This is complete for the line variant. A periodic component instead has type: sine, triangle, or square, a required example period: 24h, and optional amplitude: 0.0, offset: 0.0, and phase: 0.0 (all defaults). Choose a nonzero amplitude to produce a varying periodic signal; phase is in radians. The full reference below lists each variant separately.

Runnable example

Prerequisites: Bash and pond on PATH; no credentials, services, or existing pond. Run the complete script from any directory. It creates a new scratch workspace and overrides POND locally; it never resets an existing pond.

start: "2024-01-01T00:00:00Z"
end: "2024-01-01T03:00:00Z"
interval: "1h"
time_column: timestamp
points:
  - name: temperature
    components:
      - type: line
        offset: 20.0
        slope: 0.001
#!/bin/bash
set -euo pipefail
SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
if [[ -n "${EXAMPLE_OUTPUT:-}" ]]; then
    mkdir "${EXAMPLE_OUTPUT}"
    WORK="$(cd "${EXAMPLE_OUTPUT}" && pwd)"
else
    WORK="$(mktemp -d "${TMPDIR:-/tmp}/watertown-synthetic.XXXXXX")"
fi
export POND="${WORK}/pond"

# docs:start create-and-query
pond init --birthplace documentation-example
pond mkdir /sensors
pond mknod synthetic-timeseries /sensors/synthetic --config-path "${SOURCE_DIR}/config.yaml"
pond cat /sensors/synthetic --format=table --sql \
    'SELECT COUNT(*) AS rows, MIN(timestamp) AS first_ts, MAX(timestamp) AS last_ts FROM source' \
    > "${WORK}/summary.txt"
pond cat /sensors/synthetic --format=table --sql \
    'SELECT timestamp, temperature FROM source ORDER BY timestamp' \
    > "${WORK}/values.txt"
# docs:end create-and-query
cat "${WORK}/summary.txt" "${WORK}/values.txt"
echo "Example output: ${WORK}"

The exact files above are executed by test 100. It asserts four rows, inclusive boundaries 00:00:00Z and 03:00:00Z, and temperatures 20, 23.6, 27.2, 30.8. See the timeseries guide.

Complete configuration, complete script, download package.

Full configuration

Settings

FieldAccepted typeRequiredDefaultDescription
endstringyesnot specifiedEnd time (RFC 3339 / ISO 8601)
intervalstringyesnot specifiedSampling interval as a human-readable duration (e.g., "15m", "1h", "30s")
pointsarray of Pointyesnot specifiedNamed timeseries points (each becomes a Float64 column)
startstringyesnot specifiedStart time (RFC 3339 / ISO 8601)
time_columnstringno"timestamp"Name of the timestamp column (default: "timestamp")

Point

A named timeseries point -- its value at each timestamp is the sum of its components

FieldAccepted typeRequiredDefaultDescription
componentsarray of Waveform Componentyesnot specifiedWaveform components whose values are summed
namestringyesnot specifiedColumn name for this point

Waveform Component

Waveform component type

Choose one of the following:

Sine wave

Sine wave: offset + amplitude * sin(2pi * t / period + phase)

FieldAccepted typeRequiredDefaultDescription
amplitudenumberno0.0Constraints: format="double".
offsetnumberno0.0Constraints: format="double".
periodstringyesnot specifiedPeriod as a human-readable duration (e.g., "24h", "1h30m", "90s")
phasenumberno0.0Phase offset in radians Constraints: format="double".
type"sine"yesnot specified

Triangle wave

Triangle wave: offset + amplitude * triangle(t / period + phase)

FieldAccepted typeRequiredDefaultDescription
amplitudenumberno0.0Constraints: format="double".
offsetnumberno0.0Constraints: format="double".
periodstringyesnot specified
phasenumberno0.0Constraints: format="double".
type"triangle"yesnot specified

Square wave

Square wave: offset + amplitude * sign(sin(2pi * t / period + phase))

FieldAccepted typeRequiredDefaultDescription
amplitudenumberno0.0Constraints: format="double".
offsetnumberno0.0Constraints: format="double".
periodstringyesnot specified
phasenumberno0.0Constraints: format="double".
type"square"yesnot specified

Linear ramp

Linear ramp: offset + slope * t_seconds

FieldAccepted typeRequiredDefaultDescription
offsetnumberno0.0Constraints: format="double".
slopenumberno0.0Constraints: format="double".
type"line"yesnot specified

Semantic constraints

start and end are RFC 3339 strings; the end is inclusive if reached by the positive interval. Require nonempty points/components and unique point names distinct from time_column. These constraints exceed JSON shape checks.

Timestamp output is Arrow Timestamp(Millisecond, UTC). Value columns are non-null Float64. Top-level and point objects reject unknown fields.

Waveforms

Each component has a required type: line, sine, triangle, or square. All numeric fields default to 0. Wave components require a duration-string period; use a positive duration. phase is radians, default 0. Waveform variant objects do not currently reject unknown fields.

TypeAdditional fieldsEvaluation with t in seconds since start
lineoffset, slopeoffset + slope * t; slope is units per second
sineperiod, amplitude, offset, phaseoffset + amplitude * sin(2*pi*t/period + phase)
trianglesame as sineStarts at offset - amplitude at zero phase; rises then falls each period
squaresame as sineoffset + amplitude * sign(sin(2*pi*t/period + phase))

Current limitation: malformed durations warn and fall back to one hour. Period positivity is not fully validated. Do not rely on that fallback; configuration schemas and validation corrections are tracked separately from this pilot.

Inspect

The script demonstrates pond mknod, then pond cat --sql. Use pond describe /sensors/synthetic to inspect its schema. Direct byte reads are unsupported: use SQL and --format=table, or export queryable data.

Update

To replace a configuration in a pond you own, use pond mknod synthetic-timeseries /sensors/synthetic --config-path CONFIG --overwrite. Subsequent queries regenerate values from that configuration; there is no ingestion cursor or incremental history to advance. No external API is called. Host-mounted dynamic factories are a separate execution path; this example tests explicit pond installation only.