add line_sender_c_example_array_elem_strides api

kafka1991 · kafka1991 · commit 1ed8d6c49456 · 2025-05-23T23:10:21.000+08:00
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -100,9 +100,13 @@ if (QUESTDB_TESTS_AND_EXAMPLES)
         examples/concat.c
         examples/line_sender_c_example.c)
     compile_example(
-        line_sender_c_example_array
+        line_sender_c_example_array_byte_strides
         examples/concat.c
-        examples/line_sender_c_example_array.c)
+        examples/line_sender_c_example_array_byte_strides.c)
+    compile_example(
+        line_sender_c_example_array_elem_strides
+        examples/concat.c
+        examples/line_sender_c_example_array_elem_strides.c)
     compile_example(
         line_sender_c_example_auth
         examples/concat.c
@@ -129,8 +133,11 @@ if (QUESTDB_TESTS_AND_EXAMPLES)
         line_sender_cpp_example
         examples/line_sender_cpp_example.cpp)
     compile_example(
-        line_sender_cpp_example_array
-        examples/line_sender_cpp_example_array.cpp)
+        line_sender_cpp_example_array_byte_strides
+        examples/line_sender_cpp_example_array_byte_strides.cpp)
+    compile_example(
+        line_sender_cpp_example_array_elem_strides
+        examples/line_sender_cpp_example_array_elem_strides.cpp)
     compile_example(
         line_sender_cpp_example_auth
         examples/line_sender_cpp_example_auth.cpp)
diff --git a/cpp_test/test_line_sender.cpp b/cpp_test/test_line_sender.cpp
@@ -178,23 +178,38 @@ TEST_CASE("line_sender c api basics")
         2.7,
         48121.5,
         4.3};
-    CHECK(::line_sender_buffer_column_f64_arr(
-        buffer,
-        arr_name,
-        rank,
-        shape,
-        strides,
-        reinterpret_cast<uint8_t*>(arr_data.data()),
-        sizeof(arr_data),
-        &err));
+    CHECK(
+        ::line_sender_buffer_column_f64_arr_byte_strides(
+            buffer,
+            arr_name,
+            rank,
+            shape,
+            strides,
+            reinterpret_cast<uint8_t*>(arr_data.data()),
+            sizeof(arr_data),
+            &err));
+
+    line_sender_column_name arr_name2 = QDB_COLUMN_NAME_LITERAL("a2");
+    intptr_t elem_strides[] = {6, 2, 1};
+    CHECK(
+        ::line_sender_buffer_column_f64_arr_elem_strides(
+            buffer,
+            arr_name2,
+            rank,
+            shape,
+            elem_strides,
+            reinterpret_cast<uint8_t*>(arr_data.data()),
+            sizeof(arr_data),
+            &err));
     CHECK(::line_sender_buffer_at_nanos(buffer, 10000000, &err));
     CHECK(server.recv() == 0);
-    CHECK(::line_sender_buffer_size(buffer) == 150);
+    CHECK(::line_sender_buffer_size(buffer) == 266);
     CHECK(::line_sender_flush(sender, buffer, &err));
     ::line_sender_buffer_free(buffer);
     CHECK(server.recv() == 1);
     std::string expect{"test,t1=v1 f1=="};
     push_double_to_buffer(expect, 0.5).append(",a1==");
+    push_double_arr_to_buffer(expect, arr_data, 3, shape).append(",a2==");
     push_double_arr_to_buffer(expect, arr_data, 3, shape).append(" 10000000\n");
     CHECK(server.msgs(0) == expect);
 }
@@ -264,19 +279,23 @@ TEST_CASE("line_sender c++ api basics")
         2.7,
         48121.5,
         4.3};
+    std::vector<intptr_t> elem_strides{6, 2, 1};
     buffer.table("test")
         .symbol("t1", "v1")
         .symbol("t2", "")
         .column("f1", 0.5)
-        .column("a1", rank, shape, strides, arr_data)
+        .column<true>("a1", rank, shape, strides, arr_data)
+        .column<false>("a2", rank, shape, elem_strides, arr_data)
         .at(questdb::ingress::timestamp_nanos{10000000});
 
     CHECK(server.recv() == 0);
-    CHECK(buffer.size() == 154);
+    CHECK(buffer.size() == 270);
     sender.flush(buffer);
     CHECK(server.recv() == 1);
     std::string expect{"test,t1=v1,t2= f1=="};
     push_double_to_buffer(expect, 0.5).append(",a1==");
+    push_double_arr_to_buffer(expect, arr_data, 3, shape.data())
+        .append(",a2==");
     push_double_arr_to_buffer(expect, arr_data, 3, shape.data())
         .append(" 10000000\n");
     CHECK(server.msgs(0) == expect);
diff --git a/examples/line_sender_c_example_array_byte_strides.c b/examples/line_sender_c_example_array_byte_strides.c
@@ -31,7 +31,7 @@ static bool example(const char* host, const char* port)
     buffer = line_sender_buffer_new_for_sender(sender);
     line_sender_buffer_reserve(buffer, 64 * 1024);
 
