update docs

Author: s0und0fs1lence

chdb-purego/chdb.go

@@ -141,7 +141,7 @@ func (c *connection) Query(queryStr string, formatStr string) (result ChdbResult
 	return newChdbResult(res), nil
 }
 
-// Query implements ChdbConn.
+// QueryStreaming implements ChdbConn.
 func (c *connection) QueryStreaming(queryStr string, formatStr string) (result ChdbStreamResult, err error) {
 
 	if c.conn == nil {

chdb-purego/types.go

@@ -55,15 +55,24 @@ type ChdbResult interface {
 }
 
 type ChdbStreamResult interface {
+	// GetNext returns the next chunk of data from the stream.
+	// The chunk is a ChdbResult object that can be used to read the data.
+	// If there are no more chunks, it returns nil.
 	GetNext() ChdbResult
+	// Error returns the error message if there was an error during the streaming process.
 	Error() error
+	// Cancel cancels the streaming process and frees the underlying memory.
 	Cancel()
+	// Free frees the underlying memory and closes the stream.
 	Free()
 }
 
 type ChdbConn interface {
 	//Query executes the given queryStr in the underlying clickhouse connection, and output the result in the given formatStr
 	Query(queryStr string, formatStr string) (result ChdbResult, err error)
+	// QueryStreaming executes the given queryStr in the underlying clickhouse connection, and output the result in the given formatStr
+	// The result is a stream of data that can be read in chunks.
+	// This is useful for large datasets that cannot be loaded into memory all at once.
 	QueryStreaming(queryStr string, formatStr string) (result ChdbStreamResult, err error)
 	//Ready returns a boolean indicating if the connections is successfully established.
 	Ready() bool

chdb.md

@@ -9,6 +9,7 @@ import "github.com/chdb-io/chdb-go/chdb"
 ## Index
 
 - [func Query\(queryStr string, outputFormats ...string\) \(result chdbpurego.ChdbResult, err error\)](<#Query>)
+- [func QueryStream\(queryStr string, outputFormats ...string\) \(result chdbpurego.ChdbStreamResult, err error\)](<#QueryStream>)
 - [type Session](<#Session>)
   - [func NewSession\(paths ...string\) \(\*Session, error\)](<#NewSession>)
   - [func \(s \*Session\) Cleanup\(\)](<#Session.Cleanup>)
@@ -17,19 +18,29 @@ import "github.com/chdb-io/chdb-go/chdb"
   - [func \(s \*Session\) IsTemp\(\) bool](<#Session.IsTemp>)
   - [func \(s \*Session\) Path\(\) string](<#Session.Path>)
   - [func \(s \*Session\) Query\(queryStr string, outputFormats ...string\) \(result chdbpurego.ChdbResult, err error\)](<#Session.Query>)
+  - [func \(s \*Session\) QueryStream\(queryStr string, outputFormats ...string\) \(result chdbpurego.ChdbStreamResult, err error\)](<#Session.QueryStream>)
 
 
 <a name="Query"></a>
-## func [Query](<https://github.com/chdb-io/chdb-go/blob/main/chdb/wrapper.go#L8>)
+## func [Query](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/wrapper.go#L8>)
 
 ```go
 func Query(queryStr string, outputFormats ...string) (result chdbpurego.ChdbResult, err error)
 ```
 
 Query calls query\_conn with a default in\-memory session and default output format of "CSV" if not provided.
 
+<a name="QueryStream"></a>
+## func [QueryStream](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/wrapper.go#L23>)
+
+```go
+func QueryStream(queryStr string, outputFormats ...string) (result chdbpurego.ChdbStreamResult, err error)
+```
+
+Query calls query\_conn with a default in\-memory session and default output format of "CSV" if not provided.
+
 <a name="Session"></a>
-## type [Session](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L15-L20>)
+## type [Session](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L14-L19>)
 
 
 
@@ -40,7 +51,7 @@ type Session struct {
 ```
 
 <a name="NewSession"></a>
-### func [NewSession](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L25>)
+### func [NewSession](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L24>)
 
 ```go
 func NewSession(paths ...string) (*Session, error)
@@ -49,7 +60,7 @@ func NewSession(paths ...string) (*Session, error)
 NewSession creates a new session with the given path. If path is empty, a temporary directory is created. Note: The temporary directory is removed when Close is called.
 
 <a name="Session.Cleanup"></a>
-### func \(\*Session\) [Cleanup](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L77>)
+### func \(\*Session\) [Cleanup](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L86>)
 
 ```go
 func (s *Session) Cleanup()
@@ -58,7 +69,7 @@ func (s *Session) Cleanup()
 Cleanup closes the session and removes the directory.
 
 <a name="Session.Close"></a>
-### func \(\*Session\) [Close](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L67>)
+### func \(\*Session\) [Close](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L76>)
 
 ```go
 func (s *Session) Close()
@@ -71,7 +82,7 @@ temporary directory is created when NewSession was called with an empty path.
 ```
 
 <a name="Session.ConnStr"></a>
-### func \(\*Session\) [ConnStr](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L88>)
+### func \(\*Session\) [ConnStr](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L99>)
 
 ```go
 func (s *Session) ConnStr() string
@@ -80,7 +91,7 @@ func (s *Session) ConnStr() string
 ConnStr returns the current connection string used for the underlying connection
 
 <a name="Session.IsTemp"></a>
-### func \(\*Session\) [IsTemp](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L93>)
+### func \(\*Session\) [IsTemp](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L104>)
 
 ```go
 func (s *Session) IsTemp() bool
@@ -89,7 +100,7 @@ func (s *Session) IsTemp() bool
 IsTemp returns whether the session is temporary.
 
 <a name="Session.Path"></a>
-### func \(\*Session\) [Path](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L83>)
+### func \(\*Session\) [Path](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L94>)
 
 ```go
 func (s *Session) Path() string
@@ -98,12 +109,21 @@ func (s *Session) Path() string
 Path returns the path of the session.
 
 <a name="Session.Query"></a>
-### func \(\*Session\) [Query](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L56>)
+### func \(\*Session\) [Query](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L54>)
 
 ```go
 func (s *Session) Query(queryStr string, outputFormats ...string) (result chdbpurego.ChdbResult, err error)
 ```
 
 Query calls \`query\_conn\` function with the current connection and a default output format of "CSV" if not provided.
 
+<a name="Session.QueryStream"></a>
+### func \(\*Session\) [QueryStream](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L65>)
+
+```go
+func (s *Session) QueryStream(queryStr string, outputFormats ...string) (result chdbpurego.ChdbStreamResult, err error)
+```
+
+QueryStream calls \`query\_conn\` function with the current connection and a default output format of "CSV" if not provided. The result is a stream of data that can be read in chunks. This is useful for large datasets that cannot be loaded into memory all at once.
+
 Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

chdb/session.go

@@ -59,7 +59,9 @@ func (s *Session) Query(queryStr string, outputFormats ...string) (result chdbpu
 	return s.conn.Query(queryStr, outputFormat)
 }
 
-// Query calls `query_conn` function with the current connection and a default output format of "CSV" if not provided.
+// QueryStream calls `query_conn` function with the current connection and a default output format of "CSV" if not provided.
+// The result is a stream of data that can be read in chunks.
+// This is useful for large datasets that cannot be loaded into memory all at once.
 func (s *Session) QueryStream(queryStr string, outputFormats ...string) (result chdbpurego.ChdbStreamResult, err error) {
 	outputFormat := "CSV" // Default value
 	if len(outputFormats) > 0 {

lowApi.md

@@ -10,19 +10,24 @@ import "github.com/chdb-io/chdb-go/chdb-purego"
 
 - [type ChdbConn](<#ChdbConn>)
   - [func NewConnection\(argc int, argv \[\]string\) \(ChdbConn, error\)](<#NewConnection>)
+  - [func NewConnectionFromConnString\(conn\_string string\) \(ChdbConn, error\)](<#NewConnectionFromConnString>)
 - [type ChdbResult](<#ChdbResult>)
-  - [func RawQuery\(argc int, argv \[\]string\) \(result ChdbResult, err error\)](<#RawQuery>)
+- [type ChdbStreamResult](<#ChdbStreamResult>)
 
 
 <a name="ChdbConn"></a>
-## type [ChdbConn](<https://github.com/chdb-io/chdb-go/blob/main/chdb-purego/types.go#L53-L60>)
+## type [ChdbConn](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb-purego/types.go#L70-L81>)
 
 
 
 ```go
 type ChdbConn interface {
     //Query executes the given queryStr in the underlying clickhouse connection, and output the result in the given formatStr
     Query(queryStr string, formatStr string) (result ChdbResult, err error)
+    // QueryStreaming executes the given queryStr in the underlying clickhouse connection, and output the result in the given formatStr
+    // The result is a stream of data that can be read in chunks.
+    // This is useful for large datasets that cannot be loaded into memory all at once.
+    QueryStreaming(queryStr string, formatStr string) (result ChdbStreamResult, err error)
     //Ready returns a boolean indicating if the connections is successfully established.
     Ready() bool
     //Close the connection and free the underlying allocated memory
@@ -31,15 +36,35 @@ type ChdbConn interface {
 ```
 
 <a name="NewConnection"></a>
-### func [NewConnection](<https://github.com/chdb-io/chdb-go/blob/main/chdb-purego/chdb.go#L188>)
+### func [NewConnection](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb-purego/chdb.go#L195>)
 
 ```go
 func NewConnection(argc int, argv []string) (ChdbConn, error)
 ```
 
-Session will keep the state of query. If path is None, it will create a temporary directory and use it as the database path and the temporary directory will be removed when the session is closed. You can also pass in a path to create a database at that path where will keep your data.
+NewConnection is the low level function to create a new connection to the chdb server. using NewConnectionFromConnString is recommended.
 
-You can also use a connection string to pass in the path and other parameters. Examples:
+Deprecated: Use NewConnectionFromConnString instead. This function will be removed in a future version.
+
+Session will keep the state of query. If path is None, it will create a temporary directory and use it as the database path and the temporary directory will be removed when the session is closed. You can also pass in a path to create a database at that path where will keep your data. This is a thin wrapper around the connect\_chdb C API. the argc and argv should be like:
+
+- argc = 1, argv = \[\]string\{"\-\-path=/tmp/chdb"\}
+- argc = 2, argv = \[\]string\{"\-\-path=/tmp/chdb", "\-\-readonly=1"\}
+
+Important:
+
+- There can be only one session at a time. If you want to create a new session, you need to close the existing one.
+- Creating a new session will close the existing one.
+- You need to ensure that the path exists before creating a new session. Or you can use NewConnectionFromConnString.
+
+<a name="NewConnectionFromConnString"></a>
+### func [NewConnectionFromConnString](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb-purego/chdb.go#L269>)
+
+```go
+func NewConnectionFromConnString(conn_string string) (ChdbConn, error)
+```
+
+NewConnectionFromConnString creates a new connection to the chdb server using a connection string. You can use a connection string to pass in the path and other parameters. Examples:
 
 - ":memory:" \(for in\-memory database\)
 - "test.db" \(for relative path\)
@@ -67,13 +92,12 @@ Important:
 - Creating a new session will close the existing one.
 
 <a name="ChdbResult"></a>
-## type [ChdbResult](<https://github.com/chdb-io/chdb-go/blob/main/chdb-purego/types.go#L34-L51>)
+## type [ChdbResult](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb-purego/types.go#L39-L55>)
 
 
 
 ```go
 type ChdbResult interface {
-    // Raw bytes result buffer, used for reading the result of clickhouse query
     Buf() []byte
     // String rapresentation of the the buffer
     String() string
@@ -88,17 +112,28 @@ type ChdbResult interface {
     // If the query had any error during execution, here you can retrieve the cause.
     Error() error
     // Free the query result and all the allocated memory
-    Free() error
+    Free()
 }
 ```
 
-<a name="RawQuery"></a>
-### func [RawQuery](<https://github.com/chdb-io/chdb-go/blob/main/chdb-purego/chdb.go#L145>)
+<a name="ChdbStreamResult"></a>
+## type [ChdbStreamResult](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb-purego/types.go#L57-L68>)
+
+
 
 ```go
-func RawQuery(argc int, argv []string) (result ChdbResult, err error)
+type ChdbStreamResult interface {
+    // GetNext returns the next chunk of data from the stream.
+    // The chunk is a ChdbResult object that can be used to read the data.
+    // If there are no more chunks, it returns nil.
+    GetNext() ChdbResult
+    // Error returns the error message if there was an error during the streaming process.
+    Error() error
+    // Cancel cancels the streaming process and frees the underlying memory.
+    Cancel()
+    // Free frees the underlying memory and closes the stream.
+    Free()
+}
 ```
 
-RawQuery will execute the given clickouse query without using any session.
-
 Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)