Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Connection & Querying

To issue a query, you need to create a Connection using a pointer to a Database instance. You can use connections to execute queries, ddl statements, begin/commit/rollback transactions. You can construct multiple connections that connect to the same Database instance and issue parallel queries through these connections concurrently.

You can also use a Connection to prepare PreparedStatement, which is a way to parameterize queries for repeated execution and avoid planning the same query.

Example

auto connection = Connection(&database);
connection.query("CREATE NODE TABLE person (ID INT64, ColA INT64, PRIMARY KEY (ID));")

Available APIs

class kuzu::main::Connection

Connection is used to interact with a Database instance. Each Connection is thread-safe. Multiple connections can connect to the same Database instance in a multi-threaded environment.


KUZU_API Connection (Database * database)

Creates a connection to the database.

Parameters

  • database A pointer to the database instance that this connection will be connected to.

KUZU_API void beginReadOnlyTransaction ()

Manually starts a new read-only transaction in the current connection.


KUZU_API void beginWriteTransaction ()

Manually starts a new write transaction in the current connection.


KUZU_API void commit ()

Manually commits the current transaction.


template<typename... Args> KUZU_API std::unique_ptr<QueryResult> execute (PreparedStatement * preparedStatement, std::pair< std::string, Args >... args)

Executes the given prepared statement with args and returns the result.

Parameters

  • preparedStatement The prepared statement to execute.
  • args The parameter pack where each arg is a std::pair with the first element being parameter name and second element being parameter value.

Returns:

  • the result of the query.

KUZU_API std::unique_ptr<QueryResult> executeWithParams (PreparedStatement * preparedStatement, std::unordered_map< std::string, std::shared_ptr< common::Value >> & inputParams)

Executes the given prepared statement with inputParams and returns the result.

Parameters

  • preparedStatement The prepared statement to execute.
  • inputParams The parameter pack where each arg is a std::pair with the first element being parameter name and second element being parameter value.

Returns:

  • the result of the query.

KUZU_API uint64_t getMaxNumThreadForExec ()

Returns the maximum number of threads to use for execution in the current connection.

Returns:

  • the maximum number of threads to use for execution in the current connection.

KUZU_API std::string getNodePropertyNames (const std::string & tableName)

Parameters

  • nodeTableName The name of the node table.

Returns:

  • all property names of the given table.

KUZU_API std::string getNodeTableNames ()

Returns:

  • all node table names in string format.

KUZU_API std::string getRelPropertyNames (const std::string & relTableName)

Parameters

  • relTableName The name of the rel table.

Returns:

  • all property names of the given table.

KUZU_API std::string getRelTableNames ()

Returns:

  • all rel table names in string format.

KUZU_API void interrupt ()

Interrupts all queries currently executed within this connection.


KUZU_API std::unique_ptr<PreparedStatement> prepare (const std::string & query)

Prepares the given query and returns the prepared statement.

Parameters

  • query The query to prepare.

Returns:

  • the prepared statement.

KUZU_API std::unique_ptr<QueryResult> query (const std::string & query)

Executes the given query and returns the result.

Parameters

  • query The query to execute.

Returns:

  • the result of the query.

KUZU_API void rollback ()

Manually rollbacks the current transaction.


KUZU_API void setMaxNumThreadForExec (uint64_t numThreads)

Sets the maximum number of threads to use for execution in the current connection.

Parameters

  • numThreads The number of threads to use for execution in the current connection.

KUZU_API void setQueryTimeOut (uint64_t timeoutInMS)

Sets the query timeout value of the current connection. A value of zero (the default) disables the timeout.