Add documentation on special behaviour for query result getNext() (#351)

* Add docs on query result getNext() behaviour

* Add manual frees in C API example

* Apply suggestions from code review

---------

Co-authored-by: Prashanth Rao <35005448+prrao87@users.noreply.github.com>

Author: royi-luo

src/content/docs/client-apis/c.mdx

@@ -73,4 +73,62 @@ And then link against `<install-dest>/libkuzu.so` (or `libkuzu.dylib`/`libkuzu.l
 
 
 The static library is more complicated (as noted above, it's recommended that you use CMake to handle the details) and is not installed by default, but all static libraries will be available in the build directory.
-You need to define `KUZU_STATIC_DEFINE`, and link against the static kuzu library in `build/src`, as well as `antlr4_cypher`, `antlr4_runtime`, `brotlidec`, `brotlicommon`, `utf8proc`, `re2`, `serd`, `fastpfor`, `miniparquet`, `zstd`, `miniz`, `mbedtls`, `lz4` (all of which can be found in the third_party subdirectory of the CMake build directory. E.g. `build/third_party/zstd/libzstd.a`) and whichever standard library you're using.
+You need to define `KUZU_STATIC_DEFINE`, and link against the static Kùzu library in `build/src`, as well as `antlr4_cypher`, `antlr4_runtime`, `brotlidec`, `brotlicommon`, `utf8proc`, `re2`, `serd`, `fastpfor`, `miniparquet`, `zstd`, `miniz`, `mbedtls`, `lz4` (all of which can be found in the third_party subdirectory of the CMake build directory. E.g. `build/third_party/zstd/libzstd.a`) and whichever standard library you're using.
+
+## Handling Kùzu output using `kuzu_query_result_get_next()`
+
+For the examples in this section we will be using the following schema:
+```cypher
+CREATE NODE TABLE person(id INT64 PRIMARY KEY);
+```
+
+The `kuzu_query_result_get_next()` function returns a reference to the resulting flat tuple. Additionally, to reduce resource allocation all calls to `kuzu_query_result_get_next()` reuse the same
+flat tuple object. This means that for a query result, each call to `kuzu_query_result_get_next()` actually overwrites the flat tuple previously returned by the previous call.
+
+Thus, we recommend processing each tuple immediately before making the next call to `getNext`:
+
+```c
+kuzu_query_result result;
+kuzu_connection_query(conn, "MATCH (p:person) RETURN p.*", result);
+while (kuzu_query_result_has_next(result)) {
+  kuzu_flat_tuple tuple;
+  kuzu_query_result_get_next(result, tuple);
+  do_something(tuple);
+}
+```
+
+If you wish to process the tuples later, you must explicitly make a copy of each tuple:
+```cpp
+static kuzu_value* copy_flat_tuple(kuzu_flat_tuple* tuple, uint32_t tupleLen) {
+  kuzu_value* ret = malloc(sizeof(kuzu_value) * tupleLen);
+  for (uint32_t i = 0; i < tupleLen; i++) {
+      kuzu_flat_tuple_get_value(tuple, i, &ret[i]);
+  }
+  return ret;
+}
+
+void mainFunction() {
+  kuzu_query_result result;
+  kuzu_connection_query(conn, "MATCH (p:person) RETURN p.*", &result);
+
+  uint64_t num_tuples = kuzu_query_result_get_num_tuples(&result);
+  kuzu_value** tuples = (kuzu_value**)malloc(sizeof(kuzu_value*) * num_tuples);
+  for (uint64_t i = 0; i < num_tuples; ++i) {
+      kuzu_flat_tuple tuple;
+      kuzu_query_result_get_next(&result, &tuple);
+      tuples[i] = copy_flat_tuple(&tuple, kuzu_query_result_get_num_columns(&result));
+      kuzu_flat_tuple_destroy(&tuple);
+  }
+
+  for (uint64_t i = 0; i < num_tuples; ++i) {
+    for (uint64_t j = 0; j < kuzu_query_result_get_num_columns(&result); ++j) {
+      doSomething(tuples[i][j]);
+      kuzu_value_destroy(&tuples[i][j]);
+    }
+    free(tuples[i]);
+  }
+
+  free((void*)tuples);
+  kuzu_query_result_destroy(&result);
+}
+```

src/content/docs/client-apis/cpp.mdx

@@ -11,10 +11,71 @@ See the following link for the full documentation of the C++ API.
   href="https://kuzudb.com/api-docs/cpp/annotated.html"
 />
 
+## Handling Kùzu output using `getNext()`
+
+For the examples in this section we will be using the following schema:
+```cypher
+CREATE NODE TABLE person(id INT64 PRIMARY KEY);
+```
+
+The `getNext()` function in a `QueryResult` returns a reference to the resulting `FlatTuple`. Additionally, to reduce resource allocation all calls to `getNext()` reuse the same
+FlatTuple object. This means that for a `QueryResult`, each call to `getNext()` actually overwrites the `FlatTuple` previously returned by the previous call to `getNext()`.
+
+Thus, we don't recommend using `QueryResult` like this:
+
+```cpp
+std::unique_ptr<kuzu::main::QueryResult> result = conn.query("MATCH (p:person) RETURN p.*");
+std::vector<std::shared_ptr<kuzu::processor::FlatTuple>> tuples;
+while (result->hasNext()) {
+  // Each call to getNext() actually returns a pointer to the same tuple object
+  tuples.emplace_back(result->getNext());
+}
+
+// This is wrong!
+// The vector stores a bunch of pointers to the same underlying tuple object
+for (const auto& resultTuple: tuples) {
+  doSomething(resultTuple);
+}
+```
+
+Instead, we recommend processing each tuple immediately before making the next call to `getNext`:
+```cpp
+std::unique_ptr<kuzu::main::QueryResult> result = conn.query("MATCH (p:person) RETURN p.*");
+std::vector<std::shared_ptr<kuzu::processor::FlatTuple>> tuples;
+while (result->hasNext()) {
+  auto tuple = result->getNext();
+  doSomething(tuple);
+}
+```
+
+If wish to process the tuples later, you must explicitly make a copy of each tuple:
+```cpp
+static decltype(auto) copyFlatTuple(kuzu::processor::FlatTuple* tuple) {
+  std::vector<std::unique_ptr<kuzu::common::Value>> ret;
+  for (uint32_t i = 0; i < tuple->len(); i++) {
+      ret.emplace_back(tuple->getValue(i)->copy());
+  }
+  return ret;
+}
+
+void mainFunction() {
+  std::unique_ptr<kuzu::main::QueryResult> result = conn->query("MATCH (p:person) RETURN p.*");
+  std::vector<std::vector<std::unique_ptr<kuzu::common::Value>>> tuples;
+  while (result->hasNext()) {
+      auto tuple = result->getNext();
+      tuples.emplace_back(copyFlatTuple(tuple.get()));
+  }
+  for (const auto& tuple : tuples) {
+      doSomething(tuple);
+  }
+}
+```
+
+## UDF API
+
 In addition to interfacing with the database, the C++ API offers users the ability to define custom
 functions via User Defined Functions (UDFs), described below.
 
-## UDF API
 Kùzu provides two interfaces that enable you to define your own custom scalar and vectorized functions.
 
 ### Scalar functions
@@ -211,7 +272,7 @@ conn->createVectorizedFunction<int64_t, int64_t>("addFour", &addFour);
 conn->query("MATCH (p:person) return addFour(p.age)");
 ```
 
-#### Option 2. Vectorized function with input and return type in Cypher 
+#### Option 2. Vectorized function with input and return type in Cypher
 
 Create a vectorized function with input and return type in Cypher.
 ```cpp
@@ -263,4 +324,4 @@ conn->query("MATCH (p:person) return addDate(p.birthdate, p.age)");
 
 ## Linking
 
-See the [C API Documentation](/client-apis/c#linking) for details as linking to the C++ API is more or less identical.
+See the [C API Documentation](/client-apis/c#linking) for details as linking to the C++ API is more or less identical.

src/content/docs/client-apis/java.mdx

@@ -10,3 +10,63 @@ See the following link for the full documentation of the Java API.
   title="Java API documentation"
   href="https://kuzudb.com/api-docs/java"
 />
+
+## Handling Kùzu output using `getNext()`
+
+For the examples in this section we will be using the following schema:
+```cypher
+CREATE NODE TABLE person(id INT64 PRIMARY KEY);
+```
+
+The `getNext()` function in a `QueryResult` returns a reference to the resulting `FlatTuple`. Additionally, to reduce resource allocation all calls to `getNext()` reuse the same
+FlatTuple object. This means that for a `QueryResult`, each call to `getNext()` actually overwrites the `FlatTuple` previously returned by the previous call to `getNext()`.
+
+Thus, we don't recommend using `QueryResult` like this:
+
+```java
+QueryResult result = conn.query("MATCH (p:person) RETURN p.*");
+List<FlatTuple> tuples = new ArrayList<FlatTuple>();
+while (result.hasNext()) {
+  // Each call to getNext() actually returns a reference to the same tuple object
+  tuples.add(result.getNext());
+}
+
+// This is wrong!
+// The list stores a bunch of references to the same underlying tuple object
+for (FlatTuple resultTuple: tuples) {
+  doSomething(resultTuple);
+}
+```
+
+Instead, we recommend processing each tuple immediately before making the next call to `getNext`:
+```java
+QueryResult result = conn.query("MATCH (p:person) RETURN p.*");
+while (result.hasNext()) {
+  FlatTuple tuple = result.getNext();
+  doSomething(tuple);
+}
+```
+
+If wish to process the tuples later, you must explicitly make a copy of each tuple:
+```java
+List<Value> copyFlatTuple(FlatTuple tuple, long tupleLen) throws ObjectRefDestroyedException {
+  List<Value> ret = new ArrayList<Value>();
+  for (int i = 0; i < tupleLen; i++) {
+      ret.add(tuple.getValue(i).clone());
+  }
+  return ret;
+}
+
+void mainFunction() throws ObjectRefDestroyedException {
+  QueryResult result = conn.query("MATCH (p:person) RETURN p.*");
+  List<List<Value>> tuples = new ArrayList<List<Value>>();
+  while (result.hasNext()) {
+    FlatTuple tuple = result.getNext();
+    tuples.add(copyFlatTuple(tuple, result.getNumColumns()));
+  }
+
+  for (List<Value> tuple: tuples) {
+    doSomething(tuple);
+  }
+}
+```