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

# مرجع فئة DataStore

> مرجع واجهة برمجة التطبيقات الكامل لفئات DataStore وColumnExpr وLazyGroupBy وLazySeries

يوثّق هذا المرجع الفئات الأساسية في واجهة برمجة تطبيقات DataStore.

<div id="datastore">
  ## DataStore
</div>

الفئة الرئيسية الشبيهة بـ DataFrame للتعامل مع البيانات.

```python theme={null}
from chdb.datastore import DataStore
```

<div id="datastore-constructor">
  ### المُنشئ
</div>

```python theme={null}
DataStore(data=None, columns=None, index=None, dtype=None, copy=None)
```

**المعلمات:**

| المعلمة   | النوع                         | الوصف                |
| --------- | ----------------------------- | -------------------- |
| `data`    | dict/list/DataFrame/DataStore | بيانات الإدخال       |
| `columns` | list                          | أسماء الأعمدة        |
| `index`   | Index                         | فهرس الصف            |
| `dtype`   | dict                          | أنواع بيانات الأعمدة |
| `copy`    | bool                          | نسخ البيانات         |

**أمثلة:**

```python theme={null}
# From dictionary
ds = DataStore({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})

# From pandas DataFrame
import pandas as pd
ds = DataStore(pd.DataFrame({'a': [1, 2, 3]}))

# Empty DataStore
ds = DataStore()
```

<div id="datastore-properties">
  ### الخصائص
</div>

| الخاصية   | النوع     | الوصف                           |
| --------- | --------- | ------------------------------- |
| `columns` | Index     | أسماء الأعمدة                   |
| `dtypes`  | Series    | أنواع بيانات الأعمدة            |
| `shape`   | tuple     | (الصفوف، الأعمدة)               |
| `size`    | int       | إجمالي العناصر                  |
| `ndim`    | int       | عدد الأبعاد (2)                 |
| `empty`   | bool      | هل DataFrame فارغ               |
| `values`  | ndarray   | البيانات الداخلية كمصفوفة NumPy |
| `index`   | Index     | فهرس الصف                       |
| `T`       | DataStore | المنقول                         |
| `axes`    | list      | قائمة المحاور                   |

<div id="datastore-factory">
  ### أساليب الإنشاء
</div>

| الأسلوب                   | الوصف                         |
| ------------------------- | ----------------------------- |
| `uri(uri)`                | أسلوب إنشاء عام من URI        |
| `from_file(path, ...)`    | إنشاء من ملف                  |
| `from_df(df)`             | إنشاء من pandas DataFrame     |
| `from_s3(url, ...)`       | إنشاء من S3                   |
| `from_gcs(url, ...)`      | إنشاء من Google Cloud Storage |
| `from_azure(url, ...)`    | إنشاء من Azure Blob           |
| `from_mysql(...)`         | إنشاء من MySQL                |
| `from_postgresql(...)`    | إنشاء من PostgreSQL           |
| `from_clickhouse(...)`    | إنشاء من ClickHouse           |
| `from_mongodb(...)`       | إنشاء من MongoDB              |
| `from_sqlite(...)`        | إنشاء من SQLite               |
| `from_iceberg(path)`      | إنشاء من جدول Iceberg         |
| `from_delta(path)`        | إنشاء من Delta Lake           |
| `from_numbers(n)`         | إنشاء بأرقام متسلسلة          |
| `from_random(rows, cols)` | إنشاء ببيانات عشوائية         |
| `run_sql(query)`          | إنشاء من استعلام SQL          |

راجع [أساليب الإنشاء](/ar/products/chdb/datastore/factory-methods) للاطلاع على التفاصيل.

<div id="datastore-query">
  ### أساليب الاستعلام
</div>

