Add C++ query builder (#4664)

# Description of Changes
- Added a query builder for C++ module bindings
  - Added query-builder table/filter/join types
- Added semijoin support with compile-time checks for lookup-table and
indexed-field usage
  - Added support for returning query-builder queries from C++ views
- Hooked query-builder metadata into the C++ table/view macros and V10
module-def path
- Added test coverage for the new C++ query-builder behavior
  - Compile tests for pass/fail cases
  - SQL tests for generated query output
  - Added a C++ test module for view primary key coverage
- **Update:** Switched the core to pass the columns and index-columns
metadata with the table source for better client-side codegen to have
some shared code between server + client.
# API and ABI breaking changes
- No intended API or ABI breaking changes
- Adds a new public query-builder API to the C++ bindings
- C++ views can now return query-builder query types in addition to
materialized row results

# Expected complexity level and risk

3 - Mostly contained to C++ bindings, but it touches macros, view
registration/serialization, and module-def generation, so there are a
few places where the pieces need to stay in sync.

# Testing

I've done end to end testing of I think every type as well as built some
tests to confirm the SQL output.

- [x] Run the C++ query-builder SQL tests
[crates/bindings-cpp/tests/query-builder-compile/run_query_builder_compile_tests.sh]
- [x] Smoke test a generated C++ module using query-builder views

---------

Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Ryan <r.ekhoff@clockworklabs.io>
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

Author: 3 people

crates/bindings-cpp/include/spacetimedb.h

@@ -138,6 +138,7 @@
 
 // View context and macros
 #include "spacetimedb/view_macros.h"
+#include "spacetimedb/query_builder.h"
 
 // =============================================================================
 // CONVENIENCE ALIASES AND COMPATIBILITY

crates/bindings-cpp/include/spacetimedb/client_visibility_filter.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include "spacetimedb/query_builder.h"
+
 #include <string>
 
 namespace SpacetimeDB {
@@ -21,21 +23,33 @@ namespace SpacetimeDB {
 /// will be reported during `spacetime publish`, not at compile time.
 class Filter {
 private:
-    const char* sql_text_;
+    std::string sql_text_;
 
 public:
     /// Create a SQL-based client visibility filter
     static Filter Sql(const char* sql) {
         return Filter(sql);
     }
 
+    /// Create a SQL-based client visibility filter from an owned string
+    static Filter Sql(std::string sql) {
+        return Filter(std::move(sql));
+    }
+
+    /// Create a SQL-based client visibility filter from a typed query-builder value.
+    template<query_builder::QueryLike TQuery>
+    static Filter Sql(const TQuery& query) {
+        return Filter(query.into_sql());
+    }
+
     /// Get the SQL text for this filter
-    const char* sql_text() const {
+    const std::string& sql_text() const {
         return sql_text_;
     }
 
 private:
-    explicit Filter(const char* sql) : sql_text_(sql) {}
+    explicit Filter(const char* sql) : sql_text_(sql != nullptr ? sql : "") {}
+    explicit Filter(std::string sql) : sql_text_(std::move(sql)) {}
 };
 
-} // namespace SpacetimeDB
+} // namespace SpacetimeDB

crates/bindings-cpp/include/spacetimedb/internal/Module.h

@@ -115,6 +115,7 @@ class Module {
 public:
     // Registration support routed through the V10 module-definition builder.
     static void RegisterClientVisibilityFilter(const char* sql);
+    static void RegisterClientVisibilityFilter(const std::string& sql);
     static void SetCaseConversionPolicy(CaseConversionPolicy policy);
     static void RegisterExplicitTableName(const std::string& source_name, const std::string& canonical_name);
     static void RegisterExplicitFunctionName(const std::string& source_name, const std::string& canonical_name);
@@ -152,6 +153,10 @@ class Module {
     static void RegisterClientVisibilityFilter(const char* sql) {
         Internal::Module::RegisterClientVisibilityFilter(sql);
     }
+
+    static void RegisterClientVisibilityFilter(const std::string& sql) {
+        Internal::Module::RegisterClientVisibilityFilter(sql);
+    }
 
     // Module metadata (future extension)
     static void SetMetadata([[maybe_unused]] const char* name, [[maybe_unused]] const char* version) {

crates/bindings-cpp/include/spacetimedb/internal/v10_builder.h

@@ -34,6 +34,7 @@
 #include "autogen/RawRowLevelSecurityDefV9.g.h"
 #include "autogen/RawTypeDefV10.g.h"
 #include "field_registration.h"
+#include "../query_builder.h"
 #include "buffer_pool.h"
 #include "runtime_registration.h"
 #include "template_utils.h"
@@ -466,10 +467,14 @@ class V10Builder {
                 [func](ViewContext& ctx, BytesSource args_source) -> std::vector<uint8_t> {
                     (void)args_source;
                     auto result = func(ctx);
-                    auto result_vec = view_result_to_vec(std::move(result));
                     IterBuf buf = IterBuf::take();
-                    {
-                        bsatn::Writer writer(buf.get());
+                    bsatn::Writer writer(buf.get());
+                    if constexpr (query_builder::QueryBuilderReturn<ReturnType>) {
+                        writer.write_u8(1);
+                        bsatn::serialize(writer, result.into_sql());
+                    } else {
+                        writer.write_u8(0);
+                        auto result_vec = view_result_to_vec(std::move(result));
                         bsatn::serialize(writer, result_vec);
                     }
                     return buf.release();
@@ -480,10 +485,14 @@ class V10Builder {
                 [func](AnonymousViewContext& ctx, BytesSource args_source) -> std::vector<uint8_t> {
                     (void)args_source;
                     auto result = func(ctx);
-                    auto result_vec = view_result_to_vec(std::move(result));
                     IterBuf buf = IterBuf::take();
-                    {
-                        bsatn::Writer writer(buf.get());
+                    bsatn::Writer writer(buf.get());
+                    if constexpr (query_builder::QueryBuilderReturn<ReturnType>) {
+                        writer.write_u8(1);
+                        bsatn::serialize(writer, result.into_sql());
+                    } else {
+                        writer.write_u8(0);
+                        auto result_vec = view_result_to_vec(std::move(result));
                         bsatn::serialize(writer, result_vec);
                     }
                     return buf.release();
@@ -492,8 +501,17 @@ class V10Builder {
         }
 
         auto& type_reg = getModuleTypeRegistration();
-        auto bsatn_return = bsatn::bsatn_traits<ReturnType>::algebraic_type();
-        AlgebraicType return_type = type_reg.registerType(bsatn_return, "", &typeid(ReturnType));
+        AlgebraicType return_type = [&]() {
+            if constexpr (query_builder::QueryBuilderReturn<ReturnType>) {
+                using RowType = query_builder::query_row_type_t<ReturnType>;
+                auto row_bsatn = bsatn::bsatn_traits<RowType>::algebraic_type();
+                auto row_type = type_reg.registerType(row_bsatn, "", &typeid(RowType));
+                return MakeQueryReturnAlgebraicType(std::move(row_type));
+            } else {
+                auto bsatn_return = bsatn::bsatn_traits<ReturnType>::algebraic_type();
+                return type_reg.registerType(bsatn_return, "", &typeid(ReturnType));
+            }
+        }();
         bool is_anonymous = std::is_same_v<ContextType, AnonymousViewContext>;
         uint32_t index = static_cast<uint32_t>(is_anonymous ? (GetAnonymousViewHandlerCount() - 1) : (GetViewHandlerCount() - 1));
 
@@ -658,6 +676,7 @@ class V10Builder {
                                                uint16_t field_idx) const;
     static AlgebraicType MakeUnitAlgebraicType();
     static AlgebraicType MakeStringAlgebraicType();
+    static AlgebraicType MakeQueryReturnAlgebraicType(AlgebraicType row_type);
 
     std::vector<std::pair<std::string, bool>> table_is_event_;
     std::optional<CaseConversionPolicy> case_conversion_policy_;