# DuckDB

[DuckDB](https://github.com/duckdb/duckdb), süreç içi bir SQL [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) veritabanı yönetim sistemidir. Hub üzerindeki verilere erişmek için Hugging Face yollarını (`hf://`) kullanabilirsiniz:

[DuckDB CLI](https://duckdb.org/docs/api/cli/overview.html) (Komut Satırı Arayüzü) tek bir, bağımlılıksız çalıştırılabilir dosyadır. DuckDB'yi çalıştırmak için Python, C++, Go, Java, Rust ve daha fazlası dahil olmak üzere diğer API'ler de mevcuttur. Ek ayrıntılar için [istemciler](https://duckdb.org/docs/api/overview.html) sayfasını ziyaret edin.

> [!TIP]
> Kurulum ayrıntıları için [kurulum sayfasını](https://duckdb.org/docs/installation) ziyaret edin.

> [!TIP]
> `hf` CLI'yi kullanıyorsanız, [`hf datasets sql`](/docs/huggingface_hub/package_reference/cli#hf-datasets-sql) ile DuckDB sorgularını doğrudan çalıştırabilirsiniz, örneğin `hf datasets sql "FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3"`. Kapılı ve özel veri setleri için kimlik doğrulama, oturum açmış token'ınızdan otomatik olarak yapılandırılır ve `--format json` makine tarafından okunabilir çıktı döndürür.

`v0.10.3` sürümünden itibaren DuckDB CLI, `hf://` şemasına sahip URL'ler aracılığıyla Hugging Face Hub'daki veri setlerine erişim için yerel destek içerir. Bu güçlü araçla kullanabileceğiniz bazı özellikler şunlardır:

- Herkese açık veri setlerini ve kendi kapılı ve özel veri setlerinizi sorgulayın
- Veri kümelerini analiz edin ve SQL işlemleri gerçekleştirin
- Veri kümelerini birleştirin ve farklı formatlara dışa aktarın
- Gömme veri setlerinde vektör benzerlik araması yapın
- Veri kümelerinde tam metin arama uygulayın

DuckDB özelliklerinin tam listesi için DuckDB [belgelerini](https://duckdb.org/docs/) ziyaret edin.

CLI'yi başlatmak için, kurulum klasöründe aşağıdaki komutu çalıştırın:

```bash
./duckdb
```

## Hugging Face URL'sini Oluşturma

Hugging Face veri setlerine erişmek için aşağıdaki URL biçimini kullanın:

```plaintext
hf://datasets/{my-username}/{my-dataset}/{path_to_file} 
```

- **my-username**, veri setinin kullanıcı veya kuruluşu, örn. `ibm`
- **my-dataset**, veri seti adı, örn: `duorc`
- **path_to_parquet_file**, glob desenlerini destekleyen parquet dosya yolu, örneğin tüm parquet dosyalarını sorgulamak için `**/*.parquet`

> [!TIP]
> @~parquet dalını kullanarak otomatik dönüştürülmüş Parquet dosyalarına sorgu gönderebilirsiniz; bu dal, `refs/convert/parquet` revizyonuna karşılık gelir. Daha fazla ayrıntı için https://huggingface.co/docs/datasets-server/en/parquet#conversion-to-parquet adresindeki belgelere başvurun.
>
> Bir veri setinin `refs/convert/parquet` revizyonuna atıfta bulunmak için aşağıdaki sözdizimini kullanın:
>
> ```plaintext
> hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file} 
> ```
>
> Yukarıdaki sözdizimini takip eden örnek bir URL aşağıdadır:
>
> ```plaintext
> hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/0000.parquet
> ```

## Bir veri setini sorgula

Bir veri setindeki tüm satırları sorgulamak için hızlı bir demo ile başlayalım:

```sql
FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;
```

Veya geleneksel SQL sözdizimini kullanarak:

```sql
SELECT * FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;
```
Aşağıdaki bölümlerde, Hugging Face veri kümeleri üzerinde DuckDB ile gerçekleştirebileceğiniz daha karmaşık işlemleri ele alacağız.

> [!TIP]
> **Depolama Kovalarını Sorgulama**: DuckDB 2.0 ve sonraki sürümler, [Depolama Kovalarını](./storage-buckets) CLI ve her istemciden yerel olarak okur:
> ```sql
> SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10;
> ```
> Buckets sürüm yönetimi yapılmadığı için `@revision` sözdizimi bucket yollarına uygulanmaz. DuckDB 1.x'te Hugging Face dosya sistemini Python üzerinden kaydedin: `duckdb.register_filesystem(HfFileSystem())`. Ayrıntılar için [DuckDB ile Sorgu](./storage-buckets-access#query-with-duckdb) bölümüne bakın.

## Bir veri setini kaydet

Bir veri setini Hugging Face'e kaydetmek için `COPY ... TO` sözdizimini kullanın.

1. DuckDB >=2.0 için [eklentiyi](https://huggingface.co/duckdb-extensions) yükleyin:

```sql
SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo
  WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;
```

2. `hf` CLI veya doğrudan DuckDB içinde kimlik doğrulaması yapın:

* CLI'de:

  ```bash
  hf auth login
  ```

* DuckDB'de:

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

3. Henüz yoksa veri seti depolamanızı oluşturun:

* CLI'de:

  ```bash
  hf repos create username/my-dataset --repo-type dataset --private
  ```

* DuckDB'de:

  ```sql
  FROM hf_create_repo('hf://datasets/username/my-dataset', private := true);
  ```

4. Tablonuzu Hugging Face'e örneğin Parquet biçiminde dışa aktarın:

```sql
COPY tbl TO 'hf://datasets/username/my-dataset/out.parquet';
```

> [!TIP]
> Tabloyu bir bölüntü anahtarına göre birden çok dosyaya bölmek için `PARTITION_BY` kullanın: `COPY tbl TO 'hf://datasets/username/my-dataset/out-directory' (FORMAT parquet, PARTITION_BY (year, month));`. Dosyalar, bölüntü anahtarı değerlerine göre doğru alt dizine yerleştirilir, örneğin `'hf://datasets/username/my-dataset/out-directory/year=2026/month=1/data_1.parquet'`.

Veri kümeleri git depoları olduğu için her yeni dosya, veri kümesi geçmişinde bir commit'tir.