| Method                        | Returns     | Description            |
| ----------------------------- | ----------- | ---------------------- |
| `select(*cols)`               | DataStore   | تحديد الأعمدة          |
| `filter(condition)`           | DataStore   | تصفية الصفوف           |
| `where(condition)`            | DataStore   | اسم مستعار لـ `filter` |
| `sort(*cols, ascending=True)` | DataStore   | فرز الصفوف             |
| `orderby(*cols)`              | DataStore   | اسم مستعار لـ `sort`   |
| `limit(n)`                    | DataStore   | تقييد عدد الصفوف       |
| `offset(n)`                   | DataStore   | تخطي الصفوف            |
| `distinct(subset=None)`       | DataStore   | إزالة التكرار          |
| `groupby(*cols)`              | LazyGroupBy | تجميع الصفوف           |
| `having(condition)`           | DataStore   | تصفية المجموعات        |
| `join(right, ...)`            | DataStore   | ربط كائنات DataStore   |
| `union(other, all=False)`     | DataStore   | دمج كائنات DataStore   |
| `when(cond, val)`             | CaseWhen    | CASE WHEN              |

راجع [بناء الاستعلام](/ar/products/chdb/datastore/query-building) للاطلاع على التفاصيل.

<div id="datastore-pandas">
  ### الأساليب المتوافقة مع Pandas
</div>

اطّلع على [التوافق مع Pandas](/ar/products/chdb/datastore/pandas-compat) للحصول على القائمة الكاملة التي تضم 209 أساليب.

**الفهرسة:**
`head()`, `tail()`, `sample()`, `loc`, `iloc`, `at`, `iat`, `query()`, `isin()`, `where()`, `mask()`, `get()`, `xs()`, `pop()`

**التجميع:**
`sum()`, `mean()`, `std()`, `var()`, `min()`, `max()`, `median()`, `count()`, `nunique()`, `quantile()`, `describe()`, `corr()`, `cov()`, `skew()`, `kurt()`

**المعالجة:**
`drop()`, `drop_duplicates()`, `dropna()`, `fillna()`, `replace()`, `rename()`, `assign()`, `astype()`, `copy()`

**الفرز:**
`sort_values()`, `sort_index()`, `nlargest()`, `nsmallest()`, `rank()`

**إعادة التشكيل:**
`pivot()`, `pivot_table()`, `melt()`, `stack()`, `unstack()`, `transpose()`, `explode()`, `squeeze()`

**الدمج:**
`merge()`, `join()`, `concat()`, `append()`, `combine()`, `update()`, `compare()`

**التطبيق/التحويل:**
`apply()`, `applymap()`, `map()`, `agg()`, `transform()`, `pipe()`, `groupby()`

**السلاسل الزمنية:**
`rolling()`, `expanding()`, `ewm()`, `shift()`, `diff()`, `pct_change()`, `resample()`

<div id="datastore-io">
  ### أساليب الإدخال/الإخراج
</div>

| الأسلوب                 | الوصف                      |
| ----------------------- | -------------------------- |
| `to_csv(path, ...)`     | تصدير إلى CSV              |
| `to_parquet(path, ...)` | تصدير إلى Parquet          |
| `to_json(path, ...)`    | تصدير إلى JSON             |
| `to_excel(path, ...)`   | تصدير إلى Excel            |
| `to_df()`               | تحويل إلى pandas DataFrame |
| `to_pandas()`           | اسم مستعار لـ `to_df`      |
| `to_arrow()`            | تحويل إلى Arrow Table      |
| `to_dict(orient)`       | تحويل إلى قاموس            |
| `to_records()`          | تحويل إلى سجلات            |
| `to_numpy()`            | تحويل إلى مصفوفة NumPy     |
| `to_sql()`              | إنشاء سلسلة SQL            |
| `to_string()`           | تمثيل كسلسلة نصية          |
| `to_markdown()`         | جدول Markdown              |
| `to_html()`             | جدول HTML                  |

راجع [عمليات الإدخال/الإخراج](/ar/products/chdb/datastore/io) لمزيد من التفاصيل.

<div id="datastore-debug">
  ### دوال تصحيح الأخطاء
</div>

| الدالة                   | الوصف                      |
| ------------------------ | -------------------------- |
| `explain(verbose=False)` | عرض خطة التنفيذ            |
| `clear_cache()`          | مسح النتائج المخزنة مؤقتًا |

