marpledata 3.4.0.dev1__tar.gz → 3.6.0.dev1__tar.gz

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/.gitignore

@@ -169,4 +169,7 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
-*.env
+.env*
+
+# Client handoff pack (may contain a real API token)
+/marple-matlab/

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/AGENTS.md

@@ -15,6 +15,7 @@ This directory contains the Python SDK package published as `marpledata`.
 ## Commands
 
 - Run tests with output: `uv run pytest -vs`
+- Unit tests only: `uv run pytest -m "not integration"`
 - Build docs: `uv run --group docs sphinx-build -b html docs docs/_build/html`
 - Build package: `uv build`
 - Fix formatting: `uv run isort src tests && uv run black src tests`
@@ -29,4 +30,6 @@ Run commands from `python/` unless a command explicitly says otherwise.
 - Keep Python SDK tests in `python/tests/`.
 - Integration tests run against live Marple services and may require
   `MDB_TOKEN`, `MDB_URL`, `INSIGHT_TOKEN`, and `INSIGHT_URL`. Tests should skip
-  or fail clearly when required credentials are missing.
+  clearly when required credentials are missing. Mark live tests with
+  `pytest.mark.integration`.
+- Release steps: `RELEASING.md`.

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/CHANGELOG.md

@@ -5,7 +5,32 @@ All notable changes to the Python SDK package `marpledata` will be documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [3.4.0] - 2026-07-16
+## [Unreleased]
+
+### Changed
+
+- Exact signal names in `get_data` / `get_signal` / `get_signals` resolve via the dataset cache or `GET /datapool/{pool}/signal/{name}/id` instead of downloading the full datapool `signal_map`. Regex patterns still use the map.
+
+### Added
+
+- `DB.delete_signals`, `Dataset.delete_signal` / `Dataset.delete_signals`, and `Signal.delete` to remove signals from a dataset.
+
+### Fixed
+
+- Allow `add_signal` in post-processing
+
+## [3.5.0] - 2026-08-20
+
+### Added
+
+- `Dataset.add_signal` and `Dataset.add_signals` now accept a time-indexed pandas Series or DataFrame (DatetimeIndex / TimedeltaIndex when there is no `time` column).
+- `DataStream.push_file(..., overwrite=False)` to replace an existing dataset with the same name (also on the deprecated `DB.push_file`).
+
+### Fixed
+
+- An empty local parquet cache folder is treated as a cache miss and re-downloaded, instead of being assumed to mean the signal has no data.
+
+## [3.4.0] - 2026-07-28
 
 ### Added
 

