# NebulaDataEngine

**Repository Path**: szw1259577135/nebula-data-engine

## Basic Information

- **Project Name**: NebulaDataEngine
- **Description**: NebulaDataEngine 是一个灵活的数据引擎，支持多种数据源类型，包括内存中的数据结构（如 DataFrame、字典、列表）、文件（如 CSV、JSON、Excel）以及 MongoDB 数据库。它提供了一个统一的接口来操作这些数据源，使得开发者可以轻松地在不同的数据源之间切换，而无需修改大量的代码。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-01-12
- **Last Updated**: 2025-01-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NebulaDataEngine

`NebulaDataEngine` 是一个灵活的数据引擎，支持多种数据源类型，包括内存中的数据结构（如 `DataFrame`、字典、列表）、文件（如 CSV、JSON、Excel）以及 MongoDB 数据库。它提供了一个统一的接口来操作这些数据源，使得开发者可以轻松地在不同的数据源之间切换，而无需修改大量的代码。

## 功能特性

- **多数据源支持**：支持内存中的数据结构（`DataFrame`、字典、列表）、文件（CSV、JSON、Excel）以及 MongoDB 数据库。
- **统一的 API**：提供统一的接口来操作不同的数据源，简化了数据操作的复杂性。
- **自动建表**：支持自动创建表或集合，减少手动配置的工作量。
- **自动生成 ID**：支持自动为数据生成唯一 ID，简化数据管理。
- **多种返回格式**：支持返回 `JSON` 或 `DataFrame` 格式的数据，方便后续处理。
- **事务支持**：在 MongoDB 中支持事务操作，确保数据的一致性。

## 安装

确保你已经安装了以下依赖：

- `pandas`
- `pymongo`

你可以通过以下命令安装这些依赖：

```bash
pip install pandas pymongo
```

## 使用示例

# NebulaDataEngine 使用示例

`NebulaDataEngine` 提供了多种数据源的支持，并且通过统一的 API 简化了数据操作。以下是一些更详细的使用示例，涵盖了不同的数据源和常见操作。

## 1. 使用内存中的数据

### 1.1 使用 DataFrame 作为数据源

```python
from nebula_data_engine import NebulaDataEngine
import pandas as pd

# 创建一个 DataFrame
data = pd.DataFrame({
    'name': ['Alice', 'Bob'],
    'age': [25, 30]
})

# 初始化引擎
engine = NebulaDataEngine(data, table_name='users')

# 插入数据
new_id = engine.save({'name': 'Charlie', 'age': 35})
print(f"插入的数据 ID: {new_id}")

# 查询数据
result = engine.find({'name': 'Alice'})
print("查询结果:", result)

# 更新数据
engine.update({'name': 'Alice'}, {'age': 26})
updated_result = engine.find({'name': 'Alice'})
print("更新后的结果:", updated_result)

# 删除数据
deleted_count = engine.delete({'name': 'Bob'})
print(f"删除了 {deleted_count} 条数据")

# 查询所有数据
all_data = engine.findAll()
print("所有数据:", all_data)
```

### 1.2 使用字典作为数据源

```python
from nebula_data_engine import NebulaDataEngine

# 使用字典作为数据源
data = {
    'users': [
        {'name': 'Alice', 'age': 25},
        {'name': 'Bob', 'age': 30}
    ]
}

# 初始化引擎
engine = NebulaDataEngine(data, table_name='users')

# 插入数据
new_id = engine.save({'name': 'Charlie', 'age': 35})
print(f"插入的数据 ID: {new_id}")

# 查询数据
result = engine.find({'name': 'Alice'})
print("查询结果:", result)
```

### 1.3 使用列表作为数据源

```python
from nebula_data_engine import NebulaDataEngine

# 使用列表作为数据源
data = [
    {'name': 'Alice', 'age': 25},
    {'name': 'Bob', 'age': 30}
]

# 初始化引擎
engine = NebulaDataEngine(data, table_name='users')

# 插入数据
new_id = engine.save({'name': 'Charlie', 'age': 35})
print(f"插入的数据 ID: {new_id}")

# 查询数据
result = engine.find({'name': 'Alice'})
print("查询结果:", result)
```

## 2. 使用文件作为数据源

### 2.1 使用 CSV 文件

```python
from nebula_data_engine import NebulaDataEngine

# 使用 CSV 文件作为数据源
engine = NebulaDataEngine('data.csv', table_name='users')

# 插入数据
new_id = engine.save({'name': 'David', 'age': 40})
print(f"插入的数据 ID: {new_id}")

# 查询所有数据
all_data = engine.findAll()
print("所有数据:", all_data)

# 分页查询数据
page_data = engine.findPage({}, page=1, page_size=2)
print("分页查询结果:", page_data)
```

### 2.2 使用 Excel 文件

```python
from nebula_data_engine import NebulaDataEngine

# 使用 Excel 文件作为数据源
engine = NebulaDataEngine('data.xlsx', table_name='users')

# 插入数据
new_id = engine.save({'name': 'Eve', 'age': 45})
print(f"插入的数据 ID: {new_id}")

# 查询数据
result = engine.find({'name': 'Eve'})
print("查询结果:", result)
```

### 2.3 使用 JSON 文件

```python
from nebula_data_engine import NebulaDataEngine

# 使用 JSON 文件作为数据源
engine = NebulaDataEngine('data.json', table_name='users')

# 插入数据
new_id = engine.save({'name': 'Frank', 'age': 50})
print(f"插入的数据 ID: {new_id}")

# 查询数据
result = engine.find({'name': 'Frank'})
print("查询结果:", result)
```

