> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DataStore : API compatible pandas avec optimisation SQL

> DataStore fournit une API compatible pandas avec optimisation SQL pour l'analyse de données hautes performances

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

DataStore est l’API compatible avec pandas de chDB. Elle associe l’interface familière des DataFrame pandas à la puissance de l’optimisation des requêtes SQL et vous permet d’écrire du code dans le style de pandas tout en bénéficiant des performances de ClickHouse.

<div id="key-features">
  ## Fonctionnalités clés
</div>

* **Compatibilité avec pandas** : 209 méthodes de DataFrame pandas, 56 méthodes `.str`, plus de 42 méthodes `.dt`
* **Optimisation SQL** : les opérations sont automatiquement compilées en requêtes SQL optimisées
* **Évaluation paresseuse** : les opérations sont différées jusqu’à ce que les résultats soient nécessaires
* **630+ méthodes d’API** : une API complète pour la manipulation des données
* **Extensions ClickHouse** : des accesseurs supplémentaires (`.arr`, `.json`, `.url`, `.ip`, `.geo`) indisponibles dans pandas

<div id="architecture">
  ## Architecture
</div>

<Image size="md" img="https://mintcdn.com/private-7c7dfe99/QiEdJri7g6Jn-guK/images/chdb/datastore_architecture.png?fit=max&auto=format&n=QiEdJri7g6Jn-guK&q=85&s=4c1aeaf14a157d6e02aa729d8825ef24" alt="Architecture de DataStore" width="2816" height="1536" data-path="images/chdb/datastore_architecture.png" />

DataStore utilise une **évaluation paresseuse** avec une **exécution sur deux moteurs** :

1. **Chaîne d'opérations différées** : les opérations sont enregistrées, et non exécutées immédiatement
2. **Sélection intelligente du moteur** : QueryPlanner oriente chaque segment vers le moteur le plus adapté (chDB pour SQL, Pandas pour les opérations complexes)
3. **Mise en cache intermédiaire** : les résultats sont mis en cache à chaque étape pour accélérer l'exploration itérative