marpledata-3.6.0.dev1/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+## Development (Python)
+
+### Formatting, linting, and typing
+
+Checks run on `src/` and `tests/` in GitLab CI (`python:lint`, `python:typing`).
+
+Fix formatting locally:
+
+```bash
+uv run isort src tests
+uv run black src tests
+```
+
+Verify (mirror CI):
+
+```bash
+uv run isort src tests --check --diff
+uv run flake8 --config .flake8 src tests
+uv run black --check src tests
+uv run mypy --install-types --non-interactive
+```
+
+### Testing
+
+The testing suite includes local unit tests and integration tests against a live Marple DB / Insight deployment. Integration tests share one imported example dataset per session, use a small CSV for extra ingestions, and mark themselves with `pytest.mark.integration`.
+
+```bash
+uv run pytest -m "not integration"   # local unit tests only
+export MDB_TOKEN=...
+export INSIGHT_TOKEN=...
+# Optional, defaults to SaaS URLs:
+export MDB_URL=https://db.marpledata.com/api/v1
+export INSIGHT_URL=https://insight.marpledata.com/api/v1
+uv run pytest -vs
+```
+
+### Documentation
+
+Build the Sphinx docs locally:
+
+```bash
+uv sync --group docs
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+Open `docs/_build/html/index.html` in your browser to view the site.
+
+### Local build
+
+- `uv build`
+- `uv run pip install dist/*.whl` (Install in your local .venv)
+- `uv run python`
+  - `import marple`
+  - `marple.__version__`
+  - `from marple import Insight, DB`
+
+### Publishing
+
+See [`RELEASING.md`](RELEASING.md).

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: marpledata
-Version: 3.4.0.dev1
+Version: 3.6.0.dev1
 Summary: Marple SDK for Python
 Project-URL: Homepage, https://www.marpledata.com/
 Project-URL: Documentation, https://marpledata.gitlab.io/marple-sdk/
@@ -52,7 +52,7 @@ from marple import DB      # Marple DB
 from marple import Insight # Marple Insight
 ```
 
-For release notes, see [`CHANGELOG.md`](CHANGELOG.md).
+For release notes, see [`CHANGELOG.md`](CHANGELOG.md). To publish a release, see [`RELEASING.md`](RELEASING.md).
 
 ## Marple DB
 
@@ -90,34 +90,40 @@ dataset = dataset.wait_for_import(timeout=10)
 #### Add signals to an imported dataset
 
 Upload additional signals (for example derived channels) on an existing dataset.
-Each signal is a DataFrame, Arrow table, or on-disk parquet matching `LAKE_ARROW_SCHEMA`:
-columns `time` (int64 nanoseconds) plus `value` and/or `value_text`.
+DataFrames, Arrow tables, and on-disk parquet use `LAKE_ARROW_SCHEMA`: columns
+`time` (int64 nanoseconds) plus `value` and/or `value_text`.
 Times must overlap the dataset time range. Use `overwrite=True` to replace an existing signal name;
 a conflict without overwrite raises `SignalsAlreadyExistError`.
 
-```python
-import pandas as pd
-from marple.db import LAKE_ARROW_SCHEMA  # time + value and/or value_text
+A Series, or a DataFrame without a `time` column, takes its times from a `DatetimeIndex` or
+`TimedeltaIndex`. Indexed DataFrames must still have a `value` and/or `value_text` column.
 
-speed = dataset.get_signal("car.speed").get_data()
-derived = pd.DataFrame({
-    "time": speed.index.asi8,
-    "value": speed["value"] * 3.6,
-})
+```python
 # Single signal: wait until available before reading
+speed = dataset.get_signal("car.speed").get_data()
 signal = dataset.add_signal(
     "car.speed_kmh",
-    derived,
+    speed * 3.6,
     metadata={"unit": "km/h"},
 ).wait_until_available()
 
 # Batch: returns IDs as soon as upload completes (no wait)
 ids = dataset.add_signals([
-    {"name": "car.speed_kmh", "data": derived, "metadata": {"unit": "km/h"}},
+    {"name": "car.speed_kmh", "data": speed * 3.6, "metadata": {"unit": "km/h"}},
 ], overwrite=True, concurrency=4)
 signals = dataset.get_signals(signal_ids=ids)
 ```
 
+Data assembled from scratch uses the explicit schema columns instead:
+
+```python
+import pandas as pd
+from marple.db import LAKE_ARROW_SCHEMA  # time + value and/or value_text
+
+samples = pd.DataFrame({"time": [t0, t0 + 1_000_000_000], "value": [1.0, 2.0]})
+dataset.add_signal("car.custom", samples)
+```
+
 #### Upload large files
 
 `stream.push_file(...)` starts an ingestion and lets the Marple DB API choose the best upload mode. Depending on the deployment and file size, the SDK can upload through the API server, upload directly to Azure Blob Storage, use a single presigned URL, or split the file into multipart uploads.
@@ -203,7 +209,8 @@ if len(datasets) > 0:
 
 - **List streams**: `db.get_streams()`
 - **List datasets in a stream**: `stream.get_datasets()`
-- **Upload a file to a file-stream**: `stream.push_file(file_path, metadata={...}, concurrency=4)`
+- **Upload a file (file stream, default)**: `stream.push_file(file_path, metadata={...}, concurrency=4)`
+- **Custom lake ingest (file stream)**: `stream.add_dataset(...)` then `dataset.add_signal(...)` / `add_signals([...])`
 - **Add signals to a dataset**: `dataset.add_signal(name, data, ...)` / `dataset.add_signals([...])` — data matches `LAKE_ARROW_SCHEMA` (`time` + `value` and/or `value_text`)
 - **Wait until a signal is available**: `signal.wait_until_available(timeout=60)`
 - **Fetch signals by ID**: `dataset.get_signals(signal_ids=[...], refresh=False)`
@@ -213,13 +220,14 @@ if len(datasets) > 0:
 - **Get a resampled df of multiple signals**: `dataset.get_data(signals=[...], resample_rule="1s")`
 - **Delete a stream**: `stream.delete()` or `db.delete_stream(stream_key)`
 - **Delete a dataset**: `dataset.delete()` or `db.delete_dataset(dataset_id, dataset_path)`
+- **Delete signals**: `signal.delete()`, `dataset.delete_signal(signal_id)` / `dataset.delete_signals(signal_ids)`, or `db.delete_signals(dataset_id, dataset_path, signal_ids)`
 
-For live/realtime streams (creating and appending data):
+For live streams:
 
 - **Create an empty dataset**: `stream.add_dataset(dataset_name, metadata=None)`
 - **Upsert signal definitions**: `dataset.upsert_signals(signals=[...])`
 - **Append timeseries data**: `dataset.append(data=df, shape="long"|"wide"|None)`
-- **Cool a realtime dataset**: `dataset.cool()` then `dataset.wait_for_import()` to wait until `FINISHED`
+- **Cool to cold storage**: `dataset.cool()` then `dataset.wait_for_import()` until `FINISHED`
 
 ### Calling endpoints directly
 

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/README.md

@@ -17,7 +17,7 @@ from marple import DB      # Marple DB
 from marple import Insight # Marple Insight
 ```
 
-For release notes, see [`CHANGELOG.md`](CHANGELOG.md).
+For release notes, see [`CHANGELOG.md`](CHANGELOG.md). To publish a release, see [`RELEASING.md`](RELEASING.md).
 
 ## Marple DB
 
@@ -55,34 +55,40 @@ dataset = dataset.wait_for_import(timeout=10)
 #### Add signals to an imported dataset
 
 Upload additional signals (for example derived channels) on an existing dataset.
-Each signal is a DataFrame, Arrow table, or on-disk parquet matching `LAKE_ARROW_SCHEMA`:
-columns `time` (int64 nanoseconds) plus `value` and/or `value_text`.
+DataFrames, Arrow tables, and on-disk parquet use `LAKE_ARROW_SCHEMA`: columns
+`time` (int64 nanoseconds) plus `value` and/or `value_text`.
 Times must overlap the dataset time range. Use `overwrite=True` to replace an existing signal name;
 a conflict without overwrite raises `SignalsAlreadyExistError`.
 
-```python
-import pandas as pd
-from marple.db import LAKE_ARROW_SCHEMA  # time + value and/or value_text
+A Series, or a DataFrame without a `time` column, takes its times from a `DatetimeIndex` or
+`TimedeltaIndex`. Indexed DataFrames must still have a `value` and/or `value_text` column.
 
-speed = dataset.get_signal("car.speed").get_data()
-derived = pd.DataFrame({
-    "time": speed.index.asi8,
-    "value": speed["value"] * 3.6,
-})
+```python
 # Single signal: wait until available before reading
+speed = dataset.get_signal("car.speed").get_data()
 signal = dataset.add_signal(
     "car.speed_kmh",
-    derived,
+    speed * 3.6,
     metadata={"unit": "km/h"},
 ).wait_until_available()
 
 # Batch: returns IDs as soon as upload completes (no wait)
 ids = dataset.add_signals([
-    {"name": "car.speed_kmh", "data": derived, "metadata": {"unit": "km/h"}},
+    {"name": "car.speed_kmh", "data": speed * 3.6, "metadata": {"unit": "km/h"}},
 ], overwrite=True, concurrency=4)
 signals = dataset.get_signals(signal_ids=ids)
 ```
 
+Data assembled from scratch uses the explicit schema columns instead:
+
+```python
+import pandas as pd
+from marple.db import LAKE_ARROW_SCHEMA  # time + value and/or value_text
+
+samples = pd.DataFrame({"time": [t0, t0 + 1_000_000_000], "value": [1.0, 2.0]})
+dataset.add_signal("car.custom", samples)
+```
+
 #### Upload large files
 
 `stream.push_file(...)` starts an ingestion and lets the Marple DB API choose the best upload mode. Depending on the deployment and file size, the SDK can upload through the API server, upload directly to Azure Blob Storage, use a single presigned URL, or split the file into multipart uploads.
@@ -168,7 +174,8 @@ if len(datasets) > 0:
 
 - **List streams**: `db.get_streams()`
 - **List datasets in a stream**: `stream.get_datasets()`
-- **Upload a file to a file-stream**: `stream.push_file(file_path, metadata={...}, concurrency=4)`
+- **Upload a file (file stream, default)**: `stream.push_file(file_path, metadata={...}, concurrency=4)`
+- **Custom lake ingest (file stream)**: `stream.add_dataset(...)` then `dataset.add_signal(...)` / `add_signals([...])`
 - **Add signals to a dataset**: `dataset.add_signal(name, data, ...)` / `dataset.add_signals([...])` — data matches `LAKE_ARROW_SCHEMA` (`time` + `value` and/or `value_text`)
 - **Wait until a signal is available**: `signal.wait_until_available(timeout=60)`
 - **Fetch signals by ID**: `dataset.get_signals(signal_ids=[...], refresh=False)`
@@ -178,13 +185,14 @@ if len(datasets) > 0:
 - **Get a resampled df of multiple signals**: `dataset.get_data(signals=[...], resample_rule="1s")`
 - **Delete a stream**: `stream.delete()` or `db.delete_stream(stream_key)`
 - **Delete a dataset**: `dataset.delete()` or `db.delete_dataset(dataset_id, dataset_path)`
+- **Delete signals**: `signal.delete()`, `dataset.delete_signal(signal_id)` / `dataset.delete_signals(signal_ids)`, or `db.delete_signals(dataset_id, dataset_path, signal_ids)`
 
-For live/realtime streams (creating and appending data):
+For live streams:
 
 - **Create an empty dataset**: `stream.add_dataset(dataset_name, metadata=None)`
 - **Upsert signal definitions**: `dataset.upsert_signals(signals=[...])`
 - **Append timeseries data**: `dataset.append(data=df, shape="long"|"wide"|None)`
-- **Cool a realtime dataset**: `dataset.cool()` then `dataset.wait_for_import()` to wait until `FINISHED`
+- **Cool to cold storage**: `dataset.cool()` then `dataset.wait_for_import()` until `FINISHED`
 
 ### Calling endpoints directly
 

marpledata-3.6.0.dev1/RELEASING.md

@@ -0,0 +1,13 @@
+# Releasing `marpledata`
+
+Tokens: 1Password (`username: __token__`). Run from `python/`.
+
+- **Bump version**
+  - `uv version --bump minor` / `uv version x.y.z`
+  - Manual update `__init__.py`, `CHANGELOG.md`
+- **TestPyPI** — `rm -rf dist && uv build && uv publish --index testpypi`
+  Smoke: `pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple marpledata==<version>`
+- **PyPI** — `rm -rf dist && uv build && uv publish`
+- **Docs** — run the GitLab `pages` job (Sphinx → https://marpledata.gitlab.io/marple-sdk/)
+
+No GitHub tag/release; `CHANGELOG.md` is the release history.

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/docs/api/marple.db.Signal.rst

@@ -16,7 +16,7 @@
       ~Signal.cache_parquet
       ~Signal.get_data
       ~Signal.list_parquet_files
-      ~Signal.wait_until_cold
+      ~Signal.wait_until_available
    
    
 

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/docs/api/marple.db.SignalUpload.rst

@@ -26,7 +26,6 @@
       ~SignalUpload.name
       ~SignalUpload.data
       ~SignalUpload.metadata
-      ~SignalUpload.overwrite
       ~SignalUpload.priority
    
    

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/docs/getting-started.rst

@@ -37,8 +37,9 @@ Marple DB quickstart
    dataset = dataset.wait_for_import(timeout=10)
 
 After import, you can add derived signals with
-``dataset.add_signal(...)`` / ``dataset.add_signals([...])``. See
-:doc:`tutorials` for a full example.
+``dataset.add_signal(...)`` / ``dataset.add_signals([...])``. For custom
+ingest without file parsing, use ``stream.add_dataset(...)`` then
+``add_signal``. See :doc:`tutorials` for a full example.
 
 ``stream.push_file(...)`` starts an ingestion and lets the Marple DB API choose
 the best upload mode for the deployment and file size. For large files, use a
@@ -49,6 +50,13 @@ longer ``wait_for_import`` timeout and optionally increase upload concurrency:
    dataset = stream.push_file("large_export.csv", concurrency=8)
    dataset = dataset.wait_for_import(timeout=180)
 
+To replace an existing dataset with the same name, pass ``overwrite=True``:
+
+.. code-block:: python
+
+   dataset = stream.push_file("examples_race.csv", overwrite=True)
+   dataset = dataset.wait_for_import(timeout=10)
+
 If direct storage uploads are blocked by your network or proxy, force upload
 through the Marple DB API server:
 

marpledata-3.6.0.dev1/docs/tutorials.rst

@@ -0,0 +1,128 @@
+Tutorials
+=========
+
+These examples use the high-level ``DataStream``, ``Dataset``, and ``Signal``
+APIs. Create a stream and API token in Marple DB first.
+
+Setup
+-----
+
+.. code-block:: python
+
+   import os
+   import re
+
+   import pandas as pd
+
+   from marple import DB
+
+   db = DB(os.environ["MDB_TOKEN"])
+   stream = db.get_stream("Car data")
+
+For VPC or self-hosted deployments, pass ``os.environ["MDB_URL"]`` as the
+second argument to ``DB``.
+
+Import a file and wait for import
+---------------------------------
+
+.. code-block:: python
+
+   dataset = stream.push_file(
+       "examples_race.csv",
+       metadata={"source": "testbench"},
+       concurrency=8,
+       overwrite=False,
+   ).wait_for_import(timeout=180)
+
+Pass ``overwrite=True`` to replace an existing dataset with the same name.
+
+Add signals to a dataset
+------------------------
+
+Add signals after import, or start with an empty dataset using
+``stream.add_dataset``. Input follows :data:`marple.db.LAKE_ARROW_SCHEMA`:
+``time`` (int64 nanoseconds) plus ``value`` and/or ``value_text``.
+
+A Series, or a DataFrame without a ``time`` column, takes its times from a
+``DatetimeIndex`` or ``TimedeltaIndex``.
+
+.. code-block:: python
+
+   speed = dataset.get_signal("car.speed").get_data()
+   signal = dataset.add_signal(
+       "car.speed_kmh",
+       speed * 3.6,
+       metadata={"unit": "km/h"},
+   ).wait_until_available()
+
+Data assembled from scratch uses the explicit schema columns instead:
+
+.. code-block:: python
+
+   derived = pd.DataFrame({
+       "time": [t0, t0 + 1_000_000_000],
+       "value": [1.0, 2.0],
+   })
+   dataset.add_signal("car.custom", derived)
+
+For batches, ``add_signals`` returns signal IDs without waiting:
+
+.. code-block:: python
+
+   ids = dataset.add_signals(
+       [{"name": "car.speed_kmh", "data": speed * 3.6}],
+       overwrite=True,
+   )
+   signals = [
+       signal.wait_until_available()
+       for signal in dataset.get_signals(signal_ids=ids, refresh=True)
+   ]
+
+Filter datasets and get resampled data
+--------------------------------------
+
+.. code-block:: python
+
+   datasets = (
+       stream.get_datasets()
+       .where_metadata({"car_id": [1, 2], "track": "track_1"})
+       .wait_for_import()
+       .where_imported()
+       .where_signal("car.speed", "max", greater_than=75)
+   )
+   for dataset, data in datasets.get_data(
+       signals=["car.speed", re.compile(r"car\.wheel\..*\.speed")],
+       resample_rule="0.17s",
+   ):
+       print(dataset.path, data.shape)
+
+Ingest realtime data
+--------------------
+
+Use ``append`` with a realtime stream, then ``cool`` the dataset to cold
+storage when ingestion is complete.
+
+.. code-block:: python
+
+   realtime = db.get_stream("Live car data")
+   dataset = realtime.add_dataset("race-1", metadata={"driver": "Alice"})
+   dataset.upsert_signals([{"signal": "car.speed", "unit": "m/s"}])
+   dataset.append(pd.DataFrame({
+       "time": [1_700_000_000_000_000_000, 1_700_000_001_000_000_000],
+       "car.speed": [10.0, 12.0],
+   }))
+   dataset = dataset.cool().wait_for_import(timeout=180)
+
+Query with SQL
+--------------
+
+Trino querying is available on VPC and self-hosted deployments, not SaaS.
+
+.. code-block:: python
+
+   info = db.trino_info
+   table = f"{info['cold_catalog']}.{info['datapool']}.data"
+   data = db.query(
+       f"SELECT time, signal, value FROM {table} WHERE dataset = ? LIMIT 1000",
+       params=[dataset.id],
+   )

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/example.py

@@ -20,7 +20,9 @@ if stream_name not in [stream.name for stream in db.get_streams()]:
 
 stream = db.get_stream(stream_name)
 stream.push_file("examples_race.csv", metadata={"car_id": 1, "track": "track_1", "weather": "sunny"})
-stream.push_file("examples_race.csv", metadata={"car_id": 2, "track": "track_1", "weather": "cloudy"})
+stream.push_file(
+    "examples_race.csv", metadata={"car_id": 2, "track": "track_1", "weather": "cloudy"}, overwrite=True
+)
 stream.push_file("examples_race.csv", metadata={"car_id": 3, "track": "track_1", "weather": "rainy"})
 stream.push_file("examples_race.csv", metadata={"car_id": 1, "track": "track_2", "weather": "sunny"})
 stream.push_file("examples_race.csv", metadata={"car_id": 2, "track": "track_2", "weather": "sunny"})

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "marpledata"
-version = "3.4.0.dev1"
+version = "3.6.0.dev1"
 description = "Marple SDK for Python"
 authors = [
   { name = "Matthias Baert", email = "support@marpledata.com" },
@@ -72,6 +72,11 @@ docs = [
   "sphinx>=7.2.6",
 ]
 
+[tool.pytest.ini_options]
+markers = [
+  "integration: tests that talk to a live Marple DB / Insight instance",
+]
+
 [tool.black]
 line-length = 113
 target-version = ["py311"]

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/src/marple/__init__.py

@@ -3,4 +3,4 @@ from .db import DB
 from .insight import Insight
 
 __all__ = ["DB", "Insight", "db"]
-__version__ = "3.4.0.dev1"
+__version__ = "3.6.0.dev1"

{marpledata-3.4.0.dev1 → marpledata-3.6.0.dev1}/src/marple/db/__init__.py

@@ -353,19 +353,21 @@ class DB:
         file_path: str,
         metadata: dict | None = None,
         file_name: str | None = None,
+        overwrite: bool = False,
     ) -> int:
         """
         Push a file to a datastream.
         - `stream_key`: The name or ID of the stream to push the file to.
         - `file_path`: The path to the file to be pushed.
         - `metadata`: (optional) A dictionary of metadata to be associated with the file.
-        - `file_name`: (optional) The name of the file to be stored in the
+        - `file_name`: (optional) The name of the file to be stored in the stream.
+        - `overwrite`: (optional) If true, existing dataset with the same name will be overwritten.
 
         Note:
             This function is deprecated and it is encouraged to use the `push_file` method in the `DataStream` class directly.
         """
         stream = self.get_stream(stream_key)
-        return stream.push_file(file_path, metadata, file_name).id
+        return stream.push_file(file_path, metadata, file_name, overwrite=overwrite).id
 
     @deprecated
     def get_status(self, stream_key: str | int, dataset_id: int) -> dict:
@@ -430,6 +432,20 @@ class DB:
         r = self.post(f"/stream/{dataset.datastream_id}/dataset/{dataset.id}/delete")
         validate_response(r, "Delete dataset failed")
 
+    def delete_signals(
+        self,
+        dataset_id: int | None,
+        dataset_path: str | None,
+        signal_ids: Sequence[int],
+    ) -> None:
+        """
+        Delete signals from a dataset by ID or path.
+
+        Warning:
+            This is a destructive operation that cannot be undone.
+        """
+        self.get_dataset(dataset_id, dataset_path).delete_signals(signal_ids)
+
     @deprecated
     def update_metadata(
         self,
@@ -451,17 +467,24 @@ class DB:
             metadata = {}
         self.get_dataset(dataset_id, dataset_path).update_metadata(metadata, overwrite)
 
-    # Realtime functions #
+    # Dataset creation and realtime ingest #
 
     def add_dataset(self, stream_key: str | int, dataset_name: str, metadata: dict | None = None) -> int:
         """
-        Create a new empty dataset in the specified live stream.
-        Returns the ID of the newly created dataset.
-
-        Use `dataset_append` to add data to the dataset and `upsert_signals` to define signals.
-        Use `cool` to finalize the dataset when done.
-
-        To add datasets from a file to a file stream, use `push_file` instead.
+        Create a new empty dataset in the specified stream.
+
+        **Live (realtime) stream**
+            - Define signals with :meth:`~marple.db.dataset.Dataset.upsert_signals`
+            - Push data with :meth:`~marple.db.dataset.Dataset.append`
+            - Call :meth:`~marple.db.dataset.Dataset.cool` when finished to move the
+              dataset to cold Parquet/Iceberg storage, then
+              :meth:`~marple.db.dataset.Dataset.wait_for_import` until it is `FINISHED`.
+        **File (non-live) stream**
+            - Default path: use :meth:`push_file` instead of `add_dataset` — upload a
+              file (e.g. CSV); Marple parses it and writes it to the data lake.
+            - Custom ingestion: create an empty dataset with `add_dataset`, then upload
+              signal data with :meth:`~marple.db.dataset.Dataset.add_signal` /
+              :meth:`~marple.db.dataset.Dataset.add_signals` straight into the lake.
         """
         return self.get_stream(stream_key).add_dataset(dataset_name, metadata).id