## 3. 使用 MongoDB 作为数据源

### 3.1 基本操作

```python
from nebula_data_engine import NebulaDataEngine

# 使用 MongoDB 连接字符串作为数据源
engine = NebulaDataEngine('mongodb://localhost:27017/mydatabase', table_name='users')

# 插入数据
new_id = engine.save({'name': 'Grace', 'age': 55})
print(f"插入的数据 ID: {new_id}")

# 查询数据
result = engine.find({'name': 'Grace'})
print("查询结果:", result)

# 更新数据
engine.update({'name': 'Grace'}, {'age': 56})
updated_result = engine.find({'name': 'Grace'})
print("更新后的结果:", updated_result)

# 删除数据
deleted_count = engine.delete({'name': 'Grace'})
print(f"删除了 {deleted_count} 条数据")
```

### 3.2 事务操作

```python
from nebula_data_engine import NebulaDataEngine

# 使用 MongoDB 连接字符串作为数据源
engine = NebulaDataEngine('mongodb://localhost:27017/mydatabase', table_name='users')

# 定义事务操作
operations = [
    {"action": "save", "table_name": "users", "data": {"name": "Henry", "age": 60}},
    {"action": "update", "table_name": "users", "query": {"name": "Henry"}, "update_data": {"age": 61}},
    {"action": "delete", "table_name": "users", "query": {"name": "Henry"}}
]

# 执行事务
success = engine.transaction(operations)
print("事务执行结果:", success)
```

## 4. 其他功能

### 4.1 根据 ID 查询数据

```python
from nebula_data_engine import NebulaDataEngine

# 使用 DataFrame 作为数据源
data = pd.DataFrame({
    'name': ['Alice', 'Bob'],
    'age': [25, 30]
})

# 初始化引擎
engine = NebulaDataEngine(data, table_name='users')

# 插入数据
new_id = engine.save({'name': 'Charlie', 'age': 35})

# 根据 ID 查询数据
result = engine.findById(new_id)
print("根据 ID 查询结果:", result)
```

### 4.2 根据 ID 更新数据

```python
from nebula_data_engine import NebulaDataEngine

# 使用 DataFrame 作为数据源
data = pd.DataFrame({
    'name': ['Alice', 'Bob'],
    'age': [25, 30]
})

# 初始化引擎
engine = NebulaDataEngine(data, table_name='users')

# 插入数据
new_id = engine.save({'name': 'Charlie', 'age': 35})

# 根据 ID 更新数据
engine.updateById(new_id, {'age': 36})
updated_result = engine.findById(new_id)
print("根据 ID 更新后的结果:", updated_result)
```

### 4.3 根据 ID 删除数据

```python
from nebula_data_engine import NebulaDataEngine

# 使用 DataFrame 作为数据源
data = pd.DataFrame({
    'name': ['Alice', 'Bob'],
    'age': [25, 30]
})

# 初始化引擎
engine = NebulaDataEngine(data, table_name='users')

# 插入数据
new_id = engine.save({'name': 'Charlie', 'age': 35})

# 根据 ID 删除数据
deleted_count = engine.deleteById(new_id)
print(f"根据 ID 删除了 {deleted_count} 条数据")
```


## API 参考

### `NebulaDataEngine(data, table_name=None, return_format="json", auto_create_table=True, auto_add_id=True)`

- **data**: 数据源，可以是 `DataFrame`、字典、列表、文件路径或 MongoDB 连接字符串。
- **table_name**: 默认表名或集合名。
- **return_format**: 返回数据的格式，支持 `"json"` 或 `"dataframe"`。
- **auto_create_table**: 是否自动创建表或集合。
- **auto_add_id**: 是否自动为数据生成唯一 ID。

### `save(entity, table_name=None)`

插入数据。

- **entity**: 要插入的数据，类型为字典。
- **table_name**: 表名或集合名，默认为初始化时指定的表名。

### `delete(query, table_name=None)`

删除数据。

- **query**: 删除条件，类型为字典。
- **table_name**: 表名或集合名，默认为初始化时指定的表名。

### `deleteById(id, table_name=None)`

根据 ID 删除数据。

- **id**: 要删除的数据的 ID。
- **table_name**: 表名或集合名，默认为初始化时指定的表名。

### `update(query, update_data, table_name=None)`

更新数据。

- **query**: 更新条件，类型为字典。
- **update_data**: 要更新的数据，类型为字典。
- **table_name**: 表名或集合名，默认为初始化时指定的表名。

### `updateById(id, update_data, table_name=None)`

根据 ID 更新数据。

- **id**: 要更新的数据的 ID。
- **update_data**: 要更新的数据，类型为字典。
- **table_name**: 表名或集合名，默认为初始化时指定的表名。

### `find(query, table_name=None)`

查询数据。

- **query**: 查询条件，类型为字典。
- **table_name**: 表名或集合名，默认为初始化时指定的表名。

### `findAll(table_name=None)`

查询所有数据。

- **table_name**: 表名或集合名，默认为初始化时指定的表名。

### `findById(id, table_name=None)`

根据 ID 查询数据。

- **id**: 要查询的数据的 ID。
- **table_name**: 表名或集合名，默认为初始化时指定的表名。

### `findPage(query, page, page_size, table_name=None)`

分页查询数据。

- **query**: 查询条件，类型为字典。
- **page**: 页码。
- **page_size**: 每页的数据量。
- **table_name**: 表名或集合名，默认为初始化时指定的表名。

## 贡献

欢迎贡献代码和提出建议！请通过提交 Issue 或 Pull Request 来参与项目。

## 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。