عمليات الإدخال/الإخراج في DataStore

قراءة البيانات وكتابتها باستخدام DataStore - جميع التنسيقات والوجهات المدعومة

يدعم DataStore القراءة من تنسيقات ملفات ومصادر بيانات متعددة، والكتابة إلى كلٍ منها.

​

قراءة البيانات

​

ملفات CSV

read_csv(filepath_or_buffer, sep=',', header='infer', names=None, 
         usecols=None, dtype=None, nrows=None, skiprows=None,
         compression=None, encoding=None, **kwargs)

أمثلة:

from chdb import datastore as pd

# Basic CSV read
ds = pd.read_csv("data.csv")

# With options
ds = pd.read_csv(
    "data.csv",
    sep=";",                    # Custom delimiter
    header=0,                   # Header row index
    names=['a', 'b', 'c'],      # Custom column names
    usecols=['a', 'b'],         # Only read specific columns
    dtype={'a': 'Int64'},       # Specify dtypes
    nrows=1000,                 # Read only first 1000 rows
    skiprows=1,                 # Skip first row
    compression='gzip',         # Compressed file
    encoding='utf-8'            # Encoding
)

# From URL
ds = pd.read_csv("https://example.com/data.csv")

​

ملفات Parquet

يوصى بها لمجموعات البيانات الكبيرة - تنسيق عمودي الأعمدة مع ضغط أفضل.

read_parquet(path, columns=None, **kwargs)

أمثلة:

# Basic Parquet read
ds = pd.read_parquet("data.parquet")

# Read specific columns only (efficient - only reads needed data)
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2', 'col3'])

# From S3
ds = pd.read_parquet("s3://bucket/data.parquet")

​

ملفات JSON

read_json(path_or_buf, orient=None, lines=False, **kwargs)

أمثلة:

# Standard JSON
ds = pd.read_json("data.json")

# JSON Lines (newline-delimited)
ds = pd.read_json("data.jsonl", lines=True)

# JSON with specific orientation
ds = pd.read_json("data.json", orient='records')

​

ملفات إكسل

read_excel(io, sheet_name=0, header=0, names=None, **kwargs)

أمثلة:

# Read first sheet
ds = pd.read_excel("data.xlsx")

# Read specific sheet
ds = pd.read_excel("data.xlsx", sheet_name="Sheet1")
ds = pd.read_excel("data.xlsx", sheet_name=2)  # Third sheet

# Read multiple sheets (returns dict)
sheets = pd.read_excel("data.xlsx", sheet_name=['Sheet1', 'Sheet2'])

​

قواعد بيانات SQL

read_sql(sql, con, **kwargs)

أمثلة:

# Read from SQL query
ds = pd.read_sql("SELECT * FROM users", connection)
ds = pd.read_sql("SELECT * FROM orders WHERE date > '2024-01-01'", connection)

​

صيغ أخرى

# Feather (Arrow)
ds = pd.read_feather("data.feather")

# ORC
ds = pd.read_orc("data.orc")

# Pickle
ds = pd.read_pickle("data.pkl")

# Fixed-width formatted
ds = pd.read_fwf("data.txt", widths=[10, 20, 15])

# HTML tables
ds = pd.read_html("https://example.com/table.html")[0]

---

​

كتابة البيانات

​

to_csv

التصدير بتنسيق CSV.

to_csv(path_or_buf=None, sep=',', na_rep='', header=True, 
       index=True, mode='w', compression=None, **kwargs)

أمثلة:

ds = pd.read_parquet("data.parquet")

# Basic export
ds.to_csv("output.csv")

# With options
ds.to_csv(
    "output.csv",
    sep=";",                    # Custom delimiter
    index=False,                # Don't include index
    header=True,                # Include header
    na_rep='NULL',              # Represent NaN as 'NULL'
    compression='gzip'          # Compress output
)

# To string
csv_string = ds.to_csv()

​

to_parquet

التصدير بتنسيق Parquet (يُنصح بها للبيانات الكبيرة).

to_parquet(path, engine='pyarrow', compression='snappy', **kwargs)

أمثلة:

# Basic export
ds.to_parquet("output.parquet")

# With compression options
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')

# Partitioned output
ds.to_parquet(
    "output/",
    partition_cols=['year', 'month']
)

​

to_json

تصدير بتنسيق JSON.

to_json(path_or_buf=None, orient='records', lines=False, **kwargs)

أمثلة:

# Standard JSON (array of records)
ds.to_json("output.json", orient='records')

# JSON Lines (one JSON object per line)
ds.to_json("output.jsonl", lines=True)

# Different orientations
ds.to_json("output.json", orient='split')    # {columns, data, index}
ds.to_json("output.json", orient='records')  # [{col: val}, ...]
ds.to_json("output.json", orient='columns')  # {col: {idx: val}}

# To string
json_string = ds.to_json()

​

to_excel

التصدير بتنسيق Excel.

to_excel(excel_writer, sheet_name='Sheet1', index=True, **kwargs)

أمثلة:

# Single sheet
ds.to_excel("output.xlsx")
ds.to_excel("output.xlsx", sheet_name="Data", index=False)

# Multiple sheets
with pd.ExcelWriter("output.xlsx") as writer:
    ds1.to_excel(writer, sheet_name="Sales")
    ds2.to_excel(writer, sheet_name="Inventory")

​

to_sql

صدِّر إلى قاعدة بيانات SQL أو أنشئ عبارة SQL.

to_sql(name=None, con=None, schema=None, if_exists='fail', **kwargs)

أمثلة:

# Generate SQL query (no execution)
sql = ds.to_sql()
print(sql)
# SELECT ...
# FROM ...
# WHERE ...

# Write to database
ds.to_sql("table_name", connection, if_exists='replace')

​

طرق أخرى للتصدير

# To pandas DataFrame
df = ds.to_df()
df = ds.to_pandas()

# To Arrow Table
table = ds.to_arrow()

# To NumPy array
arr = ds.to_numpy()

# To dictionary
d = ds.to_dict()
d = ds.to_dict(orient='records')  # List of dicts
d = ds.to_dict(orient='list')     # Dict of lists

# To records (list of tuples)
records = ds.to_records()

# To string
s = ds.to_string()
s = ds.to_string(max_rows=100)

# To Markdown
md = ds.to_markdown()

# To HTML
html = ds.to_html()

# To LaTeX
latex = ds.to_latex()

# To clipboard
ds.to_clipboard()

# To pickle
ds.to_pickle("output.pkl")

# To feather
ds.to_feather("output.feather")

---

​

مقارنة تنسيقات الملفات

التنسيق	سرعة القراءة	سرعة الكتابة	حجم الملف	المخطط	الأنسب لـ
Parquet	سريعة	سريعة	صغير	نعم	مجموعات البيانات الكبيرة، التحليلات
CSV	متوسطة	سريعة	كبير	لا	التوافق، البيانات البسيطة
JSON	بطيئة	متوسطة	كبير	جزئي	واجهات API، البيانات المتداخلة
Excel	بطيئة	بطيئة	متوسط	جزئي	المشاركة مع المستخدمين غير التقنيين
Feather	سريعة جدًا	سريعة جدًا	متوسط	نعم	الاستخدام بين العمليات، pandas

​

التوصيات

1. لأعباء عمل التحليلات: استخدم Parquet

   • يتيح التنسيق العمودي قراءة الأعمدة المطلوبة فقط
   • ضغط ممتاز
   • يحافظ على أنواع البيانات

2. لتبادل البيانات: استخدم CSV أو JSON

   • توافق واسع
   • سهل القراءة للبشر

3. للتوافق مع pandas: استخدم Feather أو Arrow

   • الأسرع في التسلسل
   • يحافظ على الأنواع

---

​

دعم الضغط

​

قراءة الملفات المضغوطة

# Auto-detect from extension
ds = pd.read_csv("data.csv.gz")
ds = pd.read_csv("data.csv.bz2")
ds = pd.read_csv("data.csv.xz")
ds = pd.read_csv("data.csv.zst")

# Explicit compression
ds = pd.read_csv("data.csv", compression='gzip')

​

كتابة الملفات المضغوطة

# CSV with compression
ds.to_csv("output.csv.gz", compression='gzip')
ds.to_csv("output.csv.bz2", compression='bz2')

# Parquet (always compressed)
ds.to_parquet("output.parquet", compression='snappy')  # Default
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')    # Best ratio
ds.to_parquet("output.parquet", compression='lz4')     # Fastest

​

خيارات الضغط

الضغط	السرعة	النسبة	حالة استخدام
snappy	سريع جدًا	منخفضة	الافتراضي لـ Parquet
lz4	سريع جدًا	منخفضة	أولوية السرعة
gzip	متوسطة	عالية	التوافق
zstd	سريع	عالية جدًا	أفضل توازن
bz2	بطيء	عالية جدًا	أقصى ضغط

---

​

الإدخال/الإخراج المتدفق

للملفات الكبيرة جدًا التي لا تتسع لها الذاكرة:

​

القراءة على أجزاء

# Read in chunks
for chunk in pd.read_csv("large.csv", chunksize=100000):
    # Process each chunk
    process(chunk)

# Using iterator
reader = pd.read_csv("large.csv", iterator=True)
chunk = reader.get_chunk(10000)

​

استخدام ميزة متدفق في ClickHouse

from chdb.datastore import DataStore

# Stream from file without loading all into memory
ds = DataStore.from_file("huge.parquet")

# Operations are lazy - only computes what's needed
result = ds.filter(ds['amount'] > 1000).head(100)

---

​

مصادر البيانات البعيدة

​

HTTP/HTTPS

# Read from URL
ds = pd.read_csv("https://example.com/data.csv")
ds = pd.read_parquet("https://example.com/data.parquet")

​

S3

from chdb.datastore import DataStore

# Anonymous access
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")

# With credentials
ds = DataStore.from_s3(
    "s3://bucket/data.parquet",
    access_key_id="KEY",
    secret_access_key="SECRET"
)

​

GCS وAzure وHDFS

راجع Factory Methods للتعرّف على خيارات cloud storage.

---

​

أفضل الممارسات

​

1. استخدم Parquet للملفات الكبيرة

# Convert CSV to Parquet for better performance
ds = pd.read_csv("large.csv")
ds.to_parquet("large.parquet")

# Future reads are much faster
ds = pd.read_parquet("large.parquet")

​

2. اختر فقط الأعمدة التي تحتاج إليها

# Efficient - only reads col1 and col2
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2'])

# Inefficient - reads all columns then filters
ds = pd.read_parquet("data.parquet")[['col1', 'col2']]

​

3. استخدم الضغط

# Smaller file size, usually faster due to less I/O
ds.to_parquet("output.parquet", compression='zstd')

​

4. الكتابة على دفعات

# Write once, not in a loop
result = process_all_data(ds)
result.to_parquet("output.parquet")

# NOT this (inefficient)
for chunk in chunks:
    chunk.to_parquet(f"output_{i}.parquet")