Improve docs for the array column (#106)

Author: mtopolnik

ci/run_all_tests.py

@@ -38,7 +38,7 @@ def main():
         build_dir.glob(f'**/test_line_sender{exe_suffix}')))
     build_cxx20_dir = pathlib.Path('build_CXX20')
     test_line_sender_path_CXX20 = next(iter(
-        build_cxx20_dir.glob(f'**/test_line_sender{exe_suffix}'))) 
+        build_cxx20_dir.glob(f'**/test_line_sender{exe_suffix}')))
 
     system_test_path = pathlib.Path('system_test') / 'test.py'
     #qdb_v = '8.2.3'  # The version of QuestDB we'll test against.
@@ -55,7 +55,7 @@ def main():
     run_cmd(str(test_line_sender_path))
     run_cmd(str(test_line_sender_path_CXX20))
     #run_cmd('python3', str(system_test_path), 'run', '--versions', qdb_v, '-v')
-    run_cmd('python3', str(system_test_path), 'run', '--repo', './questdb_nd_arr', '-v')
+    run_cmd('python3', str(system_test_path), 'run', '--repo', './questdb', '-v')
 
 
 if __name__ == '__main__':

ci/run_tests_pipeline.yaml

@@ -56,13 +56,13 @@ stages:
             displayName: "Build Rust examples"
           ############################# temp for test begin #####################
           - script: |
-              git clone -b nd_arr --depth 1 https://github.com/questdb/questdb.git ./questdb_nd_arr
+              git clone --depth 1 https://github.com/questdb/questdb.git ./questdb
             displayName: git clone questdb
           - task: Maven@3
             displayName: "Compile QuestDB"
             inputs:
-              mavenPOMFile: 'questdb_nd_arr/pom.xml'
-              jdkVersionOption: '1.11'
+              mavenPOMFile: "questdb/pom.xml"
+              jdkVersionOption: "1.11"
               options: "-DskipTests -Pbuild-web-console"
           ############################# temp for test end ##################### 
           - script: python3 ci/run_all_tests.py
@@ -126,7 +126,7 @@ stages:
             submodules: false
           - template: compile.yaml
           - script: |
-              git clone -b nd_arr --depth 1 https://github.com/questdb/questdb.git
+              git clone --depth 1 https://github.com/questdb/questdb.git
             displayName: git clone questdb
           - task: Maven@3
             displayName: "Compile QuestDB"

include/questdb/ingress/line_sender.h

@@ -78,7 +78,7 @@ typedef enum line_sender_error_code
     /** Bad configuration. */
     line_sender_error_config_error,
 
-    /** Currently, only arrays with a maximum 32 dimensions are supported. */
+    /** QuestDB supports arrays of up to 32 dimensions. */
     line_sender_error_array_large_dim,
 
     /** ArrayView internal error, such as failure to get the size of a valid
@@ -413,6 +413,7 @@ line_sender_buffer_view line_sender_buffer_peek(
 
 /**
  * Start recording a new row for the given table.
+ *
  * @param[in] buffer Line buffer object.
  * @param[in] name Table name.
  */
