From 91ef4d74cb15f24539eb3bb5d9ec29cbfd17c76e Mon Sep 17 00:00:00 2001 From: ziyi chen Date: Thu, 9 Feb 2023 12:04:52 +0800 Subject: [PATCH] Add documentation for c++ API --- src/include/common/types/value.h | 324 ++++++++++++++++++++-- src/include/main/client_context.h | 12 +- src/include/main/connection.h | 80 +++++- src/include/main/database.h | 46 +++ src/include/main/doc | 127 +++++++++ src/include/main/prepared_statement.h | 21 ++ src/include/main/query_result.h | 57 +++- src/include/main/query_summary.h | 15 + src/include/processor/result/flat_tuple.h | 17 ++ 9 files changed, 662 insertions(+), 37 deletions(-) create mode 100644 src/include/main/doc diff --git a/src/include/common/types/value.h b/src/include/common/types/value.h index 7a30164b8c2..2825c41407b 100644 --- a/src/include/common/types/value.h +++ b/src/include/common/types/value.h @@ -13,59 +13,161 @@ class RelVal; class Value { public: - // Create a NULL value of any type. + /** + * @return a NULL value of ANY type. + */ KUZU_API static Value createNullValue(); - // Create a NULL value of a given type. + /** + * @param dataType the type of the NULL value. + * @return a NULL value of the given type. + */ KUZU_API static Value createNullValue(DataType dataType); - // Create a default non-NULL value of a given type + /** + * @param dataType the type of the non-NULL value. + * @return a default non-NULL value of the given type. + */ KUZU_API static Value createDefaultValue(const DataType& dataType); - + /** + * @param val_ the boolean value to set. + * @return a Value with BOOL type and val_ value. + */ KUZU_API explicit Value(bool val_); + /** + * @param val_ the int64_t value to set. + * @return a Value with INT64 type and val_ value. + */ KUZU_API explicit Value(int32_t val_); + /** + * @param val_ the int64_t value to set. + * @return a Value with INT64 type and val_ value. + */ KUZU_API explicit Value(int64_t val_); + /** + * @param val_ the double value to set. + * @return a Value with DOUBLE type and val_ value. + */ KUZU_API explicit Value(double val_); + /** + * @param val_ the date value to set. + * @return a Value with DATE type and val_ value. + */ KUZU_API explicit Value(date_t val_); + /** + * @param val_ the timestamp value to set. + * @return a Value with timestamp type and val_ value. + */ KUZU_API explicit Value(timestamp_t val_); + /** + * @param val_ the interval value to set. + * @return a Value with INTERVAL type and val_ value. + */ KUZU_API explicit Value(interval_t val_); + /** + * @param val_ the internalID value to set. + * @return a Value with INTERNAL_ID type and val_ value. + */ KUZU_API explicit Value(internalID_t val_); + /** + * @param val_ the string value to set. + * @return a Value with STRING type and val_ value. + */ KUZU_API explicit Value(const char* val_); + /** + * @param val_ the string value to set. + * @return a Value with STRING type and val_ value. + */ KUZU_API explicit Value(const std::string& val_); + /** + * @param vals the list value to set. + * @return a Value with dataType type and vals value. + */ KUZU_API explicit Value(DataType dataType, std::vector> vals); + /** + * @param val_ the node value to set. + * @return a Value with NODE type and val_ value. + */ KUZU_API explicit Value(std::unique_ptr val_); + /** + * @param val_ the rel value to set. + * @return a Value with REL type and val_ value. + */ KUZU_API explicit Value(std::unique_ptr val_); + /** + * @param val_ the value to set. + * @return a Value with dataType type and val_ value. + */ KUZU_API explicit Value(DataType dataType, const uint8_t* val_); - + /** + * @param other the value to copy from. + * @return a Value with the same value as other. + */ KUZU_API Value(const Value& other); - + /** + * @brief Sets the data type of the Value. + * @param dataType_ the data type to set to. + */ KUZU_API void setDataType(const DataType& dataType_); + /** + * @return the dataType of the value. + */ KUZU_API DataType getDataType() const; - + /** + * @brief Sets the null flag of the Value. + * @param flag null value flag to set. + */ KUZU_API void setNull(bool flag); + /** + * @brief Sets the null flag of the Value to true. + */ KUZU_API void setNull(); + /** + * @return whether the Value is null or not. + */ KUZU_API bool isNull() const; - + /** + * @brief Copies from the value. + * @param value value to copy from. + */ KUZU_API void copyValueFrom(const uint8_t* value); + /** + * @brief Copies from the other. + * @param other value to copy from. + */ KUZU_API void copyValueFrom(const Value& other); - + /** + * @return the value of the given type. + */ KUZU_API template T getValue() const { throw std::runtime_error("Unimplemented template for Value::getValue()"); } - + /** + * @return a reference to the value of the given type. + */ KUZU_API template T& getValueReference() { throw std::runtime_error("Unimplemented template for Value::getValueReference()"); } + /** + * @return a reference to the list value. + */ // TODO(Guodong): think how can we template list get functions. KUZU_API const std::vector>& getListValReference() const; - + /** + * @param value the value to Value object. + * @return a Value object based on value. + */ KUZU_API template static Value createValue(T value) { throw std::runtime_error("Unimplemented template for Value::createValue()"); } - + /** + * @return a copy of the current value. + */ KUZU_API std::unique_ptr copy() const; - + /** + * @return the current value in string format. + */ KUZU_API std::string toString() const; private: @@ -97,25 +199,57 @@ class Value { std::unique_ptr relVal; }; +/** + * @brief NodeVal represents a node in the graph and stores the nodeID, label and properties of that + * node. + */ class NodeVal { public: + /** + * @brief Constructs the NodeVal object with the given idVal and labelVal. + * @param idVal the nodeID value. + * @param labelVal the name of the node. + */ KUZU_API NodeVal(std::unique_ptr idVal, std::unique_ptr labelVal); - + /** + * @brief Constructs the NodeVal object from the other. + * @param other the NodeVal to copy from. + */ KUZU_API NodeVal(const NodeVal& other); - + /** + * @brief Adds a property with the given {key,value} pair to the NodeVal. + * @param key the name of the property. + * @param value the value of the property. + */ KUZU_API void addProperty(const std::string& key, std::unique_ptr value); - + /** + * @return all properties of the NodeVal. + */ KUZU_API const std::vector>>& getProperties() const; - + /** + * @return the nodeID as a Value. + */ KUZU_API Value* getNodeIDVal(); + /** + * @return the name of the node as a Value. + */ KUZU_API Value* getLabelVal(); - + /** + * @return the nodeID of the node as a nodeID struct. + */ KUZU_API nodeID_t getNodeID() const; + /** + * @return the name of the node in string format. + */ KUZU_API std::string getLabelName() const; - + /** + * @return a copy of the current node. + */ KUZU_API std::unique_ptr copy() const; - + /** + * @return the current node values in string format. + */ KUZU_API std::string toString() const; private: @@ -124,27 +258,63 @@ class NodeVal { std::vector>> properties; }; +/** + * @brief RelVal represents a rel in the graph and stores the relID, src/dst nodes and properties of + * that rel. + */ class RelVal { public: + /** + * @brief Constructs the RelVal based on the srcNodeIDVal, dstNodeIDVal and labelVal. + * @param srcNodeIDVal the src node. + * @param dstNodeIDVal the dst node. + * @param labelVal the name of the rel. + */ KUZU_API RelVal(std::unique_ptr srcNodeIDVal, std::unique_ptr dstNodeIDVal, std::unique_ptr labelVal); - + /** + * @brief Constructs a RelVal from other. + * @param other the RelVal to copy from. + */ KUZU_API RelVal(const RelVal& other); - + /** + * @brief Adds a property with the given {key,value} pair to the RelVal. + * @param key the name of the property. + * @param value the value of the property. + */ KUZU_API void addProperty(const std::string& key, std::unique_ptr value); - + /** + * @return all properties of the RelVal. + */ KUZU_API const std::vector>>& getProperties() const; - + /** + * @return the src nodeID value of the RelVal in Value. + */ KUZU_API Value* getSrcNodeIDVal(); + /** + * @return the dst nodeID value of the RelVal in Value. + */ KUZU_API Value* getDstNodeIDVal(); - + /** + * @return the src nodeID value of the RelVal as nodeID struct. + */ KUZU_API nodeID_t getSrcNodeID() const; + /** + * @return the dst nodeID value of the RelVal as nodeID struct. + */ KUZU_API nodeID_t getDstNodeID() const; + /** + * @return the name of the RelVal. + */ KUZU_API std::string getLabelName(); - + /** + * @return the value of the RelVal in string format. + */ KUZU_API std::string toString() const; - + /** + * @return a copy of the RelVal. + */ KUZU_API inline std::unique_ptr copy() const; private: @@ -154,171 +324,271 @@ class RelVal { std::vector>> properties; }; +/** + * @return boolean value. + */ KUZU_API template<> inline bool Value::getValue() const { assert(dataType.getTypeID() == BOOL); return val.booleanVal; } +/** + * @return int64 value. + */ KUZU_API template<> inline int64_t Value::getValue() const { assert(dataType.getTypeID() == INT64); return val.int64Val; } +/** + * @return double value. + */ KUZU_API template<> inline double Value::getValue() const { assert(dataType.getTypeID() == DOUBLE); return val.doubleVal; } +/** + * @return date_t value. + */ KUZU_API template<> inline date_t Value::getValue() const { assert(dataType.getTypeID() == DATE); return val.dateVal; } +/** + * @return timestamp_t value. + */ KUZU_API template<> inline timestamp_t Value::getValue() const { assert(dataType.getTypeID() == TIMESTAMP); return val.timestampVal; } +/** + * @return interval_t value. + */ KUZU_API template<> inline interval_t Value::getValue() const { assert(dataType.getTypeID() == INTERVAL); return val.intervalVal; } +/** + * @return internal_t value. + */ KUZU_API template<> inline internalID_t Value::getValue() const { assert(dataType.getTypeID() == INTERNAL_ID); return val.internalIDVal; } +/** + * @return string value. + */ KUZU_API template<> inline std::string Value::getValue() const { assert(dataType.getTypeID() == STRING); return strVal; } +/** + * @return NodeVal value. + */ KUZU_API template<> inline NodeVal Value::getValue() const { assert(dataType.getTypeID() == NODE); return *nodeVal; } +/** + * @return RelVal value. + */ KUZU_API template<> inline RelVal Value::getValue() const { assert(dataType.getTypeID() == REL); return *relVal; } +/** + * @return the reference to the boolean value. + */ KUZU_API template<> inline bool& Value::getValueReference() { assert(dataType.getTypeID() == BOOL); return val.booleanVal; } +/** + * @return the reference to the int64 value. + */ KUZU_API template<> inline int64_t& Value::getValueReference() { assert(dataType.getTypeID() == INT64); return val.int64Val; } +/** + * @return the reference to the double value. + */ KUZU_API template<> inline double& Value::getValueReference() { assert(dataType.getTypeID() == DOUBLE); return val.doubleVal; } +/** + * @return the reference to the date value. + */ KUZU_API template<> inline date_t& Value::getValueReference() { assert(dataType.getTypeID() == DATE); return val.dateVal; } +/** + * @return the reference to the timestamp value. + */ KUZU_API template<> inline timestamp_t& Value::getValueReference() { assert(dataType.getTypeID() == TIMESTAMP); return val.timestampVal; } +/** + * @return the reference to the interval value. + */ KUZU_API template<> inline interval_t& Value::getValueReference() { assert(dataType.getTypeID() == INTERVAL); return val.intervalVal; } +/** + * @return the reference to the internal_id value. + */ KUZU_API template<> inline nodeID_t& Value::getValueReference() { assert(dataType.getTypeID() == INTERNAL_ID); return val.internalIDVal; } +/** + * @return the reference to the string value. + */ KUZU_API template<> inline std::string& Value::getValueReference() { assert(dataType.getTypeID() == STRING); return strVal; } +/** + * @return the reference to the NodeVal value. + */ KUZU_API template<> inline NodeVal& Value::getValueReference() { assert(dataType.getTypeID() == NODE); return *nodeVal; } +/** + * @return the reference to the RelVal value. + */ KUZU_API template<> inline RelVal& Value::getValueReference() { assert(dataType.getTypeID() == REL); return *relVal; } +/** + * @param val the boolean value + * @return a Value with BOOL type and val value. + */ KUZU_API template<> inline Value Value::createValue(bool val) { return Value(val); } +/** + * @param val the int64 value + * @return a Value with INT64 type and val value. + */ KUZU_API template<> inline Value Value::createValue(int64_t val) { return Value(val); } +/** + * @param val the double value + * @return a Value with DOUBLE type and val value. + */ KUZU_API template<> inline Value Value::createValue(double val) { return Value(val); } +/** + * @param val the date_t value + * @return a Value with DATE type and val value. + */ KUZU_API template<> inline Value Value::createValue(date_t val) { return Value(val); } +/** + * @param val the timestamp_t value + * @return a Value with TIMESTAMP type and val value. + */ KUZU_API template<> inline Value Value::createValue(timestamp_t val) { return Value(val); } +/** + * @param val the interval_t value + * @return a Value with INTERVAL type and val value. + */ KUZU_API template<> inline Value Value::createValue(interval_t val) { return Value(val); } +/** + * @param val the nodeID_t value + * @return a Value with NODE_ID type and val value. + */ KUZU_API template<> inline Value Value::createValue(nodeID_t val) { return Value(val); } +/** + * @param val the string value + * @return a Value with STRING type and val value. + */ KUZU_API template<> inline Value Value::createValue(std::string val) { return Value(val); } +/** + * @param val the string value + * @return a Value with STRING type and val value. + */ KUZU_API template<> inline Value Value::createValue(const std::string& val) { return Value(val); } +/** + * @param val the string value + * @return a Value with STRING type and val value. + */ KUZU_API template<> inline Value Value::createValue(const char* value) { return Value(std::string(value)); diff --git a/src/include/main/client_context.h b/src/include/main/client_context.h index a27d8976cbb..419cac95d48 100644 --- a/src/include/main/client_context.h +++ b/src/include/main/client_context.h @@ -7,13 +7,21 @@ namespace kuzu { namespace main { -// Contain client side configuration. -// We make profiler associated per query, so profiler is not maintained in client context. +/** + * @brief Contain client side configuration. We make profiler associated per query, so profiler is + * not maintained in client context. + */ class ClientContext { friend class Connection; public: + /** + * @brief Constructs the ClientContext object. + */ KUZU_API explicit ClientContext(); + /** + * @brief Deconstructs the ClientContext object. + */ KUZU_API ~ClientContext() = default; private: diff --git a/src/include/main/connection.h b/src/include/main/connection.h index 83eaba487c3..a6d771855e4 100644 --- a/src/include/main/connection.h +++ b/src/include/main/connection.h @@ -8,6 +8,10 @@ namespace kuzu { namespace main { +/** + * @brief 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. + */ class Connection { friend class kuzu::testing::ApiTest; friend class kuzu::testing::BaseGraphTest; @@ -33,32 +37,98 @@ class Connection { enum class ConnectionTransactionMode : uint8_t { AUTO_COMMIT = 0, MANUAL = 1 }; public: + /** + * @brief Creates a connection to the database. + * @param database A pointer to the database instance that this connection will be connected to. + */ KUZU_API explicit Connection(Database* database); + /** + * @brief Destructs the connection. + */ KUZU_API ~Connection(); - + /** + * @brief Manually starts a new read-only transaction in the current connection and sets the + * current transaction mode to MANUAL. + */ KUZU_API void beginReadOnlyTransaction(); + /** + * @brief Manually starts a new write transaction in the current connection and sets the current + * transaction mode to MANUAL. + */ KUZU_API void beginWriteTransaction(); + /** + * @brief Manually commits the current transaction and sets the current transaction mode to + * AUTO_COMMIT. + */ KUZU_API void commit(); + /** + * @brief Manually rollbacks the current transaction and sets the current transaction mode to + * AUTO_COMMIT. + */ KUZU_API void rollback(); + /** + * @brief Sets the maximum number of threads to use for execution in the current connection. + * @param numThreads The number of threads to use for execution in the current connection. + */ KUZU_API void setMaxNumThreadForExec(uint64_t numThreads); + /** + * @brief Returns the maximum number of threads to use for execution in the current connection. + * @return The maximum number of threads to use for execution in the current connection. + */ KUZU_API uint64_t getMaxNumThreadForExec(); + /** + * @brief Executes the given query and returns the result. + * @param query The query to execute. + * @return The result of the query. + */ KUZU_API std::unique_ptr query(const std::string& query); + /** + * @brief Prepares the given query and returns the prepared statement. + * @param query The query to prepare. + * @return The prepared statement. + */ KUZU_API std::unique_ptr prepare(const std::string& query); - + /** + * @brief Executes the given prepared statement with args and returns the result. + * @param preparedStatement The prepared statement to execute. + * @param args The parameter pack where each arg is a std::pair with the first element being + * parameter name and second element being parameter value. + * @return The result of the query. + */ KUZU_API template inline std::unique_ptr execute( PreparedStatement* preparedStatement, std::pair... args) { std::unordered_map> inputParameters; return executeWithParams(preparedStatement, inputParameters, args...); } - // Note: Any call that goes through executeWithParams acquires a lock in the end by calling - // executeLock(...). + /** + * @brief Executes the given prepared statement with inputParams and returns the result. + * @param preparedStatement The prepared statement to execute. + * @param inputParams The parameter pack where each arg is a std::pair with the first element + * being parameter name and second element being parameter value. + * @return The result of the query. + * @note Any call that goes through executeWithParams acquires a lock in the end by calling + * executeLock(...). + */ KUZU_API std::unique_ptr executeWithParams(PreparedStatement* preparedStatement, std::unordered_map>& inputParams); - + /** + * @return All node table names in string format. + */ KUZU_API std::string getNodeTableNames(); + /** + * @return All rel table names in string format. + */ KUZU_API std::string getRelTableNames(); + /** + * @param nodeTableName The name of the node table. + * @return All property names of the given table. + */ KUZU_API std::string getNodePropertyNames(const std::string& tableName); + /** + * @param relTableName The name of the rel table. + * @return All property names of the given table. + */ KUZU_API std::string getRelPropertyNames(const std::string& relTableName); protected: diff --git a/src/include/main/database.h b/src/include/main/database.h index 477eb80b638..82438ebded8 100644 --- a/src/include/main/database.h +++ b/src/include/main/database.h @@ -10,8 +10,20 @@ namespace kuzu { namespace main { +/** + * @brief Stores buffer pool size and max number of threads configurations. + */ KUZU_API struct SystemConfig { + /** + * @brief Creates a SystemConfig object with default buffer pool size and max num of threads. + */ explicit SystemConfig(); + /** + * @brief Creates a SystemConfig object. + * @param bufferPoolSize Buffer pool size in bytes. + * @note defaultPageBufferPoolSize and largePageBufferPoolSize are calculated based on the + * DEFAULT_PAGES_BUFFER_RATIO and LARGE_PAGES_BUFFER_RATIO constants in StorageConfig. + */ explicit SystemConfig(uint64_t bufferPoolSize); uint64_t defaultPageBufferPoolSize; @@ -19,12 +31,23 @@ KUZU_API struct SystemConfig { uint64_t maxNumThreads; }; +/** + * @brief Stores databasePath. + */ KUZU_API struct DatabaseConfig { + /** + * @brief Creates a DatabaseConfig object. + * @param databasePath Path to store the database files. + */ explicit DatabaseConfig(std::string databasePath); std::string databasePath; }; +/** + * @brief Database class is the main class of the KuzuDB. It manages all database configurations and + * files. + */ class Database { friend class EmbeddedShell; friend class Connection; @@ -32,12 +55,35 @@ class Database { friend class kuzu::testing::BaseGraphTest; public: + /** + * @brief Creates a database object with default buffer pool size and max num threads. + * @param databaseConfig Database configurations(database path). + */ KUZU_API explicit Database(DatabaseConfig databaseConfig); + /** + * @brief Creates a database object. + * @param databaseConfig Database configurations(database path). + * @param systemConfig System configurations(buffer pool size and max num threads). + */ KUZU_API Database(DatabaseConfig databaseConfig, SystemConfig systemConfig); + /** + * @brief Deconstructs the database object. + */ KUZU_API ~Database(); + /** + * @brief Sets the logging level of the database instance. + * @param loggingLevel New logging level. (Supported logging levels are: "info", "debug", + * "err"). + */ void setLoggingLevel(std::string loggingLevel); + /** + * @brief Resizes the buffer pool size of the database instance. + * @param newSize New buffer pool size in bytes. + * @throws BufferManagerException if the new size is smaller than the current buffer manager + * size. + */ KUZU_API void resizeBufferManager(uint64_t newSize); private: diff --git a/src/include/main/doc b/src/include/main/doc new file mode 100644 index 00000000000..9a324c897a3 --- /dev/null +++ b/src/include/main/doc @@ -0,0 +1,127 @@ +## class kuzu::main::DataTypeInfo + + + +--- + +## class kuzu::main::QueryResult + +QueryResult stores the result of a query execution. + +--- + +```c++ +QueryResult (const PreparedSummary & preparedSummary) +``` +Creates a QueryResult object. + +**Parameters** +- `preparedSummary` stores compiling time and query options. + +--- + +```c++ +std::vector getColumnDataTypes () +``` + +**Returns:** +- dataType of each column in query result. + +--- + +```c++ +std::vector getColumnNames () +``` + +**Returns:** +- name of each column in query result. + +--- + +```c++ +std::vector > getColumnTypesInfo () +``` + +**Returns:** +- dataTypeInfo of each column. + +--- + +```c++ +std::string getErrorMessage () +``` + +**Returns:** +- error message of the query execution if the query fails. + +--- + +```c++ +std::shared_ptr getNext () +``` + +**Returns:** +- next flat tuple in the query result. + +--- + +```c++ +size_t getNumColumns () +``` + +**Returns:** +- number of columns in query result. + +--- + +```c++ +uint64_t getNumTuples () +``` + +**Returns:** +- num of tuples in query result. + +--- + +```c++ +QuerySummary* getQuerySummary () +``` + +**Returns:** +- query summary which stores the execution time, compiling time, plan and query options. + +--- + +```c++ +bool hasNext () +``` + +**Returns:** +- whether there are more tuples to read. + +--- + +```c++ +bool isSuccess () +``` + +**Returns:** +- query is executed successfully or not. + +--- + +```c++ +void writeToCSV (const std::string & fileName, char delimiter = ',', char escapeCharacter = ''', char newline = 'n') +``` +writes the query result to a csv file. + +**Parameters** +- `fileName` name of the csv file. +- `delimiter` delimiter of the csv file. +- `escapeCharacter` escape character of the csv file. +- `newline` newline character of the csv file. + +--- + +###### API documentation generated using [Doxygenmd](https://github.com/d99kris/doxygenmd) + diff --git a/src/include/main/prepared_statement.h b/src/include/main/prepared_statement.h index 4f7573b8acd..bad0e833980 100644 --- a/src/include/main/prepared_statement.h +++ b/src/include/main/prepared_statement.h @@ -7,6 +7,10 @@ namespace kuzu { namespace main { +/** + * @brief A prepared statement is a parameterized query which can avoid planning the same query for + * repeated execution. + */ class PreparedStatement { friend class Connection; friend class JOConnection; @@ -15,10 +19,27 @@ class PreparedStatement { friend class kuzu::transaction::TinySnbCopyCSVTransactionTest; public: + /** + * @brief DDL and COPY_CSV statements are automatically wrapped in a transaction and committed. + * As such, they cannot be part of an active transaction. + * @return The prepared statement is allowed to be part of an active transaction. + */ KUZU_API bool allowActiveTransaction() const; + /** + * @return The query is prepared successfully or not. + */ KUZU_API bool isSuccess() const; + /** + * @return The error message if the query is not prepared successfully. + */ KUZU_API std::string getErrorMessage() const; + /** + * @return The prepared statement is read-only or not. + */ KUZU_API bool isReadOnly() const; + /** + * @return Expressions for generating query results. + */ std::vector> getExpressionsToCollect(); private: diff --git a/src/include/main/query_result.h b/src/include/main/query_result.h index 9db8a42b5b5..fb00bdb605c 100644 --- a/src/include/main/query_result.h +++ b/src/include/main/query_result.h @@ -22,28 +22,79 @@ struct DataTypeInfo { const common::DataType& type, const std::string& name); }; +/** + * @brief QueryResult stores the result of a query execution. + */ class QueryResult { friend class Connection; public: - // Only used when we failed to prepare a query. + /** + * @brief Used to create a QueryResult object for the failing query. + */ KUZU_API QueryResult(); + /** + * @brief Creates a QueryResult object. + * @param preparedSummary stores compiling time and query options. + */ explicit QueryResult(const PreparedSummary& preparedSummary); + /** + * @brief Deconstructs the QueryResult object. + */ KUZU_API ~QueryResult(); - + /** + * @return query is executed successfully or not. + */ KUZU_API bool isSuccess() const; + /** + * @return error message of the query execution if the query fails. + */ KUZU_API std::string getErrorMessage() const; + /** + * @return number of columns in query result. + */ KUZU_API size_t getNumColumns() const; + /** + * @return name of each column in query result. + */ KUZU_API std::vector getColumnNames(); + /** + * @return dataType of each column in query result. + */ KUZU_API std::vector getColumnDataTypes(); + /** + * @return num of tuples in query result. + */ KUZU_API uint64_t getNumTuples(); + /** + * @return query summary which stores the execution time, compiling time, plan and query + * options. + */ KUZU_API QuerySummary* getQuerySummary() const; + /** + * @return dataTypeInfo of each column. + */ std::vector> getColumnTypesInfo(); - + /** + * @return whether there are more tuples to read. + */ KUZU_API bool hasNext(); + /** + * @return next flat tuple in the query result. + */ KUZU_API std::shared_ptr getNext(); + /** + * @brief writes the query result to a csv file. + * @param fileName name of the csv file. + * @param delimiter delimiter of the csv file. + * @param escapeCharacter escape character of the csv file. + * @param newline newline character of the csv file. + */ KUZU_API void writeToCSV(const std::string& fileName, char delimiter = ',', char escapeCharacter = '"', char newline = '\n'); + /** + * @brief resets the result tuple iterator. + */ KUZU_API void resetIterator(); private: diff --git a/src/include/main/query_summary.h b/src/include/main/query_summary.h index bd5f06f66d2..599f2eb29e8 100644 --- a/src/include/main/query_summary.h +++ b/src/include/main/query_summary.h @@ -8,22 +8,37 @@ namespace kuzu { namespace main { +/** + * @brief PreparedSummary stores the compiling time and query options of a query. + */ struct PreparedSummary { double compilingTime = 0; bool isExplain = false; bool isProfile = false; }; +/** + * @brief QuerySummary stores the execution time, plan, compiling time and query options of a query. + */ class QuerySummary { friend class Connection; friend class benchmark::Benchmark; public: + /** + * @return Query compiling time. + */ KUZU_API double getCompilingTime() const; + /** + * @return Query execution time. + */ KUZU_API double getExecutionTime() const; bool getIsExplain() const; bool getIsProfile() const; std::ostringstream& getPlanAsOstream(); + /** + * @return Physical plan for query in string format. + */ KUZU_API std::string getPlan(); void setPreparedSummary(PreparedSummary preparedSummary_); diff --git a/src/include/processor/result/flat_tuple.h b/src/include/processor/result/flat_tuple.h index dc35ea387d9..4118f94b8d2 100644 --- a/src/include/processor/result/flat_tuple.h +++ b/src/include/processor/result/flat_tuple.h @@ -6,14 +6,31 @@ namespace kuzu { namespace processor { +/** + * @brief Stores a vector of Values. + */ class FlatTuple { public: void addValue(std::unique_ptr value); + /** + * @return Number of values in the FlatTuple. + */ KUZU_API uint32_t len(); + /** + * @param idx value index to get. + * @return The value stored at idx. + */ KUZU_API common::Value* getValue(uint32_t idx); + /** + * @parm colsWidth The length of each column + * @param delimiter The delimiter to separate each value. + * @param maxWidth The maximum length of each column. Only the first maxWidth number of + * characters of each column will be displayed. + * @return All values in string format. + */ KUZU_API std::string toString(const std::vector& colsWidth, const std::string& delimiter = "|", uint32_t maxWidth = -1);