kuzu

README

go-kuzu

Official Go language binding for Kùzu. Kùzu an embeddable property graph database management system built for query speed and scalability. For more information, please visit the Kùzu GitHub repository or the Kùzu website.

Installation

go get github.com/kuzudb/go-kuzu

Get started

An example project is available in the example directory.

To run the example project, you can use the following command:

cd example
go run main.go

Docs

The full documentation is available at pkg.go.dev.

Tests

To run the tests, you can use the following command:

go test -v

Contributing

We welcome contributions to go-kuzu. By contributing to go-kuzu, you agree that your contributions will be licensed under the MIT License. Please read the contributing guide for more information.

Documentation

Overview

Package kuzu provides a Go interface to Kùzu graph database management system. The package is a wrapper around the C API of Kùzu.

Index

• Constants
• type Connection
  • func OpenConnection(database *Database) (*Connection, error)
  • func (conn *Connection) Close()
  • func (conn *Connection) Execute(preparedStatement *PreparedStatement, args map[string]any) (*QueryResult, error)
  • func (conn *Connection) GetMaxNumThreads() uint64
  • func (conn *Connection) Interrupt()
  • func (conn *Connection) Prepare(query string) (*PreparedStatement, error)
  • func (conn *Connection) Query(query string) (*QueryResult, error)
  • func (conn *Connection) SetMaxNumThreads(numThreads uint64)
  • func (conn *Connection) SetTimeout(timeout uint64)
• type Database
  • func OpenDatabase(path string, systemConfig SystemConfig) (*Database, error)
  • func OpenInMemoryDatabase(systemConfig SystemConfig) (*Database, error)
  • func (db *Database) Close()
• type Finalizer
• type FlatTuple
  • func (tuple *FlatTuple) Close()
  • func (tuple *FlatTuple) GetAsMap() (map[string]any, error)
  • func (tuple *FlatTuple) GetAsSlice() ([]any, error)
  • func (tuple *FlatTuple) GetAsString() string
  • func (tuple *FlatTuple) GetValue(index uint64) (any, error)
• type InternalID
• type MapItem
• type Node
• type PreparedStatement
  • func (stmt *PreparedStatement) Close()
• type QueryResult
  • func (queryResult *QueryResult) Close()
  • func (queryResult *QueryResult) GetColumnNames() []string
  • func (queryResult *QueryResult) GetCompilingTime() float64
  • func (queryResult *QueryResult) GetExecutionTime() float64
  • func (queryResult *QueryResult) GetNumberOfColumns() uint64
  • func (queryResult *QueryResult) GetNumberOfRows() uint64
  • func (queryResult *QueryResult) HasNext() bool
  • func (queryResult *QueryResult) HasNextQueryResult() bool
  • func (queryResult *QueryResult) Next() (*FlatTuple, error)
  • func (queryResult *QueryResult) NextQueryResult() (*QueryResult, error)
  • func (queryResult *QueryResult) ResetIterator()
  • func (queryResult *QueryResult) ToString() string
• type RecursiveRelationship
• type Relationship
• type SQLConnection
• type SQLConnector
• type SQLStatement
• type SystemConfig
  • func DefaultSystemConfig() SystemConfig

Constants

const Name = "kuzu"

Types

type Connection

type Connection struct {
	// contains filtered or unexported fields
}

Connection represents a connection to a Kùzu database.

func OpenConnection

func OpenConnection(database *Database) (*Connection, error)

OpenConnection opens a connection to the specified database.

func (*Connection) Close

func (conn *Connection) Close()

Close closes the Connection. Calling this method is optional. The Connection will be closed automatically when it is garbage collected.

func (*Connection) Execute

func (conn *Connection) Execute(preparedStatement *PreparedStatement, args map[string]any) (*QueryResult, error)

Execute executes the specified prepared statement with the specified arguments and returns the result. The arguments are a map of parameter names to values.

func (*Connection) GetMaxNumThreads

func (conn *Connection) GetMaxNumThreads() uint64

