From 0cd21544261efea45ec98cc5e4e98032e4a9bc76 Mon Sep 17 00:00:00 2001 From: Marko Topolnik Date: Tue, 3 Jun 2025 14:18:25 +0200 Subject: [PATCH 1/8] Improve doc for the array column --- include/questdb/ingress/line_sender.hpp | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/include/questdb/ingress/line_sender.hpp b/include/questdb/ingress/line_sender.hpp index 91fc33d6..f46635f2 100644 --- a/include/questdb/ingress/line_sender.hpp +++ b/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 line_sender_buffer& column( From 86afe1ecec90188094d88c206519843bdcae42fb Mon Sep 17 00:00:00 2001 From: Marko Topolnik Date: Wed, 4 Jun 2025 10:05:06 +0200 Subject: [PATCH 2/8] CI: go back to main branch --- ci/run_all_tests.py | 4 ++-- ci/run_tests_pipeline.yaml | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/ci/run_all_tests.py b/ci/run_all_tests.py index 4d7624f5..f051f177 100644 --- a/ci/run_all_tests.py +++ b/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__': diff --git a/ci/run_tests_pipeline.yaml b/ci/run_tests_pipeline.yaml index 03b8d129..1dd3924f 100644 --- a/ci/run_tests_pipeline.yaml +++ b/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" From c4d9d173d417bd8609c515850bddf2244fa0d9fc Mon Sep 17 00:00:00 2001 From: Marko Topolnik Date: Tue, 3 Jun 2025 14:49:07 +0200 Subject: [PATCH 3/8] Improve C docs for array --- include/questdb/ingress/line_sender.h | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/include/questdb/ingress/line_sender.h b/include/questdb/ingress/line_sender.h index 3efb424b..bda2d0d7 100644 --- a/include/questdb/ingress/line_sender.h +++ b/include/questdb/ingress/line_sender.h @@ -499,18 +499,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. + * Each element must be a positive integer. + * @param[in] strides Array strides, in the unit of bytes. + * @param[in] data_buffer Array elements laid out in row-major order. Their number + * must match the product of dimension sizes. * @param[in] data_buffer_len Bytes length of the array data. * @param[out] err_out Set to an error object on failure (if non-NULL). * @return true on success, false on error. @@ -527,10 +528,10 @@ 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. From 0ed1ec99f1595776abadd3e65d949f05dadd88a1 Mon Sep 17 00:00:00 2001 From: Marko Topolnik Date: Wed, 4 Jun 2025 10:07:47 +0200 Subject: [PATCH 4/8] Align docs of similar functions --- include/questdb/ingress/line_sender.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/include/questdb/ingress/line_sender.h b/include/questdb/ingress/line_sender.h index bda2d0d7..8bf89867 100644 --- a/include/questdb/ingress/line_sender.h +++ b/include/questdb/ingress/line_sender.h @@ -538,8 +538,9 @@ bool line_sender_buffer_column_f64_arr_byte_strides( * @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] strides Array strides, in the unit of elements. + * @param[in] data_buffer Array elements laid out in row-major order. Their number + * must match the product of dimension sizes. * @param[in] data_buffer_len Bytes length of the array data. * @param[out] err_out Set to an error object on failure (if non-NULL). * @return true on success, false on error. From 38cec49a801702c60ebe336f70862dd89d193f45 Mon Sep 17 00:00:00 2001 From: Marko Topolnik Date: Thu, 5 Jun 2025 14:01:00 +0200 Subject: [PATCH 5/8] Consistent vertical spacing in docs --- include/questdb/ingress/line_sender.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/include/questdb/ingress/line_sender.h b/include/questdb/ingress/line_sender.h index 8bf89867..87c0b8d0 100644 --- a/include/questdb/ingress/line_sender.h +++ b/include/questdb/ingress/line_sender.h @@ -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. @@ -558,6 +564,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. @@ -573,6 +580,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. @@ -713,6 +721,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. @@ -1060,6 +1069,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. From 9b250a6c2ed9cf0c9314e7a8a1b2244c01f3794f Mon Sep 17 00:00:00 2001 From: Marko Topolnik Date: Thu, 5 Jun 2025 14:01:29 +0200 Subject: [PATCH 6/8] Better wording for array dimensionality support --- include/questdb/ingress/line_sender.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/questdb/ingress/line_sender.h b/include/questdb/ingress/line_sender.h index 87c0b8d0..95b9c1c4 100644 --- a/include/questdb/ingress/line_sender.h +++ b/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 From 316b1bba50705d8db65dc8efebbca69064ee2357 Mon Sep 17 00:00:00 2001 From: Marko Topolnik Date: Thu, 5 Jun 2025 14:02:25 +0200 Subject: [PATCH 7/8] Fix docs for array data (it isn't in row-major order) --- include/questdb/ingress/line_sender.h | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/include/questdb/ingress/line_sender.h b/include/questdb/ingress/line_sender.h index 95b9c1c4..c76bed01 100644 --- a/include/questdb/ingress/line_sender.h +++ b/include/questdb/ingress/line_sender.h @@ -516,9 +516,8 @@ bool line_sender_buffer_column_str( * @param[in] shape Array of dimension sizes (length = `rank`). * Each element must be a positive integer. * @param[in] strides Array strides, in the unit of bytes. - * @param[in] data_buffer Array elements laid out in row-major order. Their number - * must match the product of dimension sizes. - * @param[in] data_buffer_len Bytes length of the array data. + * @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. */ @@ -545,9 +544,8 @@ bool line_sender_buffer_column_f64_arr_byte_strides( * @param[in] shape Array of dimension sizes (length = `rank`). * Each element must be a positive integer. * @param[in] strides Array strides, in the unit of elements. - * @param[in] data_buffer Array elements laid out in row-major order. Their number - * must match the product of dimension sizes. - * @param[in] data_buffer_len Bytes length of the array data. + * @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. */ From 99b6c31efca5f856d87a70516df2b0bc31b4051c Mon Sep 17 00:00:00 2001 From: Marko Topolnik Date: Thu, 5 Jun 2025 14:02:38 +0200 Subject: [PATCH 8/8] Emphasize that a stride can be negative --- include/questdb/ingress/line_sender.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/questdb/ingress/line_sender.h b/include/questdb/ingress/line_sender.h index c76bed01..8dab38d6 100644 --- a/include/questdb/ingress/line_sender.h +++ b/include/questdb/ingress/line_sender.h @@ -515,7 +515,7 @@ bool line_sender_buffer_column_str( * @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, in the unit of bytes. + * @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). @@ -543,7 +543,7 @@ bool line_sender_buffer_column_f64_arr_byte_strides( * @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, in the unit of elements. + * @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).