راجع [تصحيح الأخطاء](/ar/products/chdb/debugging/index) لمزيد من التفاصيل.

<div id="datastore-magic">
  ### الأساليب السحرية
</div>

| الطريقة                   | الوصف                                          |         |
| ------------------------- | ---------------------------------------------- | ------- |
| `__getitem__(key)`        | `ds['col']`, `ds[['a', 'b']]`, `ds[condition]` |         |
| `__setitem__(key, value)` | `ds['col'] = value`                            |         |
| `__delitem__(key)`        | `del ds['col']`                                |         |
| `__len__()`               | `len(ds)`                                      |         |
| `__iter__()`              | `for col in ds`                                |         |
| `__contains__(key)`       | `'col' in ds`                                  |         |
| `__repr__()`              | `repr(ds)`                                     |         |
| `__str__()`               | `str(ds)`                                      |         |
| `__eq__(other)`           | `ds == other`                                  |         |
| `__ne__(other)`           | `ds != other`                                  |         |
| `__lt__(other)`           | `ds < other`                                   |         |
| `__le__(other)`           | `ds <= other`                                  |         |
| `__gt__(other)`           | `ds > other`                                   |         |
| `__ge__(other)`           | `ds >= other`                                  |         |
| `__add__(other)`          | `ds + other`                                   |         |
| `__sub__(other)`          | `ds - other`                                   |         |
| `__mul__(other)`          | `ds * other`                                   |         |
| `__truediv__(other)`      | `ds / other`                                   |         |
| `__floordiv__(other)`     | `ds // other`                                  |         |
| `__mod__(other)`          | `ds % other`                                   |         |
| `__pow__(other)`          | `ds ** other`                                  |         |
| `__and__(other)`          | `ds & other`                                   |         |
| `__or__(other)`           | \`ds                                           | other\` |
| `__invert__()`            | `~ds`                                          |         |
| `__neg__()`               | `-ds`                                          |         |
| `__pos__()`               | `+ds`                                          |         |
| `__abs__()`               | `abs(ds)`                                      |         |

***

<div id="columnexpr">
  ## ColumnExpr
</div>

يمثل تعبيرًا لعمود في سياق التقييم الكسول. ويُعاد عند الوصول إلى عمود.

```python theme={null}
# ColumnExpr is returned automatically
col = ds['name']  # Returns ColumnExpr
```

<div id="datastore-properties">
  ### الخصائص
</div>

| الخاصية | النوع | الوصف        |
| ------- | ----- | ------------ |
| `name`  | str   | اسم العمود   |
| `dtype` | dtype | نوع البيانات |

<div id="columnexpr-accessors">
  ### Accessors
</div>

| Accessor | الوصف                 | الأساليب           |
| -------- | --------------------- | ------------------ |
| `.str`   | عمليات السلاسل النصية | 56 أسلوبًا         |
| `.dt`    | عمليات DateTime       | أكثر من 42 أسلوبًا |
| `.arr`   | عمليات Array          | 37 أسلوبًا         |
| `.json`  | تحليل JSON            | 13 أسلوبًا         |
| `.url`   | تحليل URL             | 15 أسلوبًا         |
| `.ip`    | عمليات عناوين IP      | 9 أساليب           |
| `.geo`   | عمليات Geo/المسافة    | 14 أسلوبًا         |

راجع [Accessors](/ar/products/chdb/datastore/accessors) للاطلاع على الوثائق الكاملة.

<div id="columnexpr-arithmetic">
  ### العمليات الحسابية
</div>

```python theme={null}
ds['total'] = ds['price'] * ds['quantity']
ds['profit'] = ds['revenue'] - ds['cost']
ds['ratio'] = ds['a'] / ds['b']
ds['squared'] = ds['value'] ** 2
ds['remainder'] = ds['value'] % 10
```

<div id="columnexpr-comparison">
  ### عمليات المقارنة
</div>

```python theme={null}
ds[ds['age'] > 25]           # Greater than
ds[ds['age'] >= 25]          # Greater or equal
ds[ds['age'] < 25]           # Less than
ds[ds['age'] <= 25]          # Less or equal
ds[ds['name'] == 'Alice']    # Equal
ds[ds['name'] != 'Bob']      # Not equal
```

<div id="columnexpr-logical">
  ### العمليات المنطقية
</div>

```python theme={null}
ds[(ds['age'] > 25) & (ds['city'] == 'NYC')]    # AND
ds[(ds['age'] > 25) | (ds['city'] == 'NYC')]    # OR
ds[~(ds['status'] == 'inactive')]               # NOT
```

<div id="columnexpr-methods">
  ### الأساليب
</div>

| الأسلوب                      | الوصف                   |
| ---------------------------- | ----------------------- |
| `as_(alias)`                 | تعيين اسم مستعار        |
| `cast(dtype)`                | التحويل إلى نوع         |
| `astype(dtype)`              | اسم مستعار لـ `cast`    |
| `isnull()`                   | تكون NULL               |
| `notnull()`                  | ليست NULL               |
| `isna()`                     | اسم مستعار لـ `isnull`  |
| `notna()`                    | اسم مستعار لـ `notnull` |
| `isin(values)`               | ضمن قائمة من القيم      |
| `between(low, high)`         | بين قيمتين              |
| `fillna(value)`              | ملء قيم NULL            |
| `replace(to_replace, value)` | استبدال القيم           |
| `clip(lower, upper)`         | تقييد القيم             |
| `abs()`                      | القيمة المطلقة          |
| `round(decimals)`            | تقريب القيم             |
| `floor()`                    | التقريب لأسفل           |
| `ceil()`                     | التقريب لأعلى           |
| `apply(func)`                | تطبيق دالة              |
| `map(mapper)`                | تحويل القيم             |

<div id="columnexpr-aggregation">
  ### طرق التجميع
</div>

| الطريقة       | الوصف                  |
| ------------- | ---------------------- |
| `sum()`       | المجموع                |
| `mean()`      | المتوسط                |
| `avg()`       | اسم مستعار لـ `mean()` |
| `min()`       | الحد الأدنى            |
| `max()`       | الحد الأقصى            |
| `count()`     | عدد القيم غير `NULL`   |
| `nunique()`   | عدد القيم الفريدة      |
| `std()`       | الانحراف المعياري      |
| `var()`       | التباين                |
| `median()`    | الوسيط                 |
| `quantile(q)` | الكمية                 |
| `first()`     | القيمة الأولى          |
| `last()`      | القيمة الأخيرة         |
| `any()`       | أي قيمة `true`         |
| `all()`       | جميع القيم `true`      |

***

<div id="lazygroupby">
  ## LazyGroupBy
</div>

يمثل DataStore مُجمَّعًا لعمليات التجميع.

```python theme={null}
# LazyGroupBy is returned automatically
grouped = ds.groupby('category')  # Returns LazyGroupBy
```

<div id="columnexpr-methods">
  ### الأساليب
</div>

| الأسلوب           | القيمة المعادة | الوصف                        |
| ----------------- | -------------- | ---------------------------- |
| `agg(spec)`       | DataStore      | تجميع                        |
| `aggregate(spec)` | DataStore      | اسم مستعار لـ agg            |
| `sum()`           | DataStore      | المجموع لكل مجموعة           |
| `mean()`          | DataStore      | المتوسط لكل مجموعة           |
| `count()`         | DataStore      | العدد لكل مجموعة             |
| `min()`           | DataStore      | الحد الأدنى لكل مجموعة       |
| `max()`           | DataStore      | الحد الأقصى لكل مجموعة       |
| `std()`           | DataStore      | الانحراف المعياري لكل مجموعة |
| `var()`           | DataStore      | التباين لكل مجموعة           |
| `median()`        | DataStore      | الوسيط لكل مجموعة            |
| `nunique()`       | DataStore      | عدد القيم الفريدة لكل مجموعة |
| `first()`         | DataStore      | أول قيمة لكل مجموعة          |
| `last()`          | DataStore      | آخر قيمة لكل مجموعة          |
| `nth(n)`          | DataStore      | القيمة رقم n في كل مجموعة    |
| `head(n)`         | DataStore      | أول n عناصر في كل مجموعة     |
| `tail(n)`         | DataStore      | آخر n عناصر في كل مجموعة     |
| `apply(func)`     | DataStore      | تطبيق دالة على كل مجموعة     |
| `transform(func)` | DataStore      | تحويل كل مجموعة              |
| `filter(func)`    | DataStore      | تصفية المجموعات              |

<div id="lazygroupby-columns">
  ### اختيار العمود
</div>

```python theme={null}
# Select column after groupby
grouped['amount'].sum()     # Returns DataStore
grouped[['a', 'b']].sum()   # Returns DataStore
```

<div id="lazygroupby-agg">
  ### مواصفات التجميع
</div>

```python theme={null}
# Single aggregation
grouped.agg({'amount': 'sum'})

