Bring your data

Choose the workflow

The example loaders have different contracts. Their limits are not universal library capacities. DatasetSource, loadDatasetURL and Studio's loadSource are public example code, not package exports.

Walk through the dataset explorer

1. Open the dataset explorer. Its starting rows are 180 fictional laboratory measurements.
2. Import a CSV/JSON file, or expand Load from a data URL, enter a URL and choose Auto, CSV or JSON before selecting Load data.
3. Choose a numeric measure and a categorical grouping field. Review missingness, the histogram, group counts and exact records.
4. Select a group or brush a numeric range. In this workspace, table search and filters also narrow the profile and charts; grouping and sorting change the table presentation.
5. Export CSV before replacing the dataset if you need to keep local edits. Saved table views store settings, not records or a live connection.

These linked search/filter semantics are implemented by the explorer application. A standalone DataExplorer does not automatically publish its local search or table filters to every chart. Selection is the shared predicate channel.

Prepare the snapshot

JSON accepts a nonempty row array or a snapshot object with rows and optional label and fields metadata. Each cell must be a string, finite safe numeric value, boolean or null. Flatten nested objects and arrays first. Missing cells become null.

{
  "label": "Orders snapshot",
  "rows": [
    { "id": "0001", "region": "Europe", "amount": 120 },
    { "id": "0002", "region": "Americas", "amount": null }
  ],
  "fields": {
    "id": { "type": "nominal", "label": "Order" },
    "amount": { "type": "quantitative", "format": "currency", "currency": "USD" }
  }
}

Keep large integer identifiers as strings in JSON. CSV inference preserves leading-zero and oversized identifiers as text. Use metadata for ambiguous dates, identifiers and units; the data model explains formats. A missing measure is unavailable, while an explicit zero remains a measurement.

The Python snapshot helper writes this envelope from pandas, Polars or ordinary records. No Python kernel runs in the browser.

Load a URL safely and predictably

The explorer fetches a complete CSV/JSON snapshot. It sends no cookies, authorization header or referrer. A different origin must allow browser CORS. Use HTTPS on the deployed site; although the loader accepts HTTP for environments that permit it, a secure page normally blocks an insecure remote response.

Auto format uses the response content type, then a CSV filename suffix; otherwise it tries JSON. Choose the format explicitly if the endpoint labels its response incorrectly. Pagination and arbitrary nested API envelopes are not followed. Return a flat snapshot, or use Studio's adapter for its supported API presets and custom records path.

• A successful load replaces the dataset and resets chart selection and table state. Local cell edits are not written back to the source.
• A failed or cancelled load keeps the last successfully loaded dataset. A newer load or restoring the sample supersedes an older request.
• There is no polling. Load again for a new snapshot; receipt time is not the provider's publication time.
• The visible provenance omits query strings. This is display hygiene, not secret detection: never paste credentials into a URL.

Continue in an application

Use API recipes for weather, earthquake and country-year data, or Studio for a portable project and runnable starter. For an existing product, follow Installation and Framework integration, then pass authorized rows into the same components.

The source controls, URL loader and snapshot parser are available to adapt. The UI owns the 15-second deadline; calling the loader directly requires your application to supply cancellation and a timeout.