feat: Add graph_batch and import_documents methods with usage examples and clarify transaction management

Author: tae898

bindings/python/docs/api/database.md

@@ -543,6 +543,70 @@ synchronous workflows.
 
 ---
 
+### graph_batch
+
+```python
+db.graph_batch(...) -> GraphBatch
+```
+
+Create a `GraphBatch` helper for high-throughput graph ingestion.
+
+This is the repository's recommended bulk graph-ingest path from Python when you need to
+load many vertices and edges efficiently.
+
+**Common options:**
+
+- `batch_size`: buffered edge batch size
+- `expected_edge_count`: tuning hint for large graph loads
+- `light_edges`: create property-less edges as light edges
+- `commit_every`: commit cadence during flush
+- `use_wal`: enable WAL for higher durability
+- `parallel_flush`: parallelize flush/close work
+
+**Example:**
+
+```python
+with db.graph_batch(expected_edge_count=50000) as batch:
+    alice = batch.create_vertex("Person", name="Alice")
+    bob = batch.create_vertex("Person", name="Bob")
+    batch.new_edge(alice, "Knows", bob, since=2024)
+```
+
+See [Graph Operations](../guide/graphs.md) and the graph benchmark examples for guidance.
+
+---
+
+### import_documents
+
+```python
+db.import_documents(source: str, document_type: str = "Document", ...) -> ImportResult
+```
+
+Import document-shaped data through ArcadeDB's Java importer framework.
+
+This is a narrow wrapper for file-based document imports such as CSV into a document
+type. It is supported, but it is not the recommended default for large Python-managed
+bulk ingest.
+
+**Common options:**
+
+- `file_type`: importer file type such as `"csv"`
+- `delimiter`: delimiter override for delimited formats
+- `commit_every`: importer transaction split interval
+- `parallel`: importer worker count
+- `wal`: WAL override during import
+- `extra_settings`: additional raw importer settings
+
+**Example:**
+
+```python
+db.import_documents("./movies.csv", document_type="Movie", file_type="csv")
+```
+
+For bulk table/document ingest from Python, prefer async SQL with a single async worker.
+
+---
+
 ### export_database
 
 ```python

bindings/python/docs/api/transactions.md

@@ -26,18 +26,24 @@ It is important to distinguish between operations that require explicit transact
 | :--- | :--- | :--- |
 | **Schema Operations** | `create_vertex_type()`, `create_property()`, `create_index()`, `db.command("sql", "DROP INDEX...")` | **Auto-transactional** (Do NOT wrap in `with db.transaction():`) |
 | **Data Write** | `db.command("sql", "INSERT...")`, `db.command("sql", "UPDATE...")`, `db.command("sql", "DELETE...")`, `db.command("opencypher", "CREATE ...")` | **Required** (Wrap in `with db.transaction():`) |
-| **Bulk Operations** | `db.command("sql", "IMPORT DATABASE...")` | **Auto-transactional** (Built-in transaction management) |
+| **Bulk Operations** | `db.command("sql", "IMPORT DATABASE...")`, `db.import_documents(...)`, `db.graph_batch(...)` | **Auto-transactional / auto-managed** (Built-in transaction management) |
 | **Data Read** | `db.query()`, `db.command("sql", "SELECT...")`, `db.lookup_by_rid()` | **Optional** (Can run outside transaction for better performance) |
 | **Vector Operations** | `db.create_vector_index()` | **Auto-transactional** (Do NOT wrap) |
 
 ### Key Distinction: `db.query()` vs `db.command()`
 
 - **`db.query()`**: Always used for **read-only queries**. Returns a `ResultSet` with read-only results. **Does NOT require a transaction.**
-- **`db.command()`**: Used for **both DDL and DML operations**:
-    - DML Read: `SELECT` queries (returns ResultSet, optional transaction)
-    - DML Write: `INSERT`, `UPDATE`, `DELETE` (requires transaction)
-    - DDL: `CREATE TYPE`, `CREATE PROPERTY`, `CREATE INDEX`, `DROP`, etc. (auto-transactional)
-    - Bulk: `IMPORT DATABASE`, `MOVE` (auto-transactional)
+- **`db.command()`**: Used for **both DDL and DML operations**. For read statements such
+    as `SELECT`, it returns a `ResultSet` and can run outside a transaction. For write
+    statements such as `INSERT`, `UPDATE`, and `DELETE`, wrap it in
+    `with db.transaction():`. DDL such as `CREATE TYPE`, `CREATE PROPERTY`, `CREATE INDEX`,
+    `DROP`, plus bulk commands such as `IMPORT DATABASE` and `MOVE`, remain
+    auto-transactional.
+- **`db.import_documents()`**: Runs the Java importer through the narrow document-import
+    wrapper. It manages its own importer/async lifecycle, so you should not wrap it in
+    `with db.transaction():`.
+- **`db.graph_batch()`**: Creates the engine-backed bulk graph-ingest helper. It manages
+    its own flush/commit lifecycle, so you should not wrap it in `with db.transaction():`.
 
 ### Best Practice Pattern