> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# pandas からの移行

> pandas から DataStore へ移行するためのステップバイステップガイド

このガイドでは、互換性を保ちながらパフォーマンスを向上させるために、既存の pandas コードを DataStore へ移行する方法を説明します。

<div id="one-line">
  ## ワンライナーでの移行
</div>

最も簡単なのは、import 文を変更するだけです:

```python theme={null}
# 変更前 (pandas)
import pandas as pd

# 変更後 (DataStore)
from chdb import datastore as pd
```

これで完了です！ほとんどの pandas コードは変更なしでそのまま動作します。

<div id="step-by-step">
  ## 移行手順
</div>

<Steps>
  <Step>
    ### chDB をインストールする

    ```bash theme={null}
    pip install "chdb>=4.0"
    ```
  </Step>

  <Step>
    ### インポート文を変更する

    ```python theme={null}
    # 変更前:
    import pandas as pd

    # 変更後:
    from chdb import datastore as pd
    ```
  </Step>

  <Step>
    ### コードをテストする

    既存のコードを実行してください。ほとんどの操作はそのまま動作します。

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

    # これらはすべて同じように動作します
    df = pd.read_csv("data.csv")
    result = df[df['age'] > 25]
    grouped = df.groupby('city')['salary'].mean()
    df.to_csv("output.csv")
    ```
  </Step>

  <Step>
    ### 相違点があれば対応する

    一部の操作は挙動が異なります。以下の[主な違い](#differences)を参照してください。
  </Step>
</Steps>

***

<div id="works-unchanged">
  ## 変更せずに使えるもの
</div>

<div id="loading-unchanged">
  ### データの読み込み
</div>

```python theme={null}
# これらはすべて同じように動作する
df = pd.read_csv("data.csv")
df = pd.read_parquet("data.parquet")
df = pd.read_json("data.json")
df = pd.read_excel("data.xlsx")
```

<div id="filtering-unchanged">
  ### フィルタ
</div>

```python theme={null}
# ブールインデックス
df[df['age'] > 25]
df[(df['age'] > 25) & (df['city'] == 'NYC')]

# query() メソッド
df.query('age > 25 and salary > 50000')
```

<div id="selection-unchanged">
  ### 選択範囲
</div>

```python theme={null}
# カラムの選択
df['name']
df[['name', 'age']]

# 行の選択
df.head(10)
df.tail(10)
df.iloc[0:100]
```

<div id="groupby-unchanged">
  ### GroupBy と集計
</div>

```python theme={null}
# GroupBy
df.groupby('city')['salary'].mean()
df.groupby(['city', 'dept']).agg({'salary': ['sum', 'mean']})
```

<div id="sorting-unchanged">
  ### ソート
</div>

```python theme={null}
df.sort_values('salary', ascending=False)
df.sort_values(['city', 'age'])
```

<div id="string-unchanged">
  ### 文字列操作
</div>

```python theme={null}
df['name'].str.upper()
df['name'].str.contains('John')
df['name'].str.len()
```

<div id="datetime-unchanged">
  ### DateTime の操作
</div>

```python theme={null}
df['date'].dt.year
df['date'].dt.month
df['date'].dt.dayofweek
```

<div id="io-unchanged">
  ### I/O 処理
</div>

```python theme={null}
df.to_csv("output.csv")
df.to_parquet("output.parquet")
df.to_json("output.json")
```

***

<div id="differences">
  ## 主な違い
</div>

<div id="lazy">
  ### 1. 遅延評価
</div>

DataStore の操作は遅延的に評価され、結果が必要になるまで実行されません。

**pandas:**

```python theme={null}
# 即座に実行される
result = df[df['age'] > 25]
print(type(result))  # pandas.DataFrame
```

**DataStore:**

```python theme={null}
# クエリを構築するが、まだ実行しない
result = ds[ds['age'] > 25]
print(type(result))  # DataStore (遅延評価)

# データが必要になったときに実行される
print(result)        # 実行をトリガー
df = result.to_df()  # 実行をトリガー
```

<div id="return-types">
  ### 2. 戻り値の型
</div>

| 操作                | pandas の戻り値 | DataStore の戻り値  |
| ----------------- | ----------- | --------------- |
| `df['col']`       | Series      | ColumnExpr (遅延) |
| `df[['a', 'b']]`  | DataFrame   | DataStore (遅延)  |
| `df[condition]`   | DataFrame   | DataStore (遅延)  |
| `df.groupby('x')` | GroupBy     | LazyGroupBy     |

<div id="no-inplace">
  ### 3. inplace パラメータはありません
</div>

DataStore は `inplace=True` に対応していません。必ず戻り値を使用してください。

**pandas:**

```python theme={null}
df.drop(columns=['col'], inplace=True)
```

**DataStore:**

```python theme={null}
ds = ds.drop(columns=['col'])  # 結果を代入する
```

<div id="comparing">
  ### 4. DataStore の比較
</div>

pandas は DataStore オブジェクトを認識しないため、比較するには `to_pandas()` を使用します。

```python theme={null}
# これは期待通りに動作しない場合があります
df == ds  # pandasはDataStoreを認識しません

# 代わりにこちらを使用してください
df.equals(ds.to_pandas())
```

<div id="row-order">
  ### 5. 行の順序
</div>

DataStore では、ファイルソース (SQL データベースなど) の場合、行の順序が保持されないことがあります。明示的にソートしてください。

```python theme={null}
# pandasは順序を保持する
df = pd.read_csv("data.csv")

# DataStore - 順序を保証するにはソートを使用する
ds = pd.read_csv("data.csv")
ds = ds.sort('id')  # 明示的な順序付け
```

***

<div id="patterns">
  ## 移行パターン
</div>

<div id="pattern-1">
  ### パターン 1: 読み込み・分析・書き込み
</div>

```python theme={null}
# pandas
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['amount'] > 100].groupby('category')['amount'].sum()
result.to_csv("output.csv")