@@ -425,6 +426,7 @@ bool line_sender_buffer_table(
 /**
  * Record a symbol value for the given column.
  * Make sure you record all the symbol columns before any other column type.
+ *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] value Column value.
@@ -440,6 +442,7 @@ bool line_sender_buffer_symbol(
 
 /**
  * Record a boolean value for the given column.
+ *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] value Column value.
@@ -455,6 +458,7 @@ bool line_sender_buffer_column_bool(
 
 /**
  * Record an integer value for the given column.
+ *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] value Column value.
@@ -470,6 +474,7 @@ bool line_sender_buffer_column_i64(
 
 /**
  * Record a floating-point value for the given column.
+ *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] value Column value.
@@ -485,6 +490,7 @@ bool line_sender_buffer_column_f64(
 
 /**
  * Record a string value for the given column.
+ *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] value Column value.
@@ -499,19 +505,19 @@ bool line_sender_buffer_column_str(
     line_sender_error** err_out);
 
 /**
- * Record a multidimensional array of double for the given column.
+ * Record a multidimensional array of `double` values for the given column.
  *
- * This API uses BYTE-LEVEL STRIDES where the stride values represent the
- * number of bytes between consecutive elements along each dimension.
+ * The values in the `strides` parameter represent the number of bytes
+ * between consecutive elements along each dimension.
  *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] rank Number of dimensions of the array.
  * @param[in] shape Array of dimension sizes (length = `rank`).
- *                   Each element must be a positive integer.
- * @param[in] strides Array strides.
- * @param[in] data_buffer First array element data.
- * @param[in] data_buffer_len Bytes length of the array data.
+ *                  Each element must be a positive integer.
+ * @param[in] strides Array strides, in the unit of bytes. Strides can be negative.
+ * @param[in] data_buffer Array data, laid out according to the provided shape and strides.
+ * @param[in] data_buffer_len Length of the array data block in bytes.
  * @param[out] err_out Set to an error object on failure (if non-NULL).
  * @return true on success, false on error.
  */
@@ -527,19 +533,19 @@ bool line_sender_buffer_column_f64_arr_byte_strides(
     line_sender_error** err_out);
 
 /**
- * Record a multidimensional array of double for the given column.
+ * Record a multidimensional array of `double` values for the given column.
  *
- * This function uses ELEMENT-LEVEL STRIDES where the stride values represent
- * the number of elements between consecutive elements along each dimension.
+ * The values in the `strides` parameter represent the number of elements
+ * between consecutive elements along each dimension.
  *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] rank Number of dimensions of the array.
  * @param[in] shape Array of dimension sizes (length = `rank`).
  *                   Each element must be a positive integer.
- * @param[in] strides Array strides.
- * @param[in] data_buffer First array element data.
- * @param[in] data_buffer_len Bytes length of the array data.
+ * @param[in] strides Array strides, in the unit of elements. Strides can be negative.
+ * @param[in] data_buffer Array data, laid out according to the provided shape and strides.
+ * @param[in] data_buffer_len Length of the array data block in bytes.
  * @param[out] err_out Set to an error object on failure (if non-NULL).
  * @return true on success, false on error.
  */
@@ -556,6 +562,7 @@ bool line_sender_buffer_column_f64_arr_elem_strides(
 
 /**
  * Record a nanosecond timestamp value for the given column.
+ *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] nanos The timestamp in nanoseconds since the Unix epoch.
@@ -571,6 +578,7 @@ bool line_sender_buffer_column_ts_nanos(
 
 /**
  * Record a microsecond timestamp value for the given column.
+ *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
  * @param[in] micros The timestamp in microseconds since the Unix epoch.
@@ -711,6 +719,7 @@ line_sender_opts* line_sender_opts_from_env(line_sender_error** err_out);
 /**
  * Create a new `line_sender_opts` instance with the given protocol,
  * hostname and port.
+ *
  * @param[in] protocol The protocol to use.
  * @param[in] host The QuestDB database host.
  * @param[in] port The QuestDB ILP TCP port.
@@ -1058,6 +1067,7 @@ bool line_sender_flush(
  *
  * To send and clear in one step, call `line_sender_flush` instead. Also,
  * see the docs on that function for more important details on flushing.
+ *
  * @param[in] sender Line sender object.
  * @param[in] buffer Line buffer object.
  * @return true on success, false on error.

include/questdb/ingress/line_sender.hpp

@@ -641,18 +641,19 @@ class line_sender_buffer
     }
 
     /**
-     * Record a multidimensional double-precision array for the given column.
+     * Record a multidimensional array for the given column.
      *
-     * @tparam B    Strides mode selector:
-     *              - `true` for byte-level strides
-     *              - `false` for element-level strides
-     * @tparam T    Element type (current only `double` is supported).
+     * @tparam B    Selects the unit used for the strides:
+     *              - `true`: the unit is bytes
+     *              - `false` the unit is elements
+     * @tparam T    Element type (currently only `double` is supported).
      * @tparam N    Number of elements in the flat data array
      *
      * @param name    Column name.
      * @param shape   Array dimensions (e.g., [2,3] for a 2x3 matrix).
-     * @param data    Array first element data. Size must match product of
-     * dimensions.
+     * @param strides Strides for each dimension, in the unit specified by `B`.
+     * @param data    Array elements laid out in row-major order. Their number must
+     *                match the product of dimension sizes.
      */
     template <bool B, typename T, size_t N>
     line_sender_buffer& column(