Skip to content

Commit 76c5573

Browse files
BlargianBlargian
committed
minor formatting changes
1 parent c81d63d commit 76c5573

File tree

1 file changed

+137
-78
lines changed

1 file changed

+137
-78
lines changed

‎docs/chdb/api/python.md‎

Lines changed: 137 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -11,39 +11,49 @@ doc_type: 'reference'
1111

1212
## Core Query Functions {#core-query-functions}
1313

14-
### chdb.query(sql, output_format='CSV', path='', udf_path='') {#chdb-query}
14+
### chdb.query {#chdb-query}
1515

1616
Execute SQL query using chDB engine.
1717

1818
This is the main query function that executes SQL statements using the embedded
1919
ClickHouse engine. Supports various output formats and can work with in-memory
2020
or file-based databases.
2121

22-
* **Parameters:**
23-
* **sql** (*str*) – SQL query string to execute
24-
* **output_format** (*str, optional*) – Output format for results. Defaults to “CSV”.
25-
Supported formats include:
26-
- “CSV” - Comma-separated values
27-
- “JSON” - JSON format
28-
- “Arrow” - Apache Arrow format
29-
- “Parquet” - Parquet format
30-
- “DataFrame” - Pandas DataFrame
31-
- “ArrowTable” - PyArrow Table
32-
- “Debug” - Enable verbose logging
33-
* **path** (*str, optional*) – Database file path. Defaults to “” (in-memory database).
34-
Can be a file path or “:memory:” for in-memory database.
35-
* **udf_path** (*str, optional*) – Path to User-Defined Functions directory. Defaults to “”.
36-
* **Returns:**
37-
*Query result in the specified format* –
38-
- str: For text formats like CSV, JSON
39-
- pd.DataFrame: When output_format is “DataFrame” or “dataframe”
40-
- pa.Table: When output_format is “ArrowTable” or “arrowtable”
41-
- chdb result object: For other formats
42-
* **Raises:**
43-
* [**ChdbError**](#chdb-chdberror) – If the SQL query execution fails
44-
* **ImportError** – If required dependencies are missing for DataFrame/Arrow formats
22+
**Syntax**
23+
24+
```python
25+
chdb.query(sql, output_format='CSV', path='', udf_path='')
26+
```
27+
28+
**Parameters**
29+
30+
| Parameter | Type | Default | Description |
31+
|-----------------|-------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
32+
| `sql` | str | *required* | SQL query string to execute |
33+
| `output_format` | str | `"CSV"` | Output format for results. Supported formats:<br/>• `"CSV"` - Comma-separated values<br/>• `"JSON"` - JSON format<br/>• `"Arrow"` - Apache Arrow format<br/>• `"Parquet"` - Parquet format<br/>• `"DataFrame"` - Pandas DataFrame<br/>• `"ArrowTable"` - PyArrow Table<br/>• `"Debug"` - Enable verbose logging |
34+
| `path` | str | `""` | Database file path. Defaults to in-memory database.<br/>Can be a file path or `":memory:"` for in-memory database |
35+
| `udf_path` | str | `""` | Path to User-Defined Functions directory |
36+
37+
**Returns**
38+
39+
Returns the query result in the specified format:
40+
41+
| Return Type | Condition |
42+
|--------------------|----------------------------------------------------------|
43+
| `str` | For text formats like CSV, JSON |
44+
| `pd.DataFrame` | When `output_format` is `"DataFrame"` or `"dataframe"` |
45+
| `pa.Table` | When `output_format` is `"ArrowTable"` or `"arrowtable"` |
46+
| chdb result object | For other formats |
47+
48+
49+
**Raises**
50+
51+
| Exception | Condition |
52+
|---------------|------------------------------------------------------------------|
53+
| `ChdbError` | If the SQL query execution fails |
54+
| `ImportError` | If required dependencies are missing for DataFrame/Arrow formats |
4555

46-
### Examples {#chdb-query-examples}
56+
**Examples**
4757

4858
```pycon
4959
>>> # Basic CSV query
@@ -70,39 +80,48 @@ or file-based databases.
7080
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")
7181
```
7282

73-
### chdb.sql(sql, output_format='CSV', path='', udf_path='') {#chdb-sql}
83+
### chdb.sql {#chdb-sql}
7484

7585
Execute SQL query using chDB engine.
7686

7787
This is the main query function that executes SQL statements using the embedded
7888
ClickHouse engine. Supports various output formats and can work with in-memory
7989
or file-based databases.
8090

81-
* **Parameters:**
82-
* **sql** (*str*) – SQL query string to execute
83-
* **output_format** (*str, optional*) – Output format for results. Defaults to “CSV”.
84-
Supported formats include:
85-
- “CSV” - Comma-separated values
86-
- “JSON” - JSON format
87-
- “Arrow” - Apache Arrow format
88-
- “Parquet” - Parquet format
89-
- “DataFrame” - Pandas DataFrame
90-
- “ArrowTable” - PyArrow Table
91-
- “Debug” - Enable verbose logging
92-
* **path** (*str, optional*) – Database file path. Defaults to “” (in-memory database).
93-
Can be a file path or “:memory:” for in-memory database.
94-
* **udf_path** (*str, optional*) – Path to User-Defined Functions directory. Defaults to “”.
95-
* **Returns:**
96-
*Query result in the specified format* –
97-
- str: For text formats like CSV, JSON
98-
- pd.DataFrame: When output_format is “DataFrame” or “dataframe”
99-
- pa.Table: When output_format is “ArrowTable” or “arrowtable”
100-
- chdb result object: For other formats
101-
* **Raises:**
102-
* [**ChdbError**](#chdb-chdberror) – If the SQL query execution fails
103-
* **ImportError** – If required dependencies are missing for DataFrame/Arrow formats
91+
**Syntax**
92+
93+
```python
94+
chdb.sql(sql, output_format='CSV', path='', udf_path='')
95+
```
96+
97+
**Parameters**
98+
99+
| Parameter | Type | Default | Description |
100+
|-----------------|-------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
101+
| `sql` | str | *required* | SQL query string to execute |
102+
| `output_format` | str | `"CSV"` | Output format for results. Supported formats:<br/>• `"CSV"` - Comma-separated values<br/>• `"JSON"` - JSON format<br/>• `"Arrow"` - Apache Arrow format<br/>• `"Parquet"` - Parquet format<br/>• `"DataFrame"` - Pandas DataFrame<br/>• `"ArrowTable"` - PyArrow Table<br/>• `"Debug"` - Enable verbose logging |
103+
| `path` | str | `""` | Database file path. Defaults to in-memory database.<br/>Can be a file path or `":memory:"` for in-memory database |
104+
| `udf_path` | str | `""` | Path to User-Defined Functions directory |
105+
106+
**Returns**
107+
108+
Returns the query result in the specified format:
109+
110+
| Return Type | Condition |
111+
|--------------------|----------------------------------------------------------|
112+
| `str` | For text formats like CSV, JSON |
113+
| `pd.DataFrame` | When `output_format` is `"DataFrame"` or `"dataframe"` |
114+
| `pa.Table` | When `output_format` is `"ArrowTable"` or `"arrowtable"` |
115+
| chdb result object | For other formats |
116+
117+
**Raises**
118+
119+
| Exception | Condition |
120+
|---------------------------|------------------------------------------------------------------|
121+
| [`ChdbError`](#chdberror) | If the SQL query execution fails |
122+
| `ImportError` | If required dependencies are missing for DataFrame/Arrow formats |
104123

105-
### Examples {#chdb-sql-examples}
124+
**Examples**
106125

107126
```pycon
108127
>>> # Basic CSV query
@@ -129,21 +148,39 @@ or file-based databases.
129148
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")
130149
```
131150

132-
### chdb.to_arrowTable(res) {#chdb-to-arrowtable}
151+
### chdb.to_arrowTable {#chdb-to-arrowtable}
133152

134153
Convert query result to PyArrow Table.
135154

136155
Converts a chDB query result to a PyArrow Table for efficient columnar data processing.
137156
Returns an empty table if the result is empty.
138157

139-
* **Parameters:**
140-
**res** – chDB query result object containing binary Arrow data
141-
* **Returns:**
142-
*pa.Table* – PyArrow Table containing the query results
143-
* **Raises:**
144-
**ImportError** – If pyarrow or pandas are not installed
158+
**Syntax**
159+
160+
```python
161+
chdb.to_arrowTable(res)
162+
```
163+
164+
**Parameters**
165+
166+
167+
| Parameter | Description |
168+
|--------------|-------------------------------------------------------|
169+
| `res` | chDB query result object containing binary Arrow data |
145170

146-
### Example {#chdb-to-arrowtable-example}
171+
**Returns**
172+
173+
| Return type | Description |
174+
|-------------|--------------------------------------------|
175+
| `pa.Table` | PyArrow Table containing the query results |
176+
177+
**Raises**
178+
179+
| Error type | Description |
180+
|---------------|----------------------------------------|
181+
| `ImportError` | If pyarrow or pandas are not installed |
182+
183+
**Example**
147184

148185
```pycon
149186
>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
@@ -153,21 +190,38 @@ Returns an empty table if the result is empty.
153190
0 1 hello
154191
```
155192

156-
### chdb.to_df(r) {#chdb-to-df}
193+
### chdb.to_df {#chdb-to-df}
157194

158195
Convert query result to pandas DataFrame.
159196

160197
Converts a chDB query result to a pandas DataFrame by first converting to
161198
PyArrow Table and then to pandas using multi-threading for better performance.
162199

163-
* **Parameters:**
164-
**r** – chDB query result object containing binary Arrow data
165-
* **Returns:**
166-
*pd.DataFrame* – pandas DataFrame containing the query results
167-
* **Raises:**
168-
**ImportError** – If pyarrow or pandas are not installed
200+
**Syntax**
169201

170-
### Example {#chdb-to-df-example}
202+
```python
203+
chdb.to_df(r)
204+
```
205+
206+
**Parameters**
207+
208+
| Parameter | Description |
209+
|------------|-------------------------------------------------------|
210+
| `r` | chDB query result object containing binary Arrow data |
211+
212+
**Returns**
213+
214+
| Return Type | Description |
215+
|-------------|-------------|
216+
| `pd.DataFrame` | pandas DataFrame containing the query results |
217+
218+
**Raises**
219+
220+
| Exception | Condition |
221+
|---------------|----------------------------------------|
222+
| `ImportError` | If pyarrow or pandas are not installed |
223+
224+
**Example**
171225

172226
```pycon
173227
>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
@@ -179,15 +233,19 @@ PyArrow Table and then to pandas using multi-threading for better performance.
179233

180234
## Connection and Session Management {#connection-session-management}
181235

182-
**Session Functions**
236+
The following Session Functions are available:
183237

184-
### chdb.connect(connection_string: str = ':memory:') → [Connection](#chdb-state-sqlitelike-connection) {#chdb-connect}
238+
### chdb.connect {#chdb-connect}
185239

186240
Create a connection to chDB background server.
187241

188-
This function establishes a connection to the chDB (ClickHouse) database engine.
189-
Only one open connection is allowed per process. Multiple calls with the same
190-
connection string will return the same connection object.
242+
This function establishes a [connection](#chdb-state-sqlitelike-connection) to the chDB (ClickHouse) database engine.
243+
Only one open connection is allowed per process.
244+
Multiple calls with the same connection string will return the same connection object.
245+
246+
```python
247+
chdb.connect(connection_string: str = ':memory:') → Connection
248+
```
191249

192250
* **Parameters:**
193251
**connection_string** (*str, optional*) – Database connection string. Defaults to “:memory:”.
@@ -223,11 +281,12 @@ connection string will return the same connection object.
223281
* **Raises:**
224282
**RuntimeError** – If connection to database fails
225283

226-
#### WARNING {#warning}
227-
Only one connection per process is supported. Creating a new connection
228-
will close any existing connection.
284+
:::warning
285+
Only one connection per process is supported.
286+
Creating a new connection will close any existing connection.
287+
:::
229288

230-
### Examples {#chdb-connect-examples}
289+
**Examples**
231290

232291
```pycon
233292
>>> # In-memory database
@@ -249,9 +308,9 @@ will close any existing connection.
249308
>>> # Connection automatically closed
250309
```
251310

252-
#### SEE ALSO {#see-also}
253-
- `Connection` - Database connection class
254-
- `Cursor` - Database cursor for DB-API 2.0 operations
311+
**See also**
312+
- [`Connection`](#chdb-state-sqlitelike-connection) - Database connection class
313+
- [`Cursor`](#chdb-state-sqlitelike-cursor) - Database cursor for DB-API 2.0 operations
255314

256315
## Exception Handling {#chdb-exceptions}
257316

0 commit comments

Comments
 (0)