# Multiple aggregations per column
grouped.agg({'amount': ['sum', 'mean', 'count']})

# Named aggregations
grouped.agg(
    total=('amount', 'sum'),
    average=('amount', 'mean'),
    count=('id', 'count')
)
```

***

<div id="lazyseries">
  ## LazySeries
</div>

يمثل سلسلة مؤجلة (عمودًا واحدًا).

<div id="datastore-properties">
  ### الخصائص
</div>

| الخاصية | النوع | الوصف        |
| ------- | ----- | ------------ |
| `name`  | str   | اسم السلسلة  |
| `dtype` | dtype | نوع البيانات |

<div id="columnexpr-methods">
  ### الأساليب
</div>

يرث معظم الأساليب من `ColumnExpr`. أهم الأساليب:

| الأسلوب          | الوصف                 |
| ---------------- | --------------------- |
| `value_counts()` | تكرارات القيم         |
| `unique()`       | القيم الفريدة         |
| `nunique()`      | عدد القيم الفريدة     |
| `mode()`         | قيمة المنوال          |
| `to_list()`      | التحويل إلى قائمة     |
| `to_numpy()`     | التحويل إلى مصفوفة    |
| `to_frame()`     | التحويل إلى DataStore |

***

<div id="related">
  ## الفئات ذات الصلة
</div>

<div id="f-class">
  ### F (الدوال)
</div>

مساحة أسماء لدوال ClickHouse.

```python theme={null}
from chdb.datastore import F, Field