# DataStore - 同じコードがそのまま動作します！
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['amount'] > 100].groupby('category')['amount'].sum()
result.to_csv("output.csv")
```

<div id="pattern-2">
  ### パターン 2: pandas 操作用の DataFrame
</div>

pandas 固有の機能が必要な場合は、最後に変換します。

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

# 高速なDataStore操作
ds = pd.read_csv("large_data.csv")
ds = ds.filter(ds['date'] >= '2024-01-01')
ds = ds.filter(ds['amount'] > 100)

# 特定の機能のためにpandasに変換
df = ds.to_df()
df_pivoted = df.pivot_table(...)  # pandas固有
```

<div id="pattern-3">
  ### パターン 3: ハイブリッドワークフロー
</div>

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

# 高速フィルタリングのためにDataStoreから開始
ds = pd.read_csv("huge_file.csv")  # 1000万行
ds = ds.filter(ds['year'] == 2024)  # 高速SQLフィルター
ds = ds.select('col1', 'col2', 'col3')  # カラムプルーニング

# pandas固有の操作のために変換
df = ds.to_df()  # この時点で約10万行のみ
result = df.apply(complex_custom_function)  # pandas
```

***

<div id="performance">
  ## パフォーマンス比較
</div>

大規模なデータセットでは、DataStore のほうが大幅に高速です。

| 操作               | pandas  | DataStore | 高速化率       |
| ---------------- | ------- | --------- | ---------- |
| GroupBy count    | 347ms   | 17ms      | **19.93x** |
| Complex pipeline | 2,047ms | 380ms     | **5.39x**  |
| Filter+Sort+Head | 1,537ms | 350ms     | **4.40x**  |
| GroupBy agg      | 406ms   | 141ms     | **2.88x**  |

*1,000万行でのベンチマーク*

***

<div id="troubleshooting">
  ## 移行のトラブルシューティング
</div>

<div id="issue-op">
  ### 問題: 操作が機能しない
</div>

一部の pandas の操作はサポートされていないことがあります。以下を確認してください。

1. その操作は[互換性リスト](/ja/products/chdb/datastore/pandas-compat)に記載されていますか？
2. まず pandas に変換してから試してください: `ds.to_df().operation()`

<div id="issue-results">
  ### 問題: 結果が異なる
</div>

何が起きているかを把握するには、デバッグログを有効にします:

```python theme={null}
from chdb.datastore.config import config
config.enable_debug()

# 生成されるSQLを確認する
ds.filter(ds['x'] > 10).explain()
```

<div id="issue-slow">
  ### 問題: パフォーマンスが低下している
</div>

実行パターンを確認してください:

```python theme={null}
# 悪い例: 小さな実行を複数回行う
for i in range(1000):
    result = ds.filter(ds['id'] == i).to_df()

# 良い例: 一度にまとめて実行する
result = ds.filter(ds['id'].isin(ids)).to_df()
```

<div id="issue-types">
  ### 問題: 型の不一致
</div>

DataStore では推論される型が異なる場合があります:

```python theme={null}
# 型を確認する
print(ds.dtypes)

# 強制変換
ds['col'] = ds['col'].astype('int64')
```

***

<div id="gradual">
  ## 段階的移行戦略
</div>

<div id="week-1">
  ### 第1週: 互換性を検証する
</div>

```python theme={null}
# 両方のインポートを保持する
import pandas as pd
from chdb import datastore as ds

# 結果を比較する
pdf = pd.read_csv("data.csv")
dsf = ds.read_csv("data.csv")

# 一致することを確認する
assert pdf.equals(dsf.to_pandas())
```

<div id="week-2">
  ### 第2週: 単純なスクリプトに切り替える
</div>

まずは、次のようなスクリプトから始めます:

* 大きなファイルを読み込む
* フィルタリングや集計を行う
* カスタムの apply 関数を使用しない

<div id="week-3">
  ### 第3週: 複雑なケースへの対応
</div>

カスタム関数を含むスクリプトの場合:

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

# 重い処理は DataStore に任せる
ds = pd.read_csv("data.csv")
ds = ds.filter(ds['year'] == 2024)  # SQL

# カスタム処理のために変換する
df = ds.to_df()
result = df.apply(my_custom_function)
```

<div id="week-4">
  ### 第4週: 完全移行
</div>

すべてのスクリプトでDataStoreをインポートするように切り替えます。

***

<div id="faq">
  ## よくある質問
</div>

<div id="faq-both">
  ### pandas と DataStore の両方を使えますか？
</div>

はい！両者は自由に変換できます。

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

# DataStore から pandas へ
df = ds_result.to_pandas()

# pandas から DataStore へ  
ds = ds.DataFrame(pd_result)
```

<div id="faq-tests">
  ### テストは引き続き通りますか？
</div>

ほとんどのテストは通るはずです。比較テストについては、pandas に変換してください。

```python theme={null}
def test_my_function():
    result = my_function()
    expected = pd.DataFrame(...)
    pd.testing.assert_frame_equal(result.to_pandas(), expected)
```

<div id="faq-jupyter">
  ### Jupyter で DataStore を使用できますか？
</div>

はい！DataStore は Jupyter ノートブックで使用できます:

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

ds = pd.read_csv("data.csv")
ds.head()  # Jupyterで綺麗に表示される
```

<div id="faq-issues">
  ### 問題はどこに報告すればよいですか？
</div>

互換性に関する問題を見つけた場合は、以下で報告してください。
[https://github.com/chdb-io/chdb/issues](https://github.com/chdb-io/chdb/issues)