-    line_sender_table_name table_name = QDB_TABLE_NAME_LITERAL("market_orders");
+    line_sender_table_name table_name = QDB_TABLE_NAME_LITERAL("market_orders_byte_strides");
     line_sender_column_name symbol_col = QDB_COLUMN_NAME_LITERAL("symbol");
     line_sender_column_name book_col = QDB_COLUMN_NAME_LITERAL("order_book");
 
@@ -60,7 +60,7 @@ static bool example(const char* host, const char* port)
         48121.5,
         4.3};
 
-    if (!line_sender_buffer_column_f64_arr(
+    if (!line_sender_buffer_column_f64_arr_byte_strides(
             buffer,
             book_col,
             array_rank,
diff --git a/examples/line_sender_c_example_array_elem_strides.c b/examples/line_sender_c_example_array_elem_strides.c
@@ -0,0 +1,99 @@
+#include <questdb/ingress/line_sender.h>
+#include <stdio.h>
+#include <stdbool.h>
+#include <string.h>
+#include "concat.h"
+
+static bool example(const char* host, const char* port)
+{
+    line_sender_error* err = NULL;
+    line_sender* sender = NULL;
+    line_sender_buffer* buffer = NULL;
+    char* conf_str = concat("tcp::addr=", host, ":", port, ";protocol_version=2;");
+    if (!conf_str)
+    {
+        fprintf(stderr, "Could not concatenate configuration string.\n");
+        return false;
+    }
+
+    line_sender_utf8 conf_str_utf8 = {0, NULL};
+    if (!line_sender_utf8_init(
+            &conf_str_utf8, strlen(conf_str), conf_str, &err))
+        goto on_error;
+
+    sender = line_sender_from_conf(conf_str_utf8, &err);
+    if (!sender)
+        goto on_error;
+
+    free(conf_str);
+    conf_str = NULL;
+
+    buffer = line_sender_buffer_new_for_sender(sender);
+    line_sender_buffer_reserve(buffer, 64 * 1024);
+
+    line_sender_table_name table_name = QDB_TABLE_NAME_LITERAL("market_orders_elem_strides");
+    line_sender_column_name symbol_col = QDB_COLUMN_NAME_LITERAL("symbol");
+    line_sender_column_name book_col = QDB_COLUMN_NAME_LITERAL("order_book");
+
+    if (!line_sender_buffer_table(buffer, table_name, &err))
+        goto on_error;
+
+    line_sender_utf8 symbol_val = QDB_UTF8_LITERAL("BTC-USD");
+    if (!line_sender_buffer_symbol(buffer, symbol_col, symbol_val, &err))
+        goto on_error;
+
+    size_t array_rank = 3;
+    uintptr_t array_shape[] = {2, 3, 2};
+    intptr_t array_strides[] = {6, 2, 1};
+
+    double array_data[] = {
+        48123.5,
+        2.4,
+        48124.0,
+        1.8,
+        48124.5,
+        0.9,
+        48122.5,
+        3.1,
+        48122.0,
+        2.7,
+        48121.5,
+        4.3};
+
+    if (!line_sender_buffer_column_f64_arr_elem_strides(
+            buffer,
+            book_col,
+            array_rank,
+            array_shape,
+            array_strides,
+            (const uint8_t*)array_data,
+            sizeof(array_data),
+            &err))
+        goto on_error;
+
+    if (!line_sender_buffer_at_nanos(buffer, line_sender_now_nanos(), &err))
+        goto on_error;
+
+    if (!line_sender_flush(sender, buffer, &err))
+        goto on_error;
+
+    line_sender_close(sender);
+    return true;
+
+on_error:;
+    size_t err_len = 0;
+    const char* err_msg = line_sender_error_msg(err, &err_len);
+    fprintf(stderr, "Error: %.*s\n", (int)err_len, err_msg);
+    free(conf_str);
+    line_sender_error_free(err);
+    line_sender_buffer_free(buffer);
+    line_sender_close(sender);
+    return false;
+}
+
+int main(int argc, const char* argv[])
+{
+    const char* host = (argc >= 2) ? argv[1] : "localhost";
+    const char* port = (argc >= 3) ? argv[2] : "9009";
+    return !example(host, port);
+}
diff --git a/examples/line_sender_cpp_example_array_byte_strides.cpp b/examples/line_sender_cpp_example_array_byte_strides.cpp
@@ -13,7 +13,7 @@ static bool array_example(std::string_view host, std::string_view port)
             "tcp::addr=" + std::string{host} + ":" + std::string{port} +
             ";protocol_version=2;");
 
-        const auto table_name = "cpp_market_orders"_tn;
+        const auto table_name = "cpp_market_orders_byte_strides"_tn;
         const auto symbol_col = "symbol"_cn;
         const auto book_col = "order_book"_cn;
         size_t rank = 3;
@@ -36,7 +36,7 @@ static bool array_example(std::string_view host, std::string_view port)
         questdb::ingress::line_sender_buffer buffer = sender.new_buffer();
         buffer.table(table_name)
             .symbol(symbol_col, "BTC-USD"_utf8)
-            .column(book_col, 3, shape, strides, arr_data)
+            .column<true>(book_col, 3, shape, strides, arr_data)
             .at(questdb::ingress::timestamp_nanos::now());
         sender.flush(buffer);
         return true;
diff --git a/examples/line_sender_cpp_example_array_elem_strides.cpp b/examples/line_sender_cpp_example_array_elem_strides.cpp
@@ -0,0 +1,62 @@
+#include <questdb/ingress/line_sender.hpp>
+#include <iostream>
+#include <vector>
+
+using namespace std::literals::string_view_literals;
+using namespace questdb::ingress::literals;
+
+static bool array_example(std::string_view host, std::string_view port)
+{
+    try
+    {
+        auto sender = questdb::ingress::line_sender::from_conf(
+            "tcp::addr=" + std::string{host} + ":" + std::string{port} +
+            ";protocol_version=2;");
+
+        const auto table_name = "cpp_market_orders_elem_strides"_tn;
+        const auto symbol_col = "symbol"_cn;
+        const auto book_col = "order_book"_cn;
+        size_t rank = 3;
+        std::vector<uintptr_t> shape{2, 3, 2};
+        std::vector<intptr_t> strides{6, 2, 8};
+        std::array<double, 12> arr_data = {
+            48123.5,
+            2.4,
+            48124.0,
+            1.8,
+            48124.5,
+            0.9,
+            48122.5,
+            3.1,
+            48122.0,
+            2.7,
+            48121.5,
+            4.3};
+
+        questdb::ingress::line_sender_buffer buffer = sender.new_buffer();
+        buffer.table(table_name)
+            .symbol(symbol_col, "BTC-USD"_utf8)
+            .column<false>(book_col, 3, shape, strides, arr_data)
+            .at(questdb::ingress::timestamp_nanos::now());
+        sender.flush(buffer);
+        return true;
+    }
+    catch (const questdb::ingress::line_sender_error& err)
+    {
+        std::cerr << "[ERROR] " << err.what() << std::endl;
+        return false;
+    }
+}
+
+int main(int argc, const char* argv[])
+{
+    auto host = "localhost"sv;
+    if (argc >= 2)
+        host = std::string_view{argv[1]};
+
+    auto port = "9009"sv;
+    if (argc >= 3)
+        port = std::string_view{argv[2]};
+
+    return !array_example(host, port);
+}
diff --git a/include/questdb/ingress/line_sender.h b/include/questdb/ingress/line_sender.h
@@ -499,7 +499,37 @@ bool line_sender_buffer_column_str(
 
 /**
  * Record a multidimensional array of double for the given column.
- * The array data must be stored in row-major order (C-style contiguous layout).
+ *
+ * This API uses BYTE-LEVEL STRIDES where the stride values 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.
+ * @param[out] err_out Set to an error object on failure (if non-NULL).
+ * @return true on success, false on error.
+ */
+LINESENDER_API
+bool line_sender_buffer_column_f64_arr_byte_strides(
+    line_sender_buffer* buffer,
+    line_sender_column_name name,
+    size_t rank,
+    const uintptr_t* shape,
+    const intptr_t* strides,
+    const uint8_t* data_buffer,
+    size_t data_buffer_len,
+    line_sender_error** err_out);
+
+/**
+ * Record a multidimensional array of double 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.
  *
  * @param[in] buffer Line buffer object.
  * @param[in] name Column name.
@@ -513,7 +543,7 @@ bool line_sender_buffer_column_str(
  * @return true on success, false on error.
  */
 LINESENDER_API
-bool line_sender_buffer_column_f64_arr(
+bool line_sender_buffer_column_f64_arr_elem_strides(
     line_sender_buffer* buffer,
     line_sender_column_name name,
     size_t rank,
diff --git a/include/questdb/ingress/line_sender.hpp b/include/questdb/ingress/line_sender.hpp
@@ -643,12 +643,18 @@ class line_sender_buffer
     /**
      * Record a multidimensional double-precision 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 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.
      */
-    template <typename T, size_t N>
+    template <bool B, typename T, size_t N>
     line_sender_buffer& column(
         column_name_view name,
         const size_t rank,
@@ -661,7 +667,8 @@ class line_sender_buffer
             "Only double types are supported for arrays");
         may_init();
         line_sender_error::wrapped_call(
-            ::line_sender_buffer_column_f64_arr,
+            B ? ::line_sender_buffer_column_f64_arr_byte_strides
+              : ::line_sender_buffer_column_f64_arr_elem_strides,
             _impl,
             name._impl,
             rank,
diff --git a/questdb-rs-ffi/src/lib.rs b/questdb-rs-ffi/src/lib.rs
diff --git a/questdb-rs-ffi/src/ndarr.rs b/questdb-rs-ffi/src/ndarr.rs