GetMaxNumThreads returns the maximum number of threads that can be used for executing a query in parallel.

func (*Connection) Interrupt

func (conn *Connection) Interrupt()

Interrupt interrupts the execution of the current query on the connection.

func (*Connection) Prepare

func (conn *Connection) Prepare(query string) (*PreparedStatement, error)

Prepare returns a prepared statement for the specified query string. The prepared statement can be used to execute the query with parameters.

func (*Connection) Query

func (conn *Connection) Query(query string) (*QueryResult, error)

Query executes the specified query string and returns the result.

func (*Connection) SetMaxNumThreads

func (conn *Connection) SetMaxNumThreads(numThreads uint64)

SetMaxNumThreads sets the maximum number of threads that can be used for executing a query in parallel.

func (*Connection) SetTimeout

func (conn *Connection) SetTimeout(timeout uint64)

SetTimeout sets the timeout for the queries executed on the connection. The timeout is specified in milliseconds. A value of 0 means no timeout. If a query takes longer than the specified timeout, it will be interrupted.

type Database

type Database struct {
	// contains filtered or unexported fields
}

Database represents a Kùzu database instance.

func OpenDatabase

func OpenDatabase(path string, systemConfig SystemConfig) (*Database, error)

OpenDatabase opens a Kùzu database at the given path with the given system configuration.

func OpenInMemoryDatabase

func OpenInMemoryDatabase(systemConfig SystemConfig) (*Database, error)

OpenInMemoryDatabase opens a Kùzu database in in-memory mode with the given system configuration.

func (*Database) Close

func (db *Database) Close()

Close closes the database. Calling this method is optional. The database will be closed automatically when it is garbage collected.

type Finalizer

type Finalizer interface {
	Close()
}

type FlatTuple

type FlatTuple struct {
	// contains filtered or unexported fields
}

FlatTuple represents a row in the result set of a query.

func (*FlatTuple) Close

func (tuple *FlatTuple) Close()

Close closes the FlatTuple. Calling this method is optional. The FlatTuple will be closed automatically when it is garbage collected.

func (*FlatTuple) GetAsMap

func (tuple *FlatTuple) GetAsMap() (map[string]any, error)

GetAsMap returns the values of the FlatTuple as a map. The keys of the map are the column names in the query result.

func (*FlatTuple) GetAsSlice

func (tuple *FlatTuple) GetAsSlice() ([]any, error)

GetAsSlice returns the values of the FlatTuple as a slice. The order of the values in the slice is the same as the order of the columns in the query result.

func (*FlatTuple) GetAsString

func (tuple *FlatTuple) GetAsString() string

GetAsString returns the string representation of the FlatTuple. The string representation contains the values of the tuple separated by vertical bars.

func (*FlatTuple) GetValue

func (tuple *FlatTuple) GetValue(index uint64) (any, error)

GetValue returns the value at the given index in the FlatTuple.

type InternalID

type InternalID struct {
	TableID uint64
	Offset  uint64
}

InternalID represents the internal ID of a node or relationship in Kùzu.

type MapItem

type MapItem struct {
	Key   any
	Value any
}

MapItem represents a key-value pair in a map in Kùzu. It is used for both the query parameters and the query result.

type Node

type Node struct {
	ID         InternalID
	Label      string
	Properties map[string]any
}

Node represents a node retrieved from Kùzu. A node has an ID, a label, and properties.

type PreparedStatement

type PreparedStatement struct {
	// contains filtered or unexported fields
}

PreparedStatement represents a prepared statement in Kùzu, which can be used to execute a query with parameters. PreparedStatement is returned by the `Prepare` method of Connection.

func (*PreparedStatement) Close

func (stmt *PreparedStatement) Close()

Close closes the PreparedStatement. Calling this method is optional. The PreparedStatement will be closed automatically when it is garbage collected.

type QueryResult

type QueryResult struct {
	// contains filtered or unexported fields
}

QueryResult represents the result of a query, which can be used to iterate over the result set. QueryResult is returned by the `Query` and `Execute` methods of Connection.

