chdbpurego

Documentation

Index

• type ChdbConn
  • func NewConnection(argc int, argv []string) (ChdbConn, error)
  • func NewConnectionFromConnString(conn_string string) (ChdbConn, error)
• type ChdbResult
• type ChdbStreamResult

Types

type ChdbConn

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
	Close()
}

func NewConnection

func NewConnection(argc int, argv []string) (ChdbConn, error)

NewConnection is the low level function to create a new connection to the chdb server. using NewConnectionFromConnString is recommended.

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.

func NewConnectionFromConnString

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)
• "file:test.db" (same as above)
• "/path/to/test.db" (for absolute path)
• "file:/path/to/test.db" (same as above)
• "file:test.db?param1=value1&param2=value2" (for relative path with query params)
• "file::memory:?verbose&log-level=test" (for in-memory database with query params)
• "///path/to/test.db?param1=value1&param2=value2" (for absolute path)

Connection string args handling:

Connection string can contain query params like "file:test.db?param1=value1&param2=value2"
"param1=value1" will be passed to ClickHouse engine as start up args.

For more details, see `clickhouse local --help --verbose`
Some special args handling:
- "mode=ro" would be "--readonly=1" for clickhouse (read-only mode)

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.

type ChdbResult

type ChdbResult interface {
	Buf() []byte
	// String rapresentation of the the buffer
	String() string
	// Lenght in bytes of the buffer
	Len() int
	// Number of seconds elapsed for the query execution
	Elapsed() float64
	// Amount of rows returned by the query
	RowsRead() uint64
	// Amount of bytes returned by the query
	BytesRead() uint64
	// 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()
}

type ChdbStreamResult

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()
}