Deprecate dataset backend (#471)

abidlabs · claude · web-flow · commit 246fce0a0161 · 2026-04-08T13:01:29.000-07:00
Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/open-meals-smoke.md b/.changeset/open-meals-smoke.md
@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:Deprecate dataset backend in favor of buckets
diff --git a/README.md b/README.md
@@ -237,7 +237,6 @@ You can query alerts via the CLI (`trackio get alerts --project "my-project" --j
 To get started and see basic examples of usage, see these files:
 
 - [Basic example of logging metrics locally](https://github.com/gradio-app/trackio/blob/main/examples/fake-training.py)
-- [Persisting metrics in a Hugging Face Dataset](https://github.com/gradio-app/trackio/blob/main/examples/persist-dataset.py)
 - [Deploying the dashboard to Spaces](https://github.com/gradio-app/trackio/blob/main/examples/deploy-on-spaces.py)
 
 ## Throughput & Rate Limits
diff --git a/docs/source/environment_variables.md b/docs/source/environment_variables.md
@@ -106,18 +106,9 @@ export TRACKIO_WEBHOOK_MIN_LEVEL="warn"
 
 With `warn`, only `WARN` and `ERROR` alerts are sent to webhook URLs.
 
-### `TRACKIO_DATASET_ID`
-
-Sets the Hugging Face Dataset ID where logs will be stored when running on Hugging Face Spaces. If not provided, the dataset name will be set automatically when deploying to Spaces.
-
-
-```bash
-export TRACKIO_DATASET_ID="username/dataset_name"
-```
-
 ### `HF_TOKEN`
 
-Your Hugging Face authentication token. Required for creating Spaces and Datasets on Hugging Face. Set this locally when deploying to Spaces from your machine. Must have `write` permissions for the namespace that you are deploying the Trackio dashboard.
+Your Hugging Face authentication token. Required for creating Spaces and Buckets on Hugging Face. Set this locally when deploying to Spaces from your machine. Must have `write` permissions for the namespace that you are deploying the Trackio dashboard.
 
 ```bash
 export HF_TOKEN="hf_xxxxxxxxxxxxx"
diff --git a/examples/persist-dataset.py b/examples/persist-dataset.py
diff --git a/examples/sync-static-space.py b/examples/sync-static-space.py
@@ -6,7 +6,7 @@
 
 This will:
 1. Log a few runs of fake training metrics locally
-2. Call trackio.sync() which exports data as Parquet to an HF Dataset
+2. Call trackio.sync() which uploads the local project to an HF Bucket
    and deploys a static dashboard Space (no running server needed)
 
 Set HF_TOKEN or run `huggingface-cli login` first.
diff --git a/pyproject.toml b/pyproject.toml
@@ -14,7 +14,7 @@ readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "pandas<3.0.0",
-    "huggingface-hub>=1.9.0,<2",
+    "huggingface-hub>=1.9.2,<2",
     "gradio[oauth]>=6.10.0,<7.0.0",
     "numpy<3.0.0",
     "pillow<12.0.0",
diff --git a/trackio/__init__.py b/trackio/__init__.py
@@ -139,15 +139,11 @@ def init(
         space_storage ([`~huggingface_hub.SpaceStorage`], *optional*):
             Choice of persistent storage tier.
         dataset_id (`str`, *optional*):
-            If provided, uses the legacy Hugging Face Dataset backend for metric
-            persistence (metrics are exported to Parquet and committed every 5 minutes).
-            Specify a Dataset with name like `"username/datasetname"` or
-            `"orgname/datasetname"`, or `"datasetname"` (uses currently-logged-in
-            Hugging Face user's namespace). Cannot be used together with `bucket_id`.
+            Deprecated. Use `bucket_id` instead.
         bucket_id (`str`, *optional*):
             The ID of the Hugging Face Bucket to use for metric persistence. By default,
-            when a `space_id` is provided and neither `dataset_id` nor `bucket_id` is
-            explicitly set, a bucket is auto-generated from the space_id. Buckets provide
+            when a `space_id` is provided and `bucket_id` is not explicitly set, a
+            bucket is auto-generated from the space_id. Buckets provide
             S3-like storage without git overhead - the SQLite database is stored directly
             via `hf-mount` in the Space. Specify a Bucket with name like
             `"username/bucketname"` or just `"bucketname"`.
diff --git a/trackio/cli.py b/trackio/cli.py
@@ -223,7 +223,7 @@ def main():
         "--sdk",
         choices=["gradio", "static"],
         default="gradio",
-        help="The type of Space to deploy. 'gradio' (default) deploys a live Gradio server. 'static' deploys a static Space that reads from an HF Dataset.",
+        help="The type of Space to deploy. 'gradio' (default) deploys a live Gradio server. 'static' deploys a static Space that reads from an HF Bucket.",
     )
 
     list_parser = subparsers.add_parser(
diff --git a/trackio/deploy.py b/trackio/deploy.py
@@ -288,10 +288,10 @@ def create_space_if_not_exists(
         space_storage ([`~huggingface_hub.SpaceStorage`], *optional*):
             Choice of persistent storage tier for the Space.
         dataset_id (`str`, *optional*):
-            The ID of the Dataset to add to the Space as a space variable.
+            Deprecated. Use `bucket_id` instead.
         bucket_id (`str`, *optional*):
             Full Hub bucket id (`namespace/name`) to attach via the Hub volumes API (platform mount).
-            Sets `TRACKIO_DIR` to the mount path; do not combine with `dataset_id`.
+            Sets `TRACKIO_DIR` to the mount path.
         private (`bool`, *optional*):
             Whether to make the Space private. If `None` (default), the repo will be
             public unless the organization's default is private. This value is ignored
@@ -725,14 +725,13 @@ def sync(
             If `False`, all the steps will be run synchronously.
         sdk (`str`, *optional*, defaults to `"gradio"`):
             The type of Space to deploy. `"gradio"` deploys a Gradio Space with a live
-            server. `"static"` deploys a static Space that reads from an HF Dataset
-            or HF Bucket (no server needed).
+            server. `"static"` deploys a static Space that reads from an HF Bucket
+            (no server needed).
         dataset_id (`str`, *optional*):
-            The ID of the HF Dataset to sync to. When provided, uses the legacy
-            Dataset backend instead of Buckets.
+            Deprecated. Use `bucket_id` instead.
         bucket_id (`str`, *optional*):
             The ID of the HF Bucket to sync to. By default, a bucket is auto-generated
-            from the space_id. Set `dataset_id` to use the legacy Dataset backend instead.
+            from the space_id.
     Returns:
         `str`: The Space ID of the synced project.
     """
diff --git a/trackio/imports.py b/trackio/imports.py
@@ -42,16 +42,7 @@ def import_csv(
             Space does not exist, it will be created. If the Space already exists, the
             project will be logged to it.
         dataset_id (`str`, *optional*):
-            If provided, a persistent Hugging Face Dataset will be created and the
-            metrics will be synced to it every 5 minutes. Should be a complete Dataset
-            name like `"username/datasetname"` or `"orgname/datasetname"`, or just
-            `"datasetname"` in which case the Dataset will be created in the
-            currently-logged-in Hugging Face user's namespace. If the Dataset does not
-            exist, it will be created. If the Dataset already exists, the project will
-            be appended to it. If not provided, the metrics will be logged to a local
-            SQLite database, unless a `space_id` is provided, in which case a Dataset
-            will be automatically created with the same name as the Space but with the
-            `"_dataset"` suffix.
+            Deprecated. Use `bucket_id` instead.
         private (`bool`, *optional*):
             Whether to make the Space private. If None (default), the repo will be
             public unless the organization's default is private. This value is ignored
@@ -182,16 +173,7 @@ def import_tf_events(
             Space does not exist, it will be created. If the Space already exists, the
             project will be logged to it.
         dataset_id (`str`, *optional*):
-            If provided, a persistent Hugging Face Dataset will be created and the
-            metrics will be synced to it every 5 minutes. Should be a complete Dataset
-            name like `"username/datasetname"` or `"orgname/datasetname"`, or just
-            `"datasetname"` in which case the Dataset will be created in the
-            currently-logged-in Hugging Face user's namespace. If the Dataset does not
-            exist, it will be created. If the Dataset already exists, the project will
-            be appended to it. If not provided, the metrics will be logged to a local
-            SQLite database, unless a `space_id` is provided, in which case a Dataset
-            will be automatically created with the same name as the Space but with the
-            `"_dataset"` suffix.
+            Deprecated. Use `bucket_id` instead.
         private (`bool`, *optional*):
             Whether to make the Space private. If None (default), the repo will be
             public unless the organization's default is private. This value is ignored
diff --git a/trackio/utils.py b/trackio/utils.py
@@ -3,6 +3,7 @@
 import re
 import secrets
 import time
+import warnings
 from datetime import datetime, timezone
 from functools import lru_cache
 from pathlib import Path
@@ -433,13 +434,19 @@ def preprocess_space_and_dataset_ids(
     bucket_id: str | None = None,
 ) -> tuple[str | None, str | None, str | None]:
     """
-    Preprocesses the Space, Dataset, and Bucket names to ensure they are valid
-    "username/name" format. When space_id is provided and neither dataset_id nor
-    bucket_id is explicitly set, auto-generates a bucket_id (default backend).
+    Preprocesses the Space and Bucket names to ensure they are valid
+    "username/name" format. When space_id is provided and bucket_id is not
+    explicitly set, auto-generates a bucket_id.
     """
     if space_id is not None and "/" not in space_id:
         username = _get_default_namespace()
         space_id = f"{username}/{space_id}"
+    if dataset_id is not None:
+        warnings.warn(
+            "`dataset_id` is deprecated. Use `bucket_id` instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
     if dataset_id is not None and "/" not in dataset_id:
         username = _get_default_namespace()
         dataset_id = f"{username}/{dataset_id}"

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"trackio": minor
 +---
++
 +feat:Deprecate dataset backend in favor of buckets
Original file line number	Diff line number	Diff line change
`@@ -223,7 +223,7 @@ def main():`
`223`	`223`	`"--sdk",`
`224`	`224`	`choices=["gradio", "static"],`
`225`	`225`	`default="gradio",`
`226`		`- help="The type of Space to deploy. 'gradio' (default) deploys a live Gradio server. 'static' deploys a static Space that reads from an HF Dataset.",`
	`226`	`+ help="The type of Space to deploy. 'gradio' (default) deploys a live Gradio server. 'static' deploys a static Space that reads from an HF Bucket.",`
`227`	`227`	`)`
`228`	`228`
`229`	`229`	`list_parser = subparsers.add_parser(`