func (*QueryResult) Close

func (queryResult *QueryResult) Close()

Close closes the QueryResult. Calling this method is optional. The QueryResult will be closed automatically when it is garbage collected.

func (*QueryResult) GetColumnNames

func (queryResult *QueryResult) GetColumnNames() []string

GetColumnNames returns the column names of the QueryResult as a slice of strings.

func (*QueryResult) GetCompilingTime

func (queryResult *QueryResult) GetCompilingTime() float64

GetCompilingTime returns the compiling time of the query in milliseconds.

func (*QueryResult) GetExecutionTime

func (queryResult *QueryResult) GetExecutionTime() float64

GetExecutionTime returns the execution time of the query in milliseconds.

func (*QueryResult) GetNumberOfColumns

func (queryResult *QueryResult) GetNumberOfColumns() uint64

GetNumberOfColumns returns the number of columns in the QueryResult.

func (*QueryResult) GetNumberOfRows

func (queryResult *QueryResult) GetNumberOfRows() uint64

GetNumberOfRows returns the number of rows in the QueryResult.

func (*QueryResult) HasNext

func (queryResult *QueryResult) HasNext() bool

HasNext returns true if there is at least one more tuple in the result set.

func (*QueryResult) HasNextQueryResult

func (queryResult *QueryResult) HasNextQueryResult() bool

HasNextQueryResult returns true not all the query results is consumed when multiple query statements are executed.

func (*QueryResult) Next

func (queryResult *QueryResult) Next() (*FlatTuple, error)

Next returns the next tuple in the result set.

func (*QueryResult) NextQueryResult

func (queryResult *QueryResult) NextQueryResult() (*QueryResult, error)

NextQueryResult returns the next query result when multiple query statements are executed.

func (*QueryResult) ResetIterator

func (queryResult *QueryResult) ResetIterator()

ResetIterator resets the iterator of the QueryResult. After calling this method, the `Next` method can be called to iterate over the result set from the beginning.

func (*QueryResult) ToString

func (queryResult *QueryResult) ToString() string

ToString returns the string representation of the QueryResult. The string representation contains the column names and the tuples in the result set.

type RecursiveRelationship

type RecursiveRelationship struct {
	Nodes         []Node
	Relationships []Relationship
}

RecursiveRelationship represents a recursive relationship retrieved from a path query in Kùzu. A recursive relationship has a list of nodes and a list of relationships.

type Relationship

type Relationship struct {
	SourceID      InternalID
	DestinationID InternalID
	Label         string
	Properties    map[string]any
}

Relationship represents a relationship retrieved from Kùzu. A relationship has a source ID, a destination ID, a label, and properties.

type SQLConnection

type SQLConnection interface {
	driver.Conn
	driver.Pinger
	driver.ConnPrepareContext
	driver.QueryerContext
	driver.ExecerContext
}

type SQLConnector

type SQLConnector interface {
	driver.Connector
	io.Closer
}

type SQLStatement

type SQLStatement interface {
	driver.Stmt
	driver.StmtExecContext
	driver.StmtQueryContext
}

type SystemConfig

type SystemConfig struct {
	BufferPoolSize    uint64
	MaxNumThreads     uint64
	EnableCompression bool
	ReadOnly          bool
	MaxDbSize         uint64
}

SystemConfig represents the configuration of Kùzu database system. BufferPoolSize is the size of the buffer pool in bytes. MaxNumThreads is the maximum number of threads that can be used by the database system. EnableCompression is a boolean flag to enable or disable compression. ReadOnly is a boolean flag to open the database in read-only mode. MaxDbSize is the maximum size of the database in bytes.

func DefaultSystemConfig

func DefaultSystemConfig() SystemConfig

DefaultSystemConfig returns the default system configuration. The default system configuration is as follows: BufferPoolSize: 80% of the total system memory. MaxNumThreads: Number of CPU cores. EnableCompression: true. ReadOnly: false. MaxDbSize: 0 (unlimited).