# Hugging Face
> Query public, private, and gated Hugging Face datasets from MotherDuck with hf:// paths.
MotherDuck and DuckDB can read datasets hosted on the [Hugging Face Hub](https://huggingface.co/datasets) directly, using `hf://` paths. You can query public datasets without credentials, and use a secret to read private or gated datasets. For the full details of the `hf://` protocol, see the [DuckDB Hugging Face documentation](https://duckdb.org/docs/extensions/httpfs/hugging_face).

## Query public Hugging Face datasets

### Read a single file

Reference a file in a dataset repository with a path in the form `hf://datasets/<org>/<dataset>/<path_to_file>`:

```sql
SELECT *
FROM 'hf://datasets/datasets-examples/doc-formats-csv-1/data.csv';
```

This works for any file format DuckDB can read, such as Parquet, CSV, and JSON.

### Read multiple files with glob patterns

Use glob patterns to read many files at once. `*` matches files in one directory, and `**` matches files in any subdirectory:

```sql
-- all Parquet files in one directory
SELECT count(*)
FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet';

-- all Parquet files anywhere in the dataset
SELECT count(*)
FROM 'hf://datasets/ibm/duorc/**/*.parquet';
```

### Read a specific revision

Add `@<revision>` after the dataset name to read from a specific branch, tag, or commit. Hugging Face automatically converts many datasets to Parquet and stores the result on a separate branch, which you can read with the `@~parquet` revision:

```sql
SELECT count(*)
FROM 'hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/*.parquet';
```

## Configure Hugging Face credentials

To read private datasets, or gated datasets you've been granted access to, authenticate with a Hugging Face access token. You can safely store your token in MotherDuck for convenience by creating a `SECRET` object using the [CREATE SECRET](/sql-reference/motherduck-sql-reference/create-secret.md) command.

:::note
See [Hugging Face docs](https://huggingface.co/docs/hub/security-tokens) to create a user access token. A token with `read` permission is enough to query datasets.
:::

### Create a SECRET object

### SQL

```sql
CREATE SECRET IN MOTHERDUCK (
    TYPE HUGGINGFACE,
    TOKEN 'your_hf_token' -- provided by Hugging Face
);
```

You can also use the `PERSISTENT` keyword, which stores the secret in MotherDuck when you're connected to MotherDuck:

```sql
CREATE PERSISTENT SECRET hf_secret (
    TYPE HUGGINGFACE,
    TOKEN 'your_hf_token'
);
```

```sql
-- test the Hugging Face credentials
SELECT count(*) FROM 'hf://datasets/<org>/<private_dataset>/<path_to_file>.parquet';
```

### Python

```python

import duckdb

con = duckdb.connect('md:')
con.sql("CREATE SECRET IN MOTHERDUCK ( TYPE HUGGINGFACE, TOKEN 'your_hf_token' )");

# testing that our Hugging Face credentials work
con.sql("SELECT count(*) FROM 'hf://datasets/<org>/<private_dataset>/<path_to_file>.parquet'").show()
```

### Delete a SECRET object

You can use the [DROP SECRET](/sql-reference/motherduck-sql-reference/delete-secret.md) command.

```sql
DROP SECRET <secret_name>;
```

### Hugging Face credentials as temporary secrets

MotherDuck supports DuckDB syntax for providing Hugging Face credentials.

```sql
CREATE SECRET (
    TYPE HUGGINGFACE,
    TOKEN 'your_hf_token'
);
```

If you've signed in with the Hugging Face CLI (`hf auth login`, or `huggingface-cli login` in older versions), or set the `HF_TOKEN` environment variable, use the `credential_chain` provider to read the token automatically:

```sql
CREATE SECRET (
    TYPE HUGGINGFACE,
    PROVIDER credential_chain
);
```

To store a secret from the `credential_chain` provider in MotherDuck, add the `PERSISTENT` or `IN MOTHERDUCK` keyword. Create it from a local DuckDB client connected to MotherDuck, because the MotherDuck UI can't access your local Hugging Face credentials.

:::note
Local/In-memory secrets are not persisted across sessions.
:::

:::info
Even temporary, in-memory secrets are available to MotherDuck's cloud execution engine when you connect your
local DuckDB instance to MotherDuck. When you query Hugging Face, the query runs on MotherDuck's servers, not your local machine,
and MotherDuck uses the best-matching secret to authenticate, whether it is stored locally or in MotherDuck.
For more details, see [CREATE SECRET](/sql-reference/motherduck-sql-reference/create-secret/#querying-with-secrets).
:::


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fintegrations%2Fcloud-storage%2Fhugging-face%2F&page_title=Hugging%20Face&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.