Voir le [Modèle d'exécution](/docs/fr/chdb/datastore/execution-model) pour plus de détails.

<div id="migration">
  ## Migration en une ligne depuis Pandas
</div>

```python theme={null}
# Before (pandas)
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

# After (DataStore) - just change the import!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()
```

Votre code pandas existant fonctionne tel quel, mais s’exécute désormais sur le moteur ClickHouse.

<div id="performance">
  ## Comparaison des performances
</div>

DataStore offre des gains de performances significatifs par rapport à pandas, en particulier pour l’agrégation et les pipelines complexes :

| Opération          | Pandas  | DataStore | Accélération |
| ------------------ | ------- | --------- | ------------ |
| Count de GroupBy   | 347ms   | 17ms      | **19.93x**   |
| Pipeline complexe  | 2,047ms | 380ms     | **5.39x**    |
| Filter+Sort+Head   | 1,537ms | 350ms     | **4.40x**    |
| Agrégation GroupBy | 406ms   | 141ms     | **2.88x**    |

*Benchmark effectué sur 10M lignes. Voir le [script de benchmark](https://github.com/chdb-io/chdb/blob/main/refs/benchmark_datastore_vs_pandas.py) et le [Guide des performances](/docs/fr/chdb/guides/pandas-performance) pour plus de détails.*

<div id="when-to-use">
  ## Quand utiliser DataStore
</div>

**Utilisez DataStore lorsque :**

* Vous travaillez avec de grands jeux de données (des millions de lignes)
* Vous effectuez des agrégations et des opérations `groupby`
* Vous interrogez des données provenant de fichiers, de bases de données ou du stockage cloud
* Vous construisez des pipelines de données complexes
* Vous souhaitez bénéficier de l'API pandas avec de meilleures performances

**Utilisez l'API SQL brut lorsque :**

* Vous préférez écrire directement en SQL
* Vous avez besoin d'un contrôle fin sur l'exécution des requêtes
* Vous travaillez avec des fonctionnalités spécifiques à ClickHouse qui ne sont pas exposées dans l'API pandas

<div id="comparison">
  ## Comparaison des fonctionnalités
</div>

| Fonctionnalité                            | Pandas | Polars    | DuckDB | DataStore        |
| ----------------------------------------- | ------ | --------- | ------ | ---------------- |
| Compatible avec l'API Pandas              | -      | Partielle | Non    | **Complète**     |
| Évaluation paresseuse                     | Non    | Oui       | Oui    | **Oui**          |
| Prise en charge des requêtes SQL          | Non    | Oui       | Oui    | **Oui**          |
| Fonctions ClickHouse                      | Non    | Non       | Non    | **Oui**          |
| Accesseurs String/DateTime                | Oui    | Oui       | Non    | **Oui + extras** |
| Array/JSON/URL/IP/Geo                     | Non    | Partielle | Non    | **Oui**          |
| Requêtes directes sur des fichiers        | Non    | Oui       | Oui    | **Oui**          |
| Prise en charge du stockage dans le cloud | Non    | Limitée   | Oui    | **Oui**          |

<div id="api-stats">
  ## Statistiques de l’API
</div>

| Catégorie                       | Nombre   | Couverture                                                        |
| ------------------------------- | -------- | ----------------------------------------------------------------- |
| Méthodes de DataFrame           | 209      | 100 % de pandas                                                   |
| Accesseur Series.str            | 56       | 100 % de pandas                                                   |
| Accesseur Series.dt             | 42+      | 100 %+ (inclut des fonctionnalités supplémentaires de ClickHouse) |
| Accesseur Series.arr            | 37       | Spécifique à ClickHouse                                           |
| Accesseur Series.json           | 13       | Spécifique à ClickHouse                                           |
| Accesseur Series.url            | 15       | Spécifique à ClickHouse                                           |
| Accesseur Series.ip             | 9        | Spécifique à ClickHouse                                           |
| Accesseur Series.geo            | 14       | Spécifique à ClickHouse                                           |
| **Total des méthodes de l’API** | **630+** | -                                                                 |

<div id="navigation">
  ## Navigation dans la documentation
</div>

<div id="getting-started">
  ### Prise en main
</div>

* [Démarrage rapide](/docs/fr/chdb/datastore/quickstart) - Installation et utilisation de base
* [Migration depuis Pandas](/docs/fr/chdb/guides/migration-from-pandas) - Guide de migration étape par étape

<div id="api-reference">
  ### Référence de l’API
</div>

* [Méthodes de fabrique](/docs/fr/chdb/datastore/factory-methods) - Création de DataStore à partir de diverses sources
* [Construction de requêtes](/docs/fr/chdb/datastore/query-building) - Opérations de requête de style SQL
* [compatibilité avec pandas](/docs/fr/chdb/datastore/pandas-compat) - Les 209 méthodes compatibles avec pandas
* [Accesseurs](/docs/fr/chdb/datastore/accessors) - Accesseurs String, DateTime, Array, JSON, URL, IP et Geo
* [Agrégation](/docs/fr/chdb/datastore/aggregation) - Fonctions d’agrégation et fonctions de fenêtre
* [Opérations d’E/S](/docs/fr/chdb/datastore/io) - Lecture et écriture de données

<div id="advanced-topics">
  ### Sujets avancés
</div>

* [Modèle d'exécution](/docs/fr/chdb/datastore/execution-model) - Évaluation paresseuse et mise en cache
* [Référence de classe](/docs/fr/chdb/datastore/class-reference) - Référence complète de l’API

<div id="configuration-debugging">
  ### Configuration et débogage
</div>

* [Configuration](/docs/fr/chdb/configuration/index) - Toutes les options de configuration
* [Performance Mode](/docs/fr/chdb/configuration/performance-mode) - Mode axé SQL pour un débit maximal
* [Débogage](/docs/fr/chdb/debugging/index) - Explain, profilage et journalisation

<div id="pandas-user-guides">
  ### Guides d’utilisation de Pandas
</div>

* [Recettes Pandas](/docs/fr/chdb/guides/pandas-cookbook) - Cas d’usage courants
* [Principales différences](/docs/fr/chdb/guides/pandas-differences) - Différences importantes avec Pandas
* [guide des performances](/docs/fr/chdb/guides/pandas-performance) - Conseils d’optimisation
* [SQL pour les utilisateurs de Pandas](/docs/fr/chdb/guides/pandas-to-sql) - Comprendre le SQL sous-jacent aux opérations de Pandas

<div id="quick-example">
  ## Exemple rapide
</div>

```python theme={null}
from chdb import datastore as pd

# Read data from various sources
ds = pd.read_csv("sales.csv")
# or: ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# or: ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")

# Familiar pandas operations - automatically optimized to SQL
result = (ds
    .filter(ds['amount'] > 1000)           # WHERE amount > 1000
    .groupby('region')                      # GROUP BY region
    .agg({'amount': ['sum', 'mean']})       # SUM(amount), AVG(amount)
    .sort_values('sum', ascending=False)    # ORDER BY sum DESC
    .head(10)                               # LIMIT 10
)

# View the generated SQL
print(result.to_sql())

# Execute and get results
df = result.to_df()  # Returns pandas DataFrame
```

<div id="next-steps">
  ## Étapes suivantes
</div>

* **Vous découvrez DataStore ?** Commencez par le [guide de démarrage rapide](/docs/fr/chdb/datastore/quickstart)
* **Vous venez de pandas ?** Consultez le [guide de migration](/docs/fr/chdb/guides/migration-from-pandas)
* **Vous voulez en savoir plus ?** Consultez la [référence de l’API](/docs/fr/chdb/datastore/class-reference)