# Aggregations
F.sum(Field('amount'))
F.avg(Field('price'))
F.count(Field('id'))
F.quantile(Field('value'), 0.95)

# Conditional
F.sum_if(Field('amount'), Field('status') == 'completed')
F.count_if(Field('active'))

# Window
F.row_number().over(order_by='date')
F.lag('price', 1).over(partition_by='product', order_by='date')
```

راجع [التجميع](/ar/products/chdb/datastore/aggregation#f-namespace) لمزيد من التفاصيل.

<div id="field-class">
  ### حقل
</div>

إشارة إلى عمود باسمه.

```python theme={null}
from chdb.datastore import Field

# Create field reference
amount = Field('amount')
price = Field('price')

# Use in expressions
F.sum(Field('amount'))
F.avg(Field('price'))
```

<div id="casewhen-class">
  ### CaseWhen
</div>

أداة إنشاء لتعبيرات CASE WHEN.

```python theme={null}
# Create case-when expression
result = (ds
    .when(ds['score'] >= 90, 'A')
    .when(ds['score'] >= 80, 'B')
    .when(ds['score'] >= 70, 'C')
    .otherwise('F')
)

# Assign to column
ds['grade'] = result
```

<div id="window-class">
  ### Window
</div>

مواصفة Window لدوال النافذة.

```python theme={null}
from chdb.datastore import F

# Create window
window = F.window(
    partition_by='category',
    order_by='date',
    rows_between=(-7, 0)
)

# Use with aggregation
ds['rolling_avg'] = F.avg('